Ready to Learn?Ex Libris products all provide open APIs

Tech Blog

 

Cataloging APIs enhancements

Tamar Fuches on October 18th, 2017

During 2017 we have done some work on the Alma cataloging APIs in order to enable more cataloging options such as validation, normalization etc.
This article focuses on the new cataloging APIs features, including detailed explanation and samples.
 
The following table summarize the new cataloging APIs features:
 
APIDescriptionNotes
POST /almaws/v1/bibsCreate BIB record

Normalization, validation, 

Linking to a network zone record

PUT /almaws/v1/bibs/{mms_id}Update Bib RecordNormalization, validation, cataloger level, stale version check
DELETE /almaws/v1/bibs/{mms_id}Delete Bib RecordWarnings and override, cataloger level
POST /almaws/v1/bibs/{mms_id}Operate on a BIB recordUnlinking from a network zone record

Normalization

This parameter is the ID of the normalization process to be used.
Normalization process ID is displayed in Alma UI (Configuration Menu > Resources > Cataloging > Metadata Configuration > Normalization Processes):
In addition, it is possible to retrieve the list of possible normalization processes by performing the API with normalization=XX (or any other value).
The API will return 400 HTTP response, and a list of valid values for this parameter. For example:
<web_service_result>
 <errorsExist>true</errorsExist>
  <errorList>
    <error>
       <errorCode>4022030</errorCode>
       <errorMessage>Invalid normalization profile ID. Received: XX. Valid IDs for records of type MARC21 are (displayed here followed by profile name): [13882045410001021 - change 940,18131658140001021 - Add BIB to Collection,43552 - Remove Vendor Data 980 981 993]</errorMessage>
    </error>
  </errorList>
</web_service_result>
In the above example there are 3 normalization processes that might be used. Valid values are 13882045410001021,  940,18131658140001021 or  43552. 
 
Note that the list of valid normalization processes is sensitive to cataloging format. In the create BIB API the default format is MARC21. In order to create a BIB in a different format, and retrieve the relevant normalization options, record_format field of the BIB to create must be specified in the payload. For example:
<record_format>unimarc</record_format>
In the update BIB API the list of valid normalization process ids will be according to the format of the existing record.

Validation

The validate parameter is a boolean parameter. default is false.
If validate=true is retrieves, the "Bib validation on save" validation process will be launched. If validation has failed, the records will not be saved. 400 HTTP response will be returned, with a list of validation errors. For example:
<web_service_result>
 <errorsExist>true</errorsExist>
   <errorList>
     <error>
       <errorCode>4022032</errorCode>
       <errorMessage>The record failed validation with the following errors: [Mandatory field LDR is missing; Mandatory field 245 is missing]</errorMessage>
     </error>
    </errorList>
 </web_service_result>

Cataloger level

This is relevant for institutions that use cataloging privileges (see OLH for more details).
There are 2 values related to cataloging privileges in the bibs APIs:cataloger_level parameter and cataloging_level field in the payload.
cataloger_level parameter is the level of the user which performs changes for an existing record, or trying to delete it. This level will be compared to the existing level of the record. If equal or greater, update or delete is allowed.
cataloging_level in the payload is the level to be set for the record.
The 2 values are not necessarily the same.
Both values are the cataloger level code. Possible codes are listed in 'CatalogerLevel' code table, and can be retrieved using the GET code table API.

Stale version check

The 005 field of a Marc record includes the data and time of latest transaction.
When a staff user updates a bib record, Alma checks this field in order to determine whether the record has updated while the staff was working on it. If 005 field in the data to update is different than the 005 value of the record in the database, the update action will be prevented.
In order to perform this check when updating a bib record by API, stale_version_check=true parameter should be sent.

Warnings and override

When attempting to delete a bib record using an API, Alma checks if the bib can be deleted. If not, 400 http response will be returned, including the reason. For example:
<web_service_result>
  <errorsExist>true</errorsExist>
    <errorList>
      <error>
         <errorCode>4022020</errorCode>
         <errorMessage>Could not delete Bib: Record (MMS ID: 99107778730001452) has failed to be deleted, reason - Record has inventory.</errorMessage>
      </error>
    </errorList>
</web_service_result>
In order to delete the record despite the error, you should submit the delete bib record API with override=true.

Network zone link and unlink

This parameter is relevant for institutions in a network topology (see OLH for more details).
In a network topology, institutions might link their bib records to the network bibs, and benefit from updates in the network. In order to create a local bib record, linked to a network bib record, the from_nz_mms_id parameter should be used:
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. In case an institution bib record that is linked to the NZ record already exists, an error message will be returned.
Note that network zone mms id must be known. It is possible to search the network using SRU in order to find it.
It is also possible to unlink the local bib record from the network bib. This is done by the following API:
POST /almaws/v1/bibs/{mms_id}?op=unlink_from_nz
The API expects payload, so an empty bib object will be enough: <bib/>
Additional information regarding APIs in a network topology is available here.