/
ILLiad LibKey Server Addon

ILLiad LibKey Server Addon

Owned by Brittany de Gail
Last updated: Dec 19, 2024 by Stephanie Spires
6 min read

This addon can be configured as a Decision Support Pipeline Addon or as a Server Addon and is installed using the ILLiad Customization Manager. See Installing and Configuring ILLiad Server Addons for more information. For more information on the Decision Support Pipeline, see Decision Support Pipeline Overview.

If used with the Decision Support Pipeline, this is a stage 2 & 3 DSP addon. For more information on stages, see Decision Support Pipeline Overview.

Name

LibKey Server Addon

Version

1.0.0

Author

Atlas Systems, Inc.

Description

The ILLiad LibKey addon is a Decision Support Pipeline (DSP) server addon that helps automate fulfillment through the LibKey service. It will process ILLiad requests placed in the Borrowing Article or Borrowing Article Pre-Copyright DSP pipelines or in a specified search queue, automatically initiate a search of the LibKey database for the item using either the DOI or PMID value on the ILLiad request, and if the item is available, save the LibKey access URL for the item to a specified ILLiad Transaction field and deliver the URL to the patron using a specified email template.

Download

Release Notes

  • v1.0.0:

    • Initial release

Configuration

In order to use this addon, the ThirdIronAPIKey, ThirdIronCustomerAPIKey, and DeliveryEmailTemplate settings must first be configured with values. A LibKey subscription is required to obtain the API key values; current subscribers to the LibKey service can obtain these values by contacting Third Iron at support@thirdiron.com. The DeliveryEmailTemplate setting should contain the name of the email template configured in the ILLiad Customization Manager that will be used to deliver the LibKey access URL for requests that are successfully processed and filled by the LibKey addon. Note that this email template should be configured to deliver the URL to the requesting patron using the ILLiad field specified in the LibKeyUrlField setting (default: Location), which is where the URL will be saved by the addon.

Name

Type

Default

Description

Name

Type

Default

Description

ThirdIronAPIKey

String

 

The API Key for authenticating to LibKey that identifies interactions occurring coming from ILLiad.

ThirdIronCustomerAPIKey

String

 

The API Key for authenticating to LibKey that identifies the designated Library ID supplied by Third Iron.

LibKeyUrlField

String

Location

The name of the ILLiad field on the Transaction form where the LibKey URL will be saved.

DeliveryEmailTemplate

String

 

The name of the delivery email template to be used to deliver the link.

DeliveredQueue

String

Request Finished

The name of the queue that requests will be routed to when a link is found and delivered.

LibKeySearchingMonitorQueue

String

Awaiting LibKey Search

Defines the ILLiad status that the addon will monitor for requests that it should check the LibKey API.

NotFoundQueue

String

Awaiting Request Processing

This defines the ILLiad status that requests will be routed to when an item is not found in LibKey.

ErrorQueue

String

LibKey Error Processing

This defines the ILLiad status that requests will be routed to when the addon encounters an error that cannot be automatically resolved.

Server Addon Information

Server Addon - Workflow

  1. The addon will monitor requests in the ILLiad status defined in the LibKeySearchingMonitorQueue setting.

  2. For requests in that status, the addon will check LibKey to see if the requested article is available to be filled through the LibKey service. It will search for requests using bibliographic data with the following precedence:

    1. by DOI if the ILLiad request has a value in DOI.

    2. by PMID if a DOI value is not present on the ILLiad request or if the DOI search returns no results.

  3. If the requested article is found in the LibKey database and can be filled through the LibKey service, the LibKey access URL will be generated and saved to the ILLiad field designated in the LibKeyUrlField setting for the addon and an email notification will be sent to the patron to deliver the link using the email template specified in the DeliveryEmailTemplate setting.

    1. The ILLiad request is then routed to the status specified in the DeliveredQueue setting.

  4. If the article is not found in the LibKey database or is not available to be filled through the LibKey service, the ILLiad request is routed to the status specified in the NotFoundQueue addon setting for manual processing.

Decision Support Pipeline Addon Information

Stage 2 and 3 addons are not currently supported in the pre-copyright pipeline with a "Recommended" rule type. This functionality will be available in the ILLiad v10 release. In the meantime, we recommend using the following alternative business rules:
Option 1:

  • Pipeline: Borrowing Article

  • Rule Type: Recommended

  • Target Type: Addon

  • Target: LibKey Addon

Option 2:

  • Pipeline: Borrowing Article Pre-Copyright

  • Rule Type: Automatic

  • Target Type: Addon

  • Target: LibKey Addon

The first alternative will provide a similar outcome but with additional copyright information for comparison until the new functionality is implemented.

Decision Support Pipeline Addon - Additional Configuration

This addon can be optionally configured to run as a DSP addon on the Borrowing Article Pre-Copyright and Borrowing Article Pipelines of the DSP following the additional configuration steps below:

  1. Click on the LibKey addon within the Server Addons tab in the ILLiad Customization Manager.

  2. Click the Decision Support Pipeline tab located next to the Settings tab for the addon in the bottom half of the screen.

  3. Check Borrowing Article Pre-Copyright and/or Borrowing Article under “Supported Pipelines.”

  4. Click on the DSP Business Rules tab at the top of the Customization Manager screen.

  5. Set up a business rule for the LibKey addon according to your institution’s preferences.

Decision Support Pipeline Addon Workflow

Once configured, the addon will run according to the following workflow when a request enters stage 2 of the DSP Pipeline:

Stage 2

  1. The addon looks at requests in the Awaiting Pre-Copyright Pipeline status (when configured for the Borrowing Article Pre-Copyright Pipeline) and/or the Awaiting Request Pipeline status (when configured for the Borrowing Article Pipeline) and checks LibKey to see if the requested article is available to be filled through the LibKey service. It will search for requests using bibliographic data with the following precedence:

    1. by DOI if the ILLiad request has a value in DOI.

    2. by PMID if a DOI value is not present on the ILLiad request or if the DOI search returns no results.

  2. If the article is found in the LibKey database and can be filled through the LibKey service, a fulfillment data record is generated for the addon and the LibKey access URL for the article is stored in the custom data field of the fulfillment data record.

    1. The ILLiad request is then routed to Awaiting Pipeline Sending and proceeds to Stage 3.

  3. If the article is not found in the LibKey database or is not available to be filled through the LibKey service, the ILLiad request is routed to Awaiting Pipeline Request Review for manual processing.

Stage 3

  1. If the LibKey addon is chosen to fill the request based on the business rules configured for the Decision Support Pipeline and the rule type for the selected business rule is set to Automatic, the LibKey access URL will be saved to the ILLiad field designated in the LibKeyUrlField setting for the addon and an email notification will be sent to the patron to deliver the link using the email template specified in the DeliveryEmailTemplate setting.

    1. The ILLiad request is then routed to the status specified in the DeliveredQueue setting.

  2. If the LibKey addon is chosen to fill the request based on the business rules configured for the Decision Support Pipeline and the rule type for the selected business rule is set to Recommended, the request will be sent to the Awaiting Pipeline Request Review queue for manual processing.

    1. From this queue, the Select Recommended Action option can be used to fill the request through the LibKey addon, which will save the LibKey access URL to the ILLiad field designated in the LibKeyUrlField setting and send the email notification using the email template indicated in the DeliveryEmailTemplate setting.

    2. The ILLiad request is then routed to the status specified in the DeliveredQueue setting.