ILLiad ReShare Server Addon

This is 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.

This addon is only compatible with ILLiad v9.1 or later.

Name

ReShare

Version

1.0.6

Author

Atlas Systems, Inc.

Description

The ILLiad ReShare addon is a Server Addon/Decision Support Pipeline (DSP) Addon that helps automate fulfillment through the ReShare service. It will process ILLiad requests placed in the Loan DSP pipeline or in a specified search queue, automatically initiate a ReShare request if appropriate, and poll the status of the ReShare request to automatically complete the ILLiad request or otherwise indicate it is unfilled.

Download

Integration Known Issues

Note: At this time, ReShare has not yet developed functionality to push requests originating in ReShare to ILLiad. Please contact ReShare if you would like to see this functionality as a future enhancement.

The following known issues may affect the addon’s functionality and are awaiting resolution:

  • Issue: If the pickup location for the borrowing library is set to the default_circ_desk in ReShare, then the pickup location on the borrowing library’s ILLiad request will be incorrectly updated to the lending library’s pickup location when the ReShare request is filled.

    • Status: ReShare just pushed out a fix that allows each pickup location to have a unique identifier. To verify, Atlas will help a couple of sites update this value and test the new parameters. The site will need to update its pickup locations with the new unique pickup location identifier in the PickupLocationLookupValue setting.

  • Issue: If a search by ISBN of the ReShare Shared Index returns multiple bibliographic records, the addon will route the request to a manual processing queue to allow ILL staff to decide which bibliographic record should be selected. A note will be added to the request indicating that multiple results were found. This is a result of the difference in metadata for each item such as the title.

    • Status: Atlas will meet with sites to see if they are willing to accept the risk of choosing a particular result. What rules would we need to establish when picking the best match?

Configuration - Addon Settings

Addon settings are configured in the Server Addons form located in the ILLiad Customization Manager. These settings will be the same whether using the addon as a Server Addon or as a Decision Support Pipeline Addon.

Name

Type

Default

Description

Name

Type

Default

Description

NVTGC

String

ILL

This setting should be set to the same NVTGC that this addon is configured under in the Customization Manager. It is used to filter requests that should be processed from the SearchingMonitorQueue.

SharedIndexAPIUrl

String

 

The URL for the Shared Index API service.

SharedIndexUsername

String

 

The username to use when authenticating against the Shared Index API service.

SharedIndexPassword

String

 

The password to use when authenticating against the Shared Index API service.

SharedIndexTenant

String

 

Your institution's tenant ID for the ReShare API service.

ReshareAPIUrl

String

 

The URL for the Reshare API service.

ReshareAPIUsername

String

 

The username to use when authenticating against the Reshare API service.

ReshareAPIPassword

String

 

The password to use when authenticating against the Reshare API service.

ReshareTenant

String

 

Your institution's tenant ID or SLUG for the Reshare API service.

This setting is case sensitive and should be entered in lowercase letters.

OpenURLListenerURL

String

 

The OpenURL endpoint used to create requests in ReShare.

OpenURLTenant

String

 

Your institution's symbol for the ReShare OpenURL endpoint.

This setting is case sensitive and should be entered in the format ISIL:US-abcd

SearchingMonitorQueue

String

Awaiting Reshare Search

Defines the ILLiad status that the addon will monitor for requests that it should try to fulfill through ReShare.

NotFoundQueue

String

Awaiting Request Processing

This defines the ILLiad status that requests will be routed to when a single requestable item is not found in ReShare or multiple matches are returned and a single selection cannot be made.

UnfilledQueue

String

Awaiting Unfilled Processing

This defines the ILLiad status that requests will be routed to when they are marked unfilled in ReShare.

RequestSentQueue

String

Request Sent

This defines the ILLiad status that requests will be routed to when they are successfully requested in ReShare.

ErrorQueue

String

ReShare Error Processing

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

SendIdleRequestsToErrorQueue

boolean

True (checked)

If true, requests with a ReShare statecode of REQ_IDLE will be routed to the error queue with a message added in the notes.

PatronIDField

String

{TableField:User.Username}

The value to use to identify who the request is for. This field supports table tags and will use the ILLiad request's username by default.

PickupLocationLookupValue

String

{TableField:User.NVTGC}

The value to use to identify a pickup location value of the request. This field supports table tags and will use the NVTGC of the owner of the ILLiad request by default. This value can then be used to lookup the ReShare pickup location code from the PickupLocationLookupMapping setting.

PickupLocationLookupMapping

String

 

