...
The Customization Manager now allows for addons to be uploaded with the Addon Type of "DesisionSupportDecisionSupport" and allows the Server addon to be registered to a specific NVTGC and Pipeline.
...
Addon Event Hooks
ILLiad now has 4 new event hooks (stage 3 consists of event hooks 3a and 3b) which allow the System Manager to trigger Decision Support addons whenever a request is run through a stage of a pipeline.
Decision Support addons can register to individual stages of the DSP by using the RegisterSystemEventHandleraddon function. For more information on the system script environment method of RegisterSystemEvenHandler see Environment Methods. For a more in-depth explanation of the RegisterSystemEvenHandler, see the Handling System Events article.
The following Event Hooks can be used with the DSP feature:
Event Hook: GatherInformation This event hook allows addons to populate additional fields in a Request Form (e.g., DOI, ISSN, etc.). |
Event Hook: GenerateFulfillmentData This event hook allows addons to generate fulfillment options for the request (e.g., item availability, cost, format), each creating a single FulfillmentData record in the FufillmentData Table of the Request Form. It is recommended that any addons that register for this event hook should also register to the AutomationDecision event hook. |
Event Hook: EvaluateBusinessRules This event hook allows addons to override the results of running pre-defined business rules with its own business rules. These addons are given access to the Recommendation record with the result of the business rules. From there, he addon is responsible for recording their own recommendations on the record. If no addons register to this event hook, then the business rules will be evaluated as normal. |
Event Hook: AutomationDecision This event hook allows addons to perform actions for the request without requiring staff intervention or review of the request. For example, sending the request to an external system such as Rapid or Relais for fulfillment. The automation occurs when a specific fulfillment option has been met and the request has been routed to Awaiting Pipeline Sending. |
...
Pipelines
When configuring DecisionSupport addons in Customization Manager, staff users will be responsible for selecting the registered Pipeline(s) for each addon. There are 3 request processing pipelines in the Decision Support Pipeline, which generate and evaluate Fulfillment Data for request records. There is also a final decision pipeline which that acts on the recommendation records. The final stage is only important to addon developers. In ILLiad, this pipeline is a segment of the other pipelines instead of being designated as its own pipeline.
...
Whenever a Request enters a pipeline, it will be executed against the Stages that are used in that pipeline, as mentioned above. If while processing a Transaction, any of the stages encounter a failure or an otherwise unsuccessful result, the Transaction a pipeline, it will be executed against the Stages that are used in that pipeline, as mentioned above. As of ILLiad v9.2, if while processing a Transaction, any of the stages encounter an error (e.g., a 404 response from an external server), the Transaction will be handled in one of the following ways:
If the addon encounters an error that's handled by an OnError function written into the addon, the request(s) will be routed to the error queue associated with that pipeline only if the OnError function re-throws the error. If the error is not re-thrown, the DSP will assume that the addon was not able to process the request and it will be sent to other addons for processing (if applicable).
If the addon encounters an error that isn't handled, the request(s) will be routed to the error queue associated with that pipeline.
Once a request has been routed to an error queue, that will conclude the pipeline’s processing for that Request. The request will need to be reviewed by staff to determine if the request should be routed to an input queue that will send it back into the pipeline or manually processed.
...
Handled (bool): Indicates that the addon was able to successfully modify the Transaction record.
Workflow
The System Manager will create a list of all the active addons that (a) are registered to the current pipeline, (b) are registered to an NVTGC that matches the NVTGC for the Request, and (c) have registered to the GatherInformation event hook.
The System Manager will then execute all the addons in that list in a round.
If any of the addons set the “Handled” flag of their event argument to true, they will be removed from the list for the next round.
The System Manager will keep executing addons in that list until the list is empty, or none of the addons reported “Handled” during a single round.
...
2. Fulfillment Data Generation Stage
...
Handled (bool): Indicates that the addon has successfully processed the request and would like System Manager to create a Fulfillment Data record for the Request.
Available (bool): Specifies whether the fulfillment option is available in the external system.
CopyrightIncluded (bool): Specifies whether the copyright is included with the fulfillment option.
Cost (decimal): Specifies the cost of the fulfillment option, in USD.
TurnaroundTime (int): Specifies how long it will take to fulfill the fulfillment option.
Format (string): Specifies the format of the fulfillment option (e.g., JPG, PDF, PNG).
CustomData (string): JSON data, formatted as a string. Created and read by DecisionSupport addons. It is recommended that addons populate this property with any data that the addon will need when requesting the fulfillment options from the external system. It is also recommended that the data should be formatted as JSON, but that is not enforced.
Notes (string): General plaintext notes that should be readable by staff users.
Workflow
The System Manager will create a list of all the active addons that (a) are registered to the current pipeline, (b) are registered to an NVTGC that matches the NVTGC for the Request, and (c) have registered to the GenerateFulfillmentData event hook.
The System Manager will then execute all the selected addons.
If an addon sets the “Handled” flag of their event argument to true, then System Manager will create a Fulfillment Data record for the addon.
...
3a. Business Rule Evaluation Stage
This stage of the Decision Support Pipeline evaluates pre-defined business rules, which compare different fulfillment options against each other. This stage of the Decision Support Pipeline also allows an addon to override the pre-defined business rules, allowing a single addon to compare different FulfillmentData records. Any rules in the addon take priority over rules set in the Customization Manager.
...
EvaluatePredefinedBusinessRules (method): This property is a callable function that returns an object that describes the result that will be generated if the pre-defined business rules are executed. The object that is returned has the following properties.
Automatic (bool): Determines whether the business rule would like the recommendation to be automatically executed, or if the decision should be sent to a staff user for review.
AddonTarget (int): Specifies the Addon that this recommendation is targeting. If this is null, then either the recommendation uses QueueTarget, or the linked Addon was deleted.
QueueTarget (string): Specifies the Queue that the addon should be routed to. If this is null, then the recommendation uses AddonTarget.
Notes (string): Specifies human-readable plaintext notes that indicate the source of the recommendation.
Addon Workflow
The System Manager will create a list of all the active addons that (a) are registered to the current pipeline, (b) are registered to an NVTGC that matches the NVTGC for the Request, and (c) have registered to the EvaluateBusinessRules event hook.
The System Manager will then attempt to execute an addon that has registered to the event hook.
If an addon reports that it has handled the event, System Manager will then validate the resulting recommendation.
If the recommendation is not valid, System Manager will route the request to the error queue for the pipeline.
If no addons report to have handled the event, then System Manager will move on to evaluating the pre-defined business rules instead.
| Note |
|---|
The ordering of the addons that are considered for this stage is not defined. If 2 addons register for this stage’s event hook, there is no way to guarantee which one will execute. It is recommended that only one addon registers to this event hook, for each NVTGC. |
For more information on how business rules work with the System Manager, see Business Rule Evaluation & the System Manager.
...
3b. Automation Decision Stage
This stage of the Decision Support Pipeline operates on requests from the “Awaiting Pipeline Sending” Queue. The System Manager will record a business rule evaluation as either Automatic or Recommended in the new DecisionSupportPipelineRecommendations database table which will act as the Recommendation Record. The stage evaluates each request’s Recommendation Record, either routing the request to the queue specified by the Recommendation’s QueueTarget or executing the DecisionSupport Addon specified by the Recommendation’s Target.
...
Handled (bool): Indicates that the addon has successfully processed the request.
Available (bool): Specifies whether the fulfillment option is available in the external system.
CopyrightIncluded (bool): Specifies whether the copyright is included with the fulfillment option.
Cost (decimal): Specifies the cost of the fulfillment option, in USD.
TurnaroundTime (int): Specifies how long it will take to fulfill the fulfillment option.
Format (string): Specifies the format of the fulfillment option (e.g., JPG, PDF, PNG).
CustomData (string): JSON data, formatted as a string. Created and read by DecisionSupport addons. It is recommended that addons populate this property with any data that the addon will need when requesting the fulfillment options from the external system. It is also recommended that the data should be formatted as JSON, but that is not enforced.
Notes (string): General plaintext notes that should be readable by staff users.
Workflow
From the “Awaiting Pipeline Sending” Queue, the System Manager will pull all Borrowing Requests along with the Recommendation records that are linked to the Requests.
For each request, the System Manager will validate the Recommendation.
If the recommendation passes validation-
If the QueueTarget property of the Request’s Recommendation record is set, then System Manager will automatically route the request to the specified Queue.
If the QueueTaget is not set, the System Manager will populate the properties of the event argument and will trigger the addon that is specified in the Recommendation’s AddonTarget property.
If the addon does not handle the event or does not route the Request, System Manager will route the Request to the “Awaiting Pipeline Error Review”. The result of this stage concludes the Request’s route through the Decision Support Pipeline unless the request is routed back to one of the input queues of the Decision Support Pipeline.
If the recommendation doesn't pass validation- the request will be routed to the “Awaiting Pipeline Error Review” queue if its Recommendation does not pass validation.
If neither target is specified, then the recommendation doesn’t specify any actions that the Automation Decision stage can take, which describes an Error.
If both targets specified, this is an ambiguous recommendation, which is an error since the Automation Decision stage can’t do both.
| Note |
|---|
Addons that register to the AutomationDecision event hook should also register to the GenerateFulfillmentData event hook. If a DecisionSupport addon does not register to the GenerateFulfillmentData event hook, it will never generate any fulfillment options, so System Manager will never ask it to run during the AutomationDecision event. |
...