Working with APIs in a Network Topology

Alma supports data sharing and collaboration across institutions in a streamlined manner. Each institution may choose its collaborative partners and establish a collaborative network to jointly manage shared resources:

For general information about networks in Alma, see Alma OLH

This article focuses on API and integration workflows in a network topology.

NZ API key vs. IZ API key
An account in the Developers Network is defined by ExLibris for each member institution. An additional account is defined for the network institution:

• In order to perform actions and retrieve information from a member institution, an application and API key should be generated with the institution account.
• In order to perform actions and retrieve information from shared network, an application and API key should be generated with the network account.

See Generating API keys

Cataloging infrastructure
Alma CZ contains bib records. It is recommended for institutions to link their local bib records to those in CZ, and benefit from updates and corrections that are done by the community.
In a network topology, there is another level in the hierarchy: network bib record, which is linked to the CZ record. The institution’s bib is linked to the network’s bib, and this way benefits from updates from the community and from the network.
Note that each level in the cataloging hierarchy has its own MMS ID: the institution MMS is used for local purposes like attaching inventory or requesting.
The following diagram illustrates the hierarchy:

In the following use cases, this is the hierarchy of bib records:
CZ: 992550000001150386
NZ: 9978811100191
IZ: 9990111100121

For more details regarding the bibliographic records hierarchy, see Alma OLH

Use case #1: Search for material in the network zone that does not exist locally, and see which member institution has it. A resource sharing request will be sent to that institution:
Search for records with “data” using SRU request:

<Alma domain>/view/sru/<network institution>?version=1.2&operation=searchRetrieve&recordSchema=marcxml&query=alma.all_for_ui=data

CZ ID is added as a network number (035) with (EXLCZ) prefix. If “Enrich with Members Availability” is defined in the network’s SRU profile, holdings availability for each member of the network is added in 852 field as following:

• $a Location – Institution code
• $6 Linkage – Institution zone MMS ID
• $9 Local field – P (print) / E (electronic) / D (digital)

When more than one material type is available for one institution such as print and electronic, the 852 field contains multiple $9 entries.Example:

If the NZ mms_id is known, a search for the resource in the network can be done using the API:
GET /almaws/v1/bibs/{NZ_mms_id}?apikey={network institution key}&expand=p_avail,e_avail,d_avail

The result contains information regarding member institutions that have inventory for this record in AVA field:

The institution MMS ID can be used to create a resource sharing request via the create resource sharing request API. Remember that the institution API key must be used for the institution-level request.

Use case #2: Search for material locally and see that no item is available. Search NZ to see which member institution has it. A resource sharing request will be sent to that institution.

GET /almaws/v1/bibs{IZ_mms_id}?apikey={member institution key}& expand=p_avail,e_avail,d_avail

In this example, the AVA field indicated that there are 3 items locally (subfield f), but 3 of them are not available (subfield g). The network zone MMS ID is added as a network number (035) with (EXLNZ-network_code) prefix, and can be used in order to search the network and find out what member has the material (see use case #1 above).

Use case #3: Add a bibliographic record to the institution, and link it to the network record:

POST /almaws/v1/bibs?apikey={member institution key}&from_nz_mms_id={ Network Zone mms id}

The returned BIB record will include the institution’s local bib record that was created. In 035 it will have the network record number. Note that in case an institution bib record that is linked to the NZ record already exists, an error message will be returned (this will be changed in the future, to 303 http redirect to the existing institution bib record).

In order to add local fields to the created bibliographic record:

PUT /almaws/v1/bibs/{IZ_mms_id}?apikey={member institution key}

The payload for this API should include the local fields to be added, with $$9local indication. Note that non-local fields in the payload will be ignored. Update of such fields should be done directly with the network record:
PUT  /almaws/v1/bibs/{NZ_mms_id}?apikey={network zone institution key}

Use case #4: Order inventory from vendors

POST /almaws/v1/acq/po-lines?apikey={member institution key}

The purchase order line contains bibliographic information. It is possible to define where the match will be done:

• IZ  – search for a match with institution bib. If no match is found, add a new local bib.
• IZ and NZ – search for a match with a network bib. If a match was found – add a local bib and connect it to the network bib. If no match was found – add a new bib to the network.

See more information regarding the match