Tech Blog

How to use ALMA User API to write job_category field data to improve fulfillment network

How to use ALMA User API to write job_category field data to improve fulfillment network?

Why do we need to use Job category? We, as a member of fulfillment network, has to use Job category to properly identify the walk-in user category and apply related fulfillment unit rules. By this way, we can avoid the deficiency of User group which is inappropriately applied to walk-in user under the fulfillment network.

ALMA does provide a job named “Update/Notify Users” to update user records in batch. However, this job merely provides job description modification capability, not job category modification choice, which is shown as below.

So, we have to use ALMA User API to solve this problem. The first step is to retrieve the data from ALMA server and extract user records which we would like to add/modify Job category field. We use ALMA analytics to get the user primary id list which we give the file name of “User_Primary_ID.txt”.

We use ALMA User “Get” API and “User_Primary_ID.txt” file to retrieve all users’ records in XML format, and saved them into one file named “User_extracted_infor.txt”. The file contains about more than 800 users’ records in XML. The code is located in github at The screenshot is as below.

Then, we use Excel and ALMA analytics to create a file named “Users_infor_job_category.txt” which contains 4 fields. According to User Group Code, we assign the value for related job_category and Job_cateogry_description field for each user. Then, we save this spreadsheet into a file by format of “Text(Tab delimited)(*.txt)”.

If we open the file “Users_infor_job_category.txt” by using Notepad++, it looks like below.

We use the code to get primary id from User_extracted_infor.txt file (XML format) and find the matching primary id from the file named Users_infor_job_category.txt(tab delimited format), then write Job_category and Job_category_description into each user’s XML paragraph and save them back into ALMA User database. By this way all users’ Job_category and Job_category_description are updated. The User PUT code we used is located in github at

The way we run the PHP script is in command line mode, like below.

The GET PHP code runs very smooth. However, the PUT PHP code is interrupted several times with errors.

The first kinds of error is 400 error bad request: “The external id in DB does not fit the given value in xml  – external id cannot be updated.” We found if the XML user record has owner with SIS_temp, and if database user record has owner with SIS, this error will come out.

The second kinds of error is 400 error bad request: “Mandatory field is missing: user_role parameter MetadataType for role number xx”. We found for library faculty and staff who has multiple role except “Patron” role, this problem will happen. I guess that previously after migration, we allocate some roles to library faculty and staff. After two years, Ex Libris modified some rules for faculty and staff role, but did not force us to back to modify them to be compatible with those rules. So, when we use API to send these data back to ALMA server, those rules thought the incoming data violates those rules and refuse them with errors. Basically, for patrons who only has “Patron” role, there is no problem to put them back to server.

So be careful, the data extracted by using API User Get method from ALMA, cannot always be written back to ALMA server by using API User PUT method.

We hope this can help a little. You can also wait for OIT step in to re-write the Student information system code. However, if you have any user group is not covered by SIS update, this code may provide some help.

Andy Tang

Leave a Reply