Ready to Learn?Ex Libris products all provide open APIs

Tech Blog

 

Working with Alma APIs in a fulfillment network

Tamar Fuches on April 22nd, 2018

A fulfillment network defines a relationship between Alma institutions that provide out-of-scope services to each other. The purpose of this article is to describe how fulfillment network functionality is supported in Alma APIs. For more details regarding fulfillment networks see Alma OLH.
 
Note that the APIs described in this article will be part of the Alma June 2018 release.

 

Background

Before providing services, a patron must be recognized in Alma. In a fulfillment network a patron is recognized by her home institution ID.
In the following example, user A_ID exists in institution A. In the first time she receives services from institution B, the user entity is copied to institution B. The 2 user entities are linked:
 
 
The above workflow is supported in Alma UI and in Primo. The following use cases describe how to achieve this using Alma APIs.

 

Use case 1: recognizing the user

User A_ID wants to receive a service from institution B. for example, loan a book. User id is required by the create loan API. However the user does not know her ID in institution B (B_ID). She is only aware of her regular ID: A_ID. So before creating a loan, institution B needs to find the local copied user based on A_ID.
The GET users API should be used for this:
GET /almaws/v1/users?source_institution_code=A&source_user_id=A_ID&apikey={key of institution B}
The response for this will include the local user entity in institution B:
<users>
   <user>
      <primary_id>B_ID</primary_id> 
      <source_institution_code>A</source_institution_code>
      <source_link_id>123</source_link_id>
       …
   </user>
</users>
Usually there will be only a single user in the returned list.
 
Then, a loan can be created in institution B using B_ID:
POST /almaws/v1/users/B_ID/loans?item_barcode=xxx&apikey={key of institution B}

Note that before creating the loan, it is recommended to refresh the information in the local user in institution B. This is in order to handle a case in which user A_ID in institution A was updated, after it was already copied to institution B.
Refreshing the user is done using the operate on user API:
POST /almaws/v1/users/B_ID?op=refresh&apikey={key of institution B}
The returned user object is the updated refreshed user in institution B.
 

Use case 2: creating a linked user

If this is the first time user A_ID receives services, a local entity does not yet exist for him in institution B.
In this case, the GET users API will return an empty list:

GET /users?source_institution_code=A&source_user_id=A_ID&apikey={key of institution B}

A linked user can be created in institution B using the POST user API:

POST /users?source_institution_code=A&source_user_id=A_ID&apikey={key of institution B}

Payload: Empty user structure:  <user/>


The returned user is the local copied user in institution B:

<user>
   <primary_id>B_ID</primary_id> 
   <source_institution_code>A</source_institution_code>
   <source_link_id>123</source_link_id>
    ….
</user>

 

Summary: logic in loaning application

This is a brief summary of the way an application should be designed in order to implement the above use cases:
- Check for local user:
  GET /users?source_institution_code=A&source_user_id=A_ID&apikey={key of institution B}
- If user is found:
     - Refresh user data:
       POST /almaws/v1/users/B_ID?op=refresh&apikey={key of institution B}
- Else:
     - Create local user:
       POST /users?source_institution_code=A&source_user_id=A_ID&apikey={key of institution B}
- Create loan:
  POST /almaws/v1/users/B_ID/loans?item_barcode=xxx&apikey={key of institution B}