Tech Blog

Using Alma APIs for creating Sets

Avatarby Ori Miller Ex Libris, Clarivate February 22, 2017 (Updated: November 26, 2018)
ALMA JOBS
On top of the Job APIs, it is now possible to use APIs to create a set which will be used as an input for the Job.
The page ‘Managing Search Queries and Sets’ which can be found here explains in details about all types of sets and their intended usage.
The various Set related API can be found here and a reference of all indexes can be found here.
Note that an ‘Update Set’ API doesn’t exist as this isn’t a common use case. However you can always use the DELETE and POST to create a new set if needed.

Set types

There are two kinds of sets:
Itemized – Individual items, selected or uploaded by the librarian
Logical – A saved search query, which is run every time the set is referenced.
It is possible to use APIs to either create an empty Itemized set and then populate with members, or create a logical set.
Logical set is currently supported for all Inventory sets (Bibs, Items, Portfolios, Digital representations etc.) but not for Users, PO-Lines and Vendors.
Logical set creation
The syntax for defining a logical set is similar to what appears in the UI when performing an Inventory search.
Current Search:  

Physical Items where Title (Title contains keywords "history") and Holding (Library (Holding) equals "Art Library") and Physical item (Receiving date after "2016-04-02")

However to see the exact syntax which is needed for creating a set using the API, it is recommended to first create a set using the UI, use a GET call to the API to find out what the syntax is, and then use it as a template for creating other similar Logical sets using the API.

In the below sample you can see how a set of Items is defined by a 3 conditions: one from the Bib, one from the Holding and one from the Item. Note that the textual syntax which appears in the UI is included in the ‘desc’ attribute. As in all our APIs the ‘desc’ attributes are ignore when received in POST requests. The actual value of the ‘query’ field will be used. It uses a more technical syntax and the name are more code-like, but comparing to the ‘desc’ attribute should make it understandable.

<set link="/almaws/v1/conf/sets/1622034000000121">

    <id>1622034000000121</id>

    <name>items - history, Art, date</name>

    <type desc="Logical">LOGICAL</type>

    <content desc="Physical items">ITEM</content>

    <private desc="Yes">true</private>

    <status desc="Active">ACTIVE</status>

    <status_date>2017-02-22T10:35:41.664Z</status_date>

    <created_by desc="John Smith">johns</created_by>

    <created_date>2017-02-22T10:35:41.664Z</created_date>

    <query

        desc="Physical Items where Title (Title contains keywords "history") 

        and Holding (Library (Holding) equals "Art Library") 

        and Physical item (Receiving date after "2016-04-02")">

        ITEM where BIB_MMS (title CONTAIN "history")

        AND HOLDING (holding_Library OUTER_EQUAL "ART") 

        AND ITEM (arrivalDate AFTER "2016-04-02")</query>

    <number_of_members link="/almaws/v1/conf/sets/1622034000000121/members">3</number_of_members>

</set>
In the near future we’ll be adding a special documentation page here at the Developer Network, which will list the available indexes for each inventory type. Hopefully this will enable creating a complex logical set, without creating a template one with the UI first.

Special use cases

If you would like to have a ‘frozen’ Itemized set from a Logical set you can use the Create Set API with the from_logical_set parameter. The payload could be as small as <set></set> since all fields have default values (or values which are taken from the logical set on which the new set is built). The original logical set remains as is.
It is also possible to create Logical sets based on the report of an MD-Import run. For this we have dedicated a separate blog post – see here

4 Replies to “Using Alma APIs for creating Sets”

  1. How do I retrieve xml output for the following user(patron) data fields using Alma API below? I am using Perl scripts to extract the fields and I NEED HELP. HERE IS THE FIELDS THAT I WANT TO EXTRACT:

    primary_id, first_name Last_name, middle_name, user_group, last_modified_date, blocked, email, deleted, campus_code search by last_modified_date = yesterday_date(mm/dd/yyyy).

    HERE IS MY ALMA API:
    https://api-na.hosted.exlibrisgroup.com/almaws/v1/users?&apikey=xxxxx

    By Rochester College 01DAL_ROCHESTER on April 3, 2017 at 4:52 PM

  2. As this question doesn’t seem to be related to sets, I suggest to ask it in Alma’s forum. You can also open a Support case. But maybe I can help with this:

    Try GET /almaws/v1/users/{user_id} – this should give all the information there is about the user.

    Ori Alma API Team

  3. It seems very difficult to construct a query especially when it involves with multiple fields with operators. E.g. I need to create a set for items between a call number range, AC – AZ, in two locations, Libr:media and Libr:asia.

    ITEM where HOLDING ((PermanentCallNumber GREATER_EQUAL “AC”) AND (PermanentCallNumber LESS_THAN “AZ”) AND ((permanentPhysicalLocation EQUAL “Libr : asia”) OR (permanentPhysicalLocation EQUAL “Libr : media”)))

    Would you give me a direction or documentations?

    Thanks

    Nackil

  4. Hi Nackil,
    Generally, we recommend creating one set using the UI and then using the GET-Set API to use its output as a template for POST requests.

    Specifically, there is a known issue with the indexes you used (searching for Items using Holdings fields). Please open a case with Support so we can base a bug-fix on it.
    Thanks,
    Ori
    Alma APIs Team

Leave a Reply