Ready to Learn?Ex Libris products all provide open APIs

Tech Blog

 

For Institutions: Setting up a real-time acquisitions workflow with participating vendors

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

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

Note: This article is general, for setting the workflow with any vendor. You can find here specific instructions for setting the workflow with ProQuest Coutts OASIS.

 
Set-up for Real Time Ordering happens both on the vendor and the Alma side.
 

Configuration in Alma

  1. Default Metadata template: ensure that a default metadata template is configured. (Open metadata editor - template - choose the one you want to define as a default - click properties - check as default).
  2. New Order API Integration Profile: Decide about the matching rules that you want to apply - see How the bibliographic record is determined. Validations for fund related issue can also be configured as documented here (docx).
  3. Vendor specific Alma configuration:
    YBP: The vendor account representing YBP should be defined with 0% discount.

 

Information you will need to send the vendor

  1. API key
An API key should be generated by you and supplied to the vendor:
  • Login to the Developers Network using your institution account. Make sure you are connected with your institution account and not with your personal account: Go to Dashboard - Organization. Your institution code should be displayed:
  • Define an application with the name "Integration with vendor".
  • Add "Acquisition" API to the application, with read/write plan for your production environment.
  • Add "Configuration" API to the application, with read only plan for your production environment.
Note: YBP does not have a testing environment, hence the API key must be defined for the Alma production environment.
  • Copy the API key of the application. This is the API key that will be used as part of the vendor API calls in order to identify your institution.
For more details regarding API key generation and working with Alma APIs, see: Alma APIs.
 
  1. Vendor code and Vendor account code - this is the information regarding the vendor record in Alma. The created PO line will be related to that vendor and vendor account:
Make sure that this vendor in Alma is configured not to send outgoing EDI messages for POs. Other EDI messages (e.g. for invoices) can be sent if this is your workflow.
 
  1. Owning Library code(s) - this is the library for which the created PO line will be assigned to:

You will need to supply a list of possible owning library codes to the vendor. The implementation on the vendor side might be to give a drop-down on the ordering form, 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.
Note that the vendor might use the retrieve libraries API in order to get full list of libraries, or use the get library API in order to check a code of specific library.
 
  1. Location code(s) - this is the location in which the related item(s) will be created. Relevant only for physical material:

Note that the LSP might use the retrieve locations API in order to get full list of libraries, or use the get location API in order to check a code of specific library.
 
  1. Fund code(s) - this is the fund from which the payment will be done. Note that the vendor can use the Retrieve funds API.

 

Troubleshooting

After the above information was supplied to the vendor, 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.