InnReach API Implementation Guide

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

Objective

The purpose of this document is to explain the general workflow of a customer that uses INN-Reach and Alma using the API based integration, including the PS/Support tools that are required for the initial setup. See also Visiting Patrons in an InnReach Network.

Publishing

INN-Reach knowledge about the availability of items in the network is based on the institutions’ use of the API to notify INN-Reach about bib and items records’ status. In Alma, the publishing platform is configured to publish this information using the INN-Reach APIs.

Workflow

Once the records have been published, borrowers will be able to request the items.

A demo of the integration is found here. The demo and the below captures have been done with an INN-Reach sandbox test environment.

Below is the flowchart of the workflow. In this diagram, Alma is playing both the borrower and the lender role. This is done to present one chart that shows Alma’s role as borrower and its role as lender. Many times, Alma will be either on the borrower side or on the lender side but not on both.

The flowchart illustrates the communications that flow between INN-Reach and Alma. INN-Reach messages that Alma ignores are not shown in this diagram.

InnReach/Alma Flowchart

Placing a Request

The initial creation of the request is done directly in INN-Reach. General Electronic Services may be used to create OpenURL links from Primo search results to INN-Reach request forms, as described in the General Electronic Services section.

Request is placed in INN-Reach.
Patron Authentication
Request is created

Shipping an Item

Once a lending request has been automatically created by the API, the lender’s processing is the standard Alma workflow for processing lending requests. Pick slips may be created from the Lending Requests task list or move requests may be created for branch processing of the physical items using the Manage Fulfillment Options task list action. Requests for branch processing may also be automatically created by Alma. See more information at Peer to Peer Resource Sharing - Lending.

After the item has been fetched staff uses the Fulfillment > Resource Sharing > Shipping Items menu to ship the item.

Other Actions

Additional supported actions are:

Receive – Borrower can do the receive action using the regular Alma interfaces. INN-Reach is automatically updated. Note that Alma on the lender side does not register the fact that a borrower has done a receive action. See Receiving an Item from a Resource Sharing Request.
Return – Borrower can do the return action using the regular Alma interfaces. INN-Reach is automatically updated. Note that Alma on the lender side does not register the fact that a borrower has done a return action. See Returning a Resource Sharing Item to the Lender.
Cancel – Borrower can do the cancel action using the regular Alma/Primo interfaces. INN-Reach is automatically updated. Alma on the lender side is updated that a borrower has done a cancel action. See Canceling a Resource Sharing Request.
Reject – Lender can do the reject action using the regular Alma interfaces. INN-Reach is automatically updated. Alma on the lender side is updated so that a borrower has done a cancel action.

(New for February) Visiting Patron Checkout

If you are configured to use V3 of the INN-Reach Integration Profile (see Integration Profile) then patrons of other INN-Reach institutions (that also use V3) can directly checkout items from your library.

To Checkout Items from a Visiting Patron's Library:

On the Patron Identification page (if you are configured with V3 for INN-Reach Integration Profile as described in Integration Profile) select the Find user in other institution checkbox.
Select the patron's institution.
Enter the patron's ID and select Find User.
If the patron's id is authorized by their institution, you can now enter items to checkout for the patron.
After the barcode is entered and the Update INN-Reach Requests job runs, lending request/s are created at the lending library and borrowing request/s at the patron’s home library. From this point on the request is handled as a regular resource sharing request

Configuration

Integration Profile

A library integrated with INN-Reach APIs must have an INN-Reach integration profile. In order to participate in an INN-Reach resource sharing workflow, the library must have an integration profile of type ‘Resource Sharing Integration’ (first step of defining the Integration Profile) and system ‘INN-Reach API’ (second step of defining the Integration Profile).
See Integration Profiles for instructions on creating and editing integration profiles. Note that for INN-Reach the Integration Type must be Resource Sharing Integration.

The Resource Sharing Integration option selected for the Integration Type field.

If you are setup to work with INN-Reach D2IR V3 you can also configure your system to work with that version. This requires the Update INN-Reach Requests job (see Scheduled Jobs) to be active (Configuration > Fulfillment > General > Fulfillment Jobs Configuration). When this job runs, it updates the status of your requests every two hours.

The V.3 option selected in the Version field for the InnReach Integration Profile.

You can check with Innovative regarding which version of INN-Reach is relevant to your organization.
If you selected the Version 3 (V3) option, the Visiting Patrons Workflow checkbox displays and you can select it to use the Visiting Patrons Workflow functionality (see Visiting Patrons in an InnReach Network). In this case, make sure to select the Generate List of Agencies option in order to correctly reflect the list of INN-Reach libraries that you can interact with.

