Ready to Learn?Ex Libris products all provide open APIs

Tech Blog

 

For Vendors: Setting up a real-time acquisitions workflow with ExLibris Alma

Real Time Acquisition General Overview
Instructions for Institutions
Instructions for vendors
General overview of ExLibris APIs methodology
Common APIs for Acquisitions Vendor Integration
Related blogs

 
This article contains the required steps for vendors, in order to set up a real-time acquisitions workflow with ExLibris Alma. For general description of the real-time acquisitions workflow, see here.
 

General

When an order is submitted in your system, its information should be sent to Alma, using the create po-line API.
API calls to Alma should be sent to the following base URL: https://api-na.hosted.exlibrisgroup.com/almaws/v1. An apikey parameter should be sent to Alma as part of the API call, indicating the institution. This information should be supplied by the institution (Maximum length: 255) - see here for more information.

The PO line object

The po line object contains many fields; you should review it and send as much information as you have. Following is list of the required information that must be sent for processing the po line in Alma:

  1. type – there are several types of po lines in Alma. The type defines the frequency of the order (one time or continous), and its material (print, electronic or a package).You should map your order types into the Alma types. See the list of Alma types here.
  2. price – the list price (i.e. price of a single item, before discount), as defined in your system.
  3. vendor_reference_number - the order number, as defined in your system.
  4. resource_metadata – send here as much bibliographic information as possible. The minimum is the title or the mms_id. See Alma matching logic.
  5. renewal_date - for continuous and standing orders PO lines.
  6. amount for funding – The specific fund for covering the order should be supplied by the institution (see below).
    The amount for funding should be calculated based on the net price i.e. [list price] * quantity – discount. If you want to define a single fund with 100% funding, its amount should be: [list price] * quantity – discount.
    In Alma a discount might be defined as part of the vendor account information.If a discount is not known in the ordering stage and will vary for each title, then no discount should be defined in Alma as part of the vendor account: in the stage of ordering the discount should be considered as 0.

Information that should be supplied by the institution

  1. vendor and vendor account (Maximum length: 255) – the vendor record in Alma. The created PO line will be related to that vendor and vendor account. This information should be supplied by the institution, and associated with the institution’s account that is defined in your system .
  2. owner (Maximum length: 50)- the library for which the created PO line will be assigned. You might give a drop-down on the ordering form, allowing the operator to choose the relevant owning library. Other implementation might be to associate an account to a single owning library. In this case, the operator will have to be logged in with the relevant account.
  3. library, location and quantity – for physical material. Note that the library in which the item will be placed might be different than the owning library.
  4. fund_distributions – list of funds and the amount they cover. The specific fund(s) for covering the order might be selected by the operator as part of the order submission form (see below).
     

Usually, a form will be added in your system during the submit order stage, allowing the operator to select the fund. For physical material, the operator should select also quantity, library and location: 

The drop-down values can be retrieved as following:

We recommend using these APIs in order to retrieve a list of valid values, and reduce the amount of errors.

 

Alma response

  • If a po line was successfully created, Alma will response with 200 HTTP and the created po line object. It is recommended to keep the created po line number in your system, in order to allow further review in the future.
  • If the po line was rejected by Alma, 400 HTTP response will be returned as well as a textual description of the error. 

 

Troubleshooting

After the required information was supplied by the institution, we recommend that the following will be done in order to make sure the integration is set properly:
 
  1. Perform GET /almaws/v1/acq/test?apikey={supplied apikey}
The response should be in the following form:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<test>GET - OK - institutionCode: 01MY_INST</test>

Make sure that the institution is the correct one. If not - it means that the API key was not generated using the institution account.

 

  1. Perform POST /almaws/v1/acq/test?apikey={supplied apikey}
The response should be in the following form:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<test>POST - OK</test>

If 400 HTTP error was retrieved, it means that the API key was not defined with read/write permission, or it is against a demo environment.
 
  1. "Failed to create bibliographic record" error message
Make sure that the institution has defined a default metadata template (Open metadata editor - template - choose the one you want to define as a default - click properties - check as default). In addition, make sure that this template has definition for LDR and 245 fields.
 
  1. Make sure that the institution has given vendor code and not vendor name, vendor account code and not vendor account description. You can use the GET vendor API in order to check the data.