This article is a reference guide for addon developers who are creating addons for the Decision Support Pipeline (DSP). The guide will include changes to the System Manager and a better understanding of the Transaction Record workflows as it moves throughout the system. For a more general overview of the DSP process, see Decision Support Pipeline Overview.
There are currently no Lending Processing or DocDel pipelines but the pipelines and addons in the feature are designed to support additional process types. The goal is to help make development in the future an easier transition if new pipelines and workflows were to be added.
Decision Support Addons | Business Rules | Addon Event Hooks | Pipelines | Pipeline Stages
The Customization Manager now allows for addons to be uploaded with the Addon Type of "DecisionSupport" and allows the Server addon to be registered to a specific NVTGC and Pipeline.
Addon Type: The new addon type, DecisionSupport, lets ILLiad know the addon is being used with the Decision Support feature. This new addon type is similar to ILLiad’s Server addon type in how it's uploaded and how it functions, except with a few new features.
NVTGC: Decision Support addons are registered to a single NVTGC, meaning that the addon will only be able to see and process requests within a specific NVTGC, allowing individual sites to control which addons they want to use in their pipeline.
Since each addon is associated with a specific NVTGC, each institution's pipeline workflow may look different even though the addon is uploaded to the server.
Pipeline: Decision Support addons can be registered to a specific Decision Support Pipeline(s). The addon will only process Requests in the designated pipeline. If multiple NVTGCS require the same addon, it will need to be uploaded multiple times and assigned a separate NVTGC for each site.
The Business Rule Evaluation stage of the DSP evaluates user-defined business rules against individual requests, allowing the System Manager to compare different fulfillment options for each request. Business Rules filter out different fulfillment options, by evaluating the Business Rule’s MatchString against the Request’s current state and information gathered after running the addons. The match strings for Business Rules are evaluated as boolean SQL statements that work similarly to how the match string works for Routing Rules.
The following joins and aliases are used in the business rule match string:
Transactions Table filtered to return only the Current Request is aliased as “t”.
Users Table joined to the Transactions Table is aliased as “u”.
FulfillmentData Table joined to the Transactions Table is aliased as “fd”.
After the fulfillment options have been filtered and the request is in the Business Rule stage, the System Manager will use the Target properties of each Business Rule to select a recommended action. Details regarding how these Business Rules are evaluated are included in the Workflow section of the Business Rule Evaluation Stage below.
u.Status = 'Faculty' and fd.Cost <= 10 and t.NotWantedAfter > DATEADD(DAY, 5, GETDATE()) |
In the example, the request would be filtered based on the Users who are "Faculty", the cost (of the fulfillment option) being less than or equal to $10, and the Transaction's NotWantedAfter being no more than 5 days from the current date.
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. |
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 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.
Each of these pipelines is associated with a designated set of Stages that will run the addons and add information or send the request, based on the Process Type (Borrowing, DocDel, Lending), Request Type (Article, Loan), and which queue it's in (input queue). If any problem occurs during one of the stages, then the request will be sent to the appropriate error queue for staff review.
Borrowing Article Pre-Copyright- This pipeline applies to requests that are in the input queue of Awaiting Pre-Copyright Pipeline, have a Process Type of Borrowing, and a Request Type of Article.
Stage(s): Information Gathering, Fulfillment Data Generation, Business Rule Evaluation
Error Queue: Pre-Copyright Pipeline Errors
Borrowing Article: This pipeline applies to requests that are in the input queue of Awaiting Request Pipeline, have a Process Type of Borrowing, and a Request Type of Article.
Stage(s): Information Gathering, Fulfillment Data Generation, Business Rule Evaluation
Error Queue: Awaiting Pipeline Error Review
Borrowing Loan: This pipeline applies to requests that are in the input queue of Awaiting Request Pipeline, have a Process Type of Borrowing, and a Request Type of Loan.
Stage(s): Information Gathering, Fulfillment Data Generation, Business Rule Evaluation
Error Queue: Awaiting Pipeline Error Review
Automation Decision: This pipeline applies to requests that are in the input queue of Awaiting Pipeline Sending, have a Process Type of Borrowing, and a Request Type of Article or Loan. This pipeline acts on a Request’s Recommendation record, which is often the result of a Request being processed by one of the other pipelines. When uploading an addon to the Customization Manager, this queue does not exist because it operates the same as the Borrowing Article and Borrowing Loan pipelines and has the same error queue. This pipeline was necessary to handle the backend workflow for requests that can leave a pipeline and enter a queue that allows staff users to review the request before kicking it into a queue for sending or selecting the recommended fulfillment option.
Stage(s): Automation Decision
Error Queue: Awaiting Pipeline Error Review
Whenever a Request enters 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.
All stages of the Decision Support Pipeline communicate with DecisionSupport addons, so the functions that are registered to any stages of the Decision Support Pipeline should accept a single parameter. Each stage of the Decision Support Pipeline has a distinct schema that it will populate before handing the event argument object to the addon.
This stage of the Decision Support Pipeline allows addons to add additional information to the Request Form. For example, an addon could look up additional information for a Request based on a DOI number.
Handled (bool): Indicates that the addon was able to successfully modify the Transaction record.
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.
This stage of the Decision Support Pipeline allows addons to generate fulfillment options for Requests. This information is stored in a new data table in ILLiad called the FulfillmentData table.
The event arguments for this stage include a “Handled” property, along with the non-metadata fields from the FulfillmentData model. Not all FufillmentData model properties are included in this stage's event arguments (e.g., ID, Source, and TransactionNumber fields).
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.
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.
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.
The model will first evaluate the argument properties for the addon before evaluating the business rule argument properties.
Addon Arguments:
FulfillmentData (ICollection of FulfillmentData records): Unlike the Fulfillment Data Generation and the Automation Decision stages, which include a subset of the fields (does not include ID, Source, and TransactionNumber fields) from the FulfillmentData model, the event arguments for this stage include a .NET ICollection that contains all of the fields from the FulfillmentData model. The addon will be able to compare records for the collection against each other, while also having access to Request and User data when making a recommendation. This model has the following properties:
ID (int): Specifies the database identifier for the FulfillmentData.
Source (int): Specifies the DecisionSupport addon that generated the fulfillment option.
TransactionNumber (int): Specifies the Request that the fulfillment option applies to.
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, which is not enforced behavior.
Automatic (bool): Determines whether the addon 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 QueueTarget is specified, or the linked Addon was deleted. When setting this value, the addon should pull the Source field from the from an element from the ICollection of FulfillmentData records.
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.
Business Rule Arguments:
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.
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.
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.
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.
The event arguments for this stage include a “Handled” property, along with the non-metadata fields from the FulfillmentData model. Not all FufillmentData model properties are included in this stage's event arguments (e.g., ID, Source, and TransactionNumber fields). For this stage, the only property that should be written to is the “Handled” property. For example, eventArgs.Handled=true. All the other properties are intended to allow the addon to access all the data it generated during its Fulfillment Data Generation stage.
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.
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.
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. |
Addons are expected to route Requests during this stage of the pipeline. If the DecisionSupport addon does not route the Request, System Manager will route the Request to the “Awaiting Pipeline Error Review” Queue once the addon has completed. |