The Outgoing Definitions of the Integration Profile have to be filled in based on information supplied by Innovative. Below is an example.

The Outgoing Definitions fields filled in for the Integration Profile.

The Incoming Definitions are automatically generated. Use the Generate Secret button to have Alma generate a secret. After generating the secret, use the ‘Copy to clipboard’ link that appears on the page in order to get the generated secret. The information in this section as well as the secret are required in order to configure the INN-Reach side of the integration.

The Incoming Definitions section with the Copy to Clipboard option highlighted.

Mapping Alma user groups to INN-Reach central patron types is required. To do this, follow the procedures below:

Click the Mapping of Alma user groups to central patron types link under Incoming Definitions.
Click Add Row.
Select a user group and enter the Central Patron Type provided by the INN-Reach project manager.
Click Add Row and repeat until all necessary user groups are accounted for.

The fields that display after selecting "Mapping of Alma user groups to central patron types".

Mapping Alma locations to central item types is required for lending. To do this, follow the procedures below:

Click the Mapping of Alma location codes to central item types link under Outgoing Definitions.
Click Add Row.
Enter the library code in the Library Code field.
Enter the location code in the Location Code field, and the central item type in the Null field. Central item types should be provided by the INN-Reach project manager.

Values filled for the Library Code, Location Code and null fields.

Setting Locations

Updating locations in INN-Reach must be done after the integration profile has been set up since it requires that the integration profile be already configured and have "INN-Reach" in its name. The setup is done using the ‘INN-Reach Locations Setup’ cloud application.

Once installed, the application simply needs to be run. It is recommended to run with the Show Log option ON.

The location codes are exported to Alma as 5 lower case alphanumeric characters and not with the Alma codes. This is due to an INN-Reach requirement. The descriptions are exported unchanged.

Re-run the application every time a location that should be published to INN-Reach is added to Alma’s configuration.

InnReach Sets

In order for the lender to publish to INN-Reach, it must be configured with a physical titles set that is used as input to the publishing profile. The set must include all of the physical titles that are part of the INN-Reach requesting system, and will be defined by the library as per the library’s criteria for this purpose.

Publishing Profiles

In order for the lender to publish to INN-Reach, it must be configured with:

A BIB level publishing profile:
The profile is set to use the set defined for INN-Reachand will be set to use the Publishing Protocol ‘INN-Reach’.

An Items level publishing profile:

The profile is set to use the set defined for INN-Reach.

The Data Enrichment tab must be set to include items information as below:

Data Enrichment tab settings
Field	Items Information Setting
Repeatable	Must be a field that is not used in cataloged MARC records, for example 990.
Item PID	0
Material Type	a
Copy ID subfield	e
Item Status	b
Current Library	c
Current Location	d
Description subfield	v
Call Number subfield	t

Partner Record

The INN-Reach resource sharing partner record is used for the borrowing and lending requests communication. The partner record will:

Have an ‘INN-Reach API’ type.
Be defined to allow sharing patron information.
The workflow profiles (Borrower AND lender) must be set not to use ‘cancel reply’.

If your INN-Reach workflow involves using the lender’s item barcodes at the borrower side, then the Shared Barcodes option should also be turned ON.

The item policies to select from should be configured (Fulfillment Configuration>Physical Fulfillment>Item Policy) when at the scope of the resource sharing library.

Workflow Profiles

The INN-Reach Partner records need to be linked to a Borrowing workflow profile that enables cancelling by patron and staff, but does not wait for cancel replies.

If renewals are to be enabled, then it is recommended to:

Set the lending workflow:
1. NOT require Renewal response.
2. Allowing patron renewal from Primo is done by activating the Patron Renewal action.
3. Allowing the staff renewal from Alma is done by activating the Staff Renewal action.
It is recommended to set the borrowing workflow with Mediated Patron Renewal. This will cause patron renewals from Primo to set the borrowing request to a status of Mediated Patron Renewal. Staff then uses the borrower task list Request Renew action to renew the borrower request. This will also have the effect of renewing the patron loan, and sending a Borrowing Info Letter notification to the patron.

Other Settings

rs_allow_actions_on_scan_in – recommended to be False in order to prevent lenders' items that are being checked back in from being automatically re-shipped by Alma.
rs_keep_rejected_request_active – recommended to be None so that rejected requests do not remain on the active task list.
rs_auto_request_lending – recommended to be ‘true’ so that lending requests automatically link up to the inventory that will be used for fulfilling the request. It is also required to make sure the ‘Is Requestable for Physical Resource Sharing’ policy on the request TOU is set to ‘true’ for all resource sharing lendable items. For more information see Physical Fulfillment.