Tech Blog

How to create an order with an interested user via an API in your institution in 5 easy steps

See also: How to create an order via an API in your institution in 5 easy steps.

This blog will focus on creating an order with an interested user via an API in your institution.
The developer network already discusses how to create an order using an API. See for example Create PO Line , specifically the body parameters which describe the interested user.

For further information regarding the functionality of the interested user see “To add an interested user” at Manually Creating a PO Line.  The specific format of how to add the interested user as part of the payload (input) is included in the documentation of the Create PO Line API .

While the developer network provides a generic sample input file for the Create PO Line API in both XML and JSON format, this blog focuses on your institution and not a generic sample.  In this way you will have an example with, for example, your fund code, vendor codes, vendor account, reporting codes, etc.  Further, we will first do a GET on an existing POL which has an interested user so that we can see exactly how it is added to the payload (input) of the API.

ONE

Make sure you have an API key for read/write acquisitions. If you do not have one then log into the developer network and create one.
Set to sandbox or production as desired.

TWO

Identify an order in Alma similar to the one you want to create (POL type, fund, vendor, etc.) and make sure it has at least one interested user.
Be sure to use sandbox or production depending on API key you will use.
In the example here we will use POL-45266:

THREE

Do a GET on the order and save the XML in a local file for editing.
Here is the syntax (of course replace “01234567890” with your real API key):

https://api-eu.hosted.exlibrisgroup.com/almaws/v1/acq/po-lines/POL-45266?apikey=01234567890

FOUR

Edit the output from the GET above as follows to use as input for the POST to create the new orders.

Take note of how the interested user(s) in the output from the GET above appears:

<interested_users>
  <interested_user>
    <primary_id>AliciaC613</primary_id>
    <notify_receiving_activation>true</notify_receiving_activation>
    <hold_item>true</hold_item>
    <notify_renewal>false</notify_renewal>
    <notify_cancel>false</notify_cancel>
    <first_name>Alicia</first_name>
    <last_name>Chen</last_name>
    <email>thelibrary613@gmail.com</email>
  </interested_user>
</interested_users>

Edit the above “interested users” section as follows:

Remove the following lines as they are unnecessary for the input because the information is “known” from the primary ID:

  • <first_name>
  • <last_name>
  • <email>

Change primary ID to a user for whom you want to create an “interested user” and fill in these fields as desired, they correspond to the columns we saw in the Alma user interface:

  • <notify_receiving_activation>
  • <hold_item>
  • <notify_renewal>
  • <notify_cancel>

Regarding the meaning of each of the above options see “To add an interested user” at Manually Creating a PO Line.  

We will change the section of the interested users to this:

<interested_users>
  <interested_user>
    <primary_id>AnnaN613</primary_id>
    <notify_receiving_activation>true</notify_receiving_activation>
    <hold_item>true</hold_item>
    <notify_renewal>false</notify_renewal>
    <notify_cancel>false</notify_cancel>
  </interested_user>
</interested_users>

The primary ID AnnaN613 is for user “Anna Nemati”.  Change the rest of the POL output as follows:

Remove the following lines because they will get created automatically: 

  • POL number
  • POL status
  • PO number
  • MMSID
  • created date
  • status date
  • expected_receipt_date (relevant for POL type physical)

Remove the following sections because they will get created automatically: 

  • alerts
  • locations section (relevant for POL type physical) (will get created based on POL owner library)

Change the following so you will not have a match in an existing:

  • ISBN or ISSN
  • system control number

FIVE

Do a POST as follows:

https://api-eu.hosted.exlibrisgroup.com/almaws/v1/acq/po-lines?apikey=01234567890

In the Body choose application/xml and put in the edited output from the GET above.
Get response with POL number

See that the POL has the interested user we defined in the input (payload):

We also see of course that the POL was created from the API

 

 

 

 

Leave a Reply