A comma-separated mapping that defines the ReShare pickup location or LMS location code to use for a given PickupLocationLookupValue, determined from the prior setting. If this mapping does not contain a key for the provided lookup value, the lookup value will be used without modification.

Example: ILL=DEFAULT_CIRC_DESK

RequestPollingFrequency

String

10

Defines how frequently, in minutes, the addon will poll the ReShare service for status updates on submitted requests.

ReshareFilledStatuses

String

REQ_SHIPPED

A comma-separated list of the ReShare states that are considered to be filled.

ReshareUnfilledStatuses

String

REQ_END_OF_ROTA, REQ_UNABLE_TO_CONTACT_SUPPLIER

A comma-separated list of the ReShare states that are considered to be unfilled.

RequestPlaceholderID

String

ReShareIdPending

Placeholder value to use in the ILLNumber field on the ILLiad request for a new ReShare request for which an HRID is not yet available.

ReShare Configuration & Testing

Information to assist PALCI users with setting their credentials is available in PALCI’s ILLiad ReShare Server Addon documentation.

Please contact your consortium for help acquiring initial configurations and credentials. If you have any questions concerning troubleshooting for installation, please contact Atlas Support (support@atlas-sys.com):

  • SharedIndexAPIUrl

  • SharedIndexUsername

  • SharedIndexPassword

  • SharedIndexTenant

  • ReshareAPIUrl

  • ReshareAPIUsername

  • ReshareAPIPassword

  • ReshareTenant

  • OpenURLListenerURL

  • OpenURLTenant

  • PatronIDField

  • PickupLocationLookupMapping

To obtain the values for ReshareAPIUsername and ReshareAPIPassword settings, you will have to first create a user in ReShare. The values for these settings will then be the username and password credentials for that user.

As of version 1.0.6, if the addon encounters an error it is unable to resolve, such as in the case that any of the settings above are configured incorrectly and API calls cannot be made, then requests will be routed to the queue defined in the ErrorQueue setting for manual processing by staff.

Converting the Casing of ILLiad Values Sent to ReShare

As of version 1.0.6, the tag replacement feature used to pull a value from a specified ILLiad database field in the PatronIDField and PickupLocationLookupValue settings now supports additional options to convert the casing of that value to all uppercase or lowercase characters before sending it to ReShare. This is useful when the casing for the pickup location or username value in ILLiad is different from the casing of those values in ReShare.

Formatting

To convert an ILLiad value to uppercase or lowercase, a comma should be added after the names of the specified database table and field in the tag used by the setting and followed by:

  • “Uppercase” to convert the value to uppercase:

    • {TableField:<DatabaseTableName>.<FieldName>,Uppercase}

  • “Lowercase” to convert the value to lowercase:

    • {TableField:<DatabaseTableName>.<FieldName>,Lowercase}

Example

If a user's username in ILLiad is 'asmith', but their username used by the ReShare system is 'ASMITH', then the value of the PatronIDField setting should be set as follows to convert the lowercase value from ILLiad to the uppercase value in ReShare: 

1 {TableField:User.Username,UpperCase}

ILLiad Shared Server Sites - Additional Configuration

ILLiad shared server sites will need to upload and configure the addon settings separately for each individual NVTGC on the ILLiad server. The addon settings and credentials will be the same across each NVTGC with the following exceptions, which must be adjusted appropriately for each NVTGC:

  • NVTGC

  • PickupLocationLookupMapping

Addon Workflow Chart

The chart below can be used as a reference to track the addon’s workflows for both Server Addon and DSP Addon configurations:

ReShare Addon Workflow Chart

Server Addon Information

Server Addon - Workflow

Once the addon settings listed above are configured, the ReShare addon will run as a Server Addon according to the following workflow:

Step One: Request Creation

The addon will work by monitoring the ILLiad status defined in the SearchingMonitorQueue setting:

When using this addon as a Server Addon, you can add the SearchingMonitorQueue (default: Awaiting Reshare Search) to the default queues for manual routing in the ILLiad Customization Manager under System | Custom Queues. You may also consider configuring additional routing rules to automatically route requests into the SearchingMonitorQueue in a way that makes sense for your institution's local workflows.

  1. When a request enters the SearchingMonitorQueue, the addon will first confirm that the request is within the addon's scope by checking the user's NVTGC and confirming it's under the addon's NVTGC setting.

  2. If within the appropriate scope, the addon will then search the ReShare Index using bibliographic data on the request with the following precedence:

    1. By OCLC number if the ILLiad request has a value in ESPNumber.

    2. By ISBN if the ILLiad request has a value in ISxN.

    3. By title, author, and date using the LoanTitle, LoanAuthor, and LoanDate fields on the ILLiad request.

  3. If the ReShare request cannot be created because there are no matching items or more than one matching item in ReShare, the ILLiad request is routed to the status in the NotFoundQueue setting for manual processing and the addon’s workflow will stop here.

  4. If a single result is found in ReShare, the addon will submit a ReShare request for the ILLiad request, determining the patron identifier and pickup location used for the ReShare request using the PatronIDField, PickupLocationLookupValue, and PickupLocationLookupMapping settings.

    1. The ILLiad request is then routed to the status in the RequestSentQueue setting and the ILL Number field on the request will be updated with the tracking ID number for the request in the ReShare system.

