Skip to main content
  • Subscribe by RSS
  • Ex Libris Knowledge Center

    InnReach API Implementation Guide


    The purpose of this document is to explain the general workflow of a customer that uses InnReach 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.


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




    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 InnReach 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 InnReach and Alma. InnReach 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 InnReach. General Electronic Services may be used to create OpenURL links from Primo search results to InnReach request forms, as described in the General Electronic Services section.

    1. Request is placed in InnReach.

    2. Patron Authentication

    3. 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. InnReach 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. InnReach 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. InnReach 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. InnReach 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 InnReach Integration Profile (see Integration Profile) then patrons of other InnReach institutions (that also use V3) can directly checkout items from your library. 

    To Checkout Items from a Visiting Patron's Library:
    1. On the Patron Identification page (if you are configured with V3 for InnReach Integration Profile as described in Integration Profile) select the Find user in other institution checkbox.

      Find User in Other Institution.
    2. Select the patron's institution.

      Select patron institution.
    3. Enter the patron's ID and select Find User.

      Find User.
    4. If the patron's id is authorized by their institution, you can now enter items to checkout for the patron.

      Checkout items for visiting patron.
    5. 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


    Integration Profile

    A library integrated with InnReach APIs must have an InnReach integration profile. In order to participate in an InnReach resource sharing workflow, the library must have an integration profile of type ‘Resource Sharing Integration’ (first step of defining the Integration Profile) and system ‘InnReach API’ (second step of defining the Integration Profile).
    See Integration Profiles for instructions on creating and editing integration profiles. Note that for InnReach 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 InnReach 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 InnReach 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 InnReach 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 InnReach 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:

    1. Click the Mapping of Alma user groups to central patron types link under Incoming Definitions. 
    2. Click Add Row. 
    3. Select a user group and enter the Central Patron Type provided by the INN-Reach project manager.
    4. 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:

    1. Click the Mapping of Alma location codes to central item types link under Outgoing Definitions.
    2. Click Add Row.
    3. Enter the library code in the Library Code field.
    4. 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 InnReach must be done after the integration profile has been set up since it requires that the integration profile be already configured and have "InnReach" in its name. The setup is done using the ‘InnReach 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 InnReach requirement. The descriptions are exported  unchanged.

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

    InnReach Sets

    In order for the lender to publish to InnReach, 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 InnReach 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 InnReach, it must be configured with:

    • A BIB level publishing profile:

      The profile is set to use the set defined for InnReach and will be set to use the Publishing Protocol ‘InnReach’.


    • An Items level publishing profile:

      The profile is set to use the set defined for InnReach.


      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 InnReach resource sharing partner record is used for the borrowing and lending requests communication. The partner record will:

    • Have an ‘InnReach 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 InnReach 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 InnReach 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:

    1. 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.


    2. 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.

    • Was this article helpful?