Step Two: Request Fulfillment

After creating the ReShare request for the ILLiad request, the addon will poll the ReShare service according to the frequency defined in the RequestPollingFrequency setting, in minutes, to check the current state of requests and will automatically update their corresponding ILLiad requests that are in the RequestSentQueue in the following manner:

  1. The addon will retrieve all ReShare requests in the states defined in the ReshareUnfilledStatuses setting and check each one to see if there is a corresponding ILLiad request with a matching ILL Number field.

    1. If a matching ILLiad request is found, the addon will route that request to the status in the UnfilledQueue setting.

  2. The addon will retrieve all ReShare requests in the states defined in the ReshareFilledStatuses setting and check each one to see if there is a corresponding ILLiad request with a matching ILL Number field.

    1. If a matching ILLiad request is found, the addon will route that request to Request Finished.

Note that the addon cannot poll ReShare faster than its System Manager interval, defined in the SystemManagerAddonInterval customization key.

Decision Support Pipeline Addon Information

Decision Support Pipeline - Additional Configuration

You can optionally also configure the addon as a Decision Support Pipeline Addon. The addon will still run as a normal Server Addon according to all of the steps listed above, but will also add additional DSP functionality to give you more flexibility and options for your workflows. To enable the additional DSP functionality for the addon follow these steps:

  1. Click on the ReShare 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 Loan 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 new ReShare addon according to your institution’s preferences.

Example business rule:

This business rule will send borrowing loan requests in the Borrowing Loan pipeline to the ReShare addon. If a match is found in the ReShare Index for the ILLiad request according to the criteria listed in the workflow section below, then a ReShare request will be automatically created for the ILLiad request.

  • Rule Number: Determines the precedence for this business rule in the pipeline. For example, if you’d like all requests to run through ReShare first before performing any other business rules, enter “1” here.

  • Pipeline: Borrowing Loan

  • Enabled: Yes

  • Rule Type: Automatic

  • Target Type: Addon

  • Target: ILLiad Reshare

  • Description: Send borrowing loan requests to ReShare

  • Match String: 1=1

Decision Support Pipeline - Workflow

Once configured, the addon will run according to the following workflow when a request enters stage 2 of the DSP Pipeline and the business rule for the addon is triggered:

Step One: Request Creation

Stage 2

  1. The addon looks at requests in the Awaiting Request Pipeline status and checks the ReShare Index to see if it can be found in the Shared Index using bibliographic data with the following precedence:

    1. By OCLC number if the ILLiad request has a value in ESPNumber.

    2. By ISBN if the ILLiad request has a value in ISxN.

    3. By title, author, and date using the LoanTitle, LoanAuthor, and LoanDate fields.

  2. If zero or more than one result is found in ReShare, the ILLiad request is routed to Awaiting Pipeline Request Review for manual processing and the addon’s workflow will end here.

  3. If a single result is found in ReShare, ILLiad will check the business rules and either automatically route the request to Awaiting Pipeline Sending and proceed to Stage 3 if the rule type is “Automatic,” or route the request to Awaiting Pipeline Request Review if the rule type is “Recommended.”

Stage 3

  1. The addon looks at requests in the Awaiting Pipeline Sending and submits a ReShare request for the ILLiad request, determining the patron identifier and pickup location used for the ReShare request using the PatronIDField, PickupLocationLookupValue, and PickupLocationLookupMapping settings.

  2. The ILLiad request is then routed to the status in the RequestSentQueue setting and the ILL Number field on the request will be updated with the tracking ID number for the request in the ReShare system.

  3. An entry for ReShare will also be added to the Fulfillment Data Table located in the Detail tab of the ILLiad request.

Step Two: Request Fulfillment

The fulfillment process for requests routed through the Decision Support Pipeline will proceed in the same manner as requests handled by the Server Addon, detailed above.