1 of 22

Bunches of Batches of APIs:�Batch Item Record Creation using Grima

Raymond E. Deiser II

Kansas State University Libraries

ELSUG 2021

15 November 2021

1

2 of 22

Presentation Outline

Why use an API?
Establishing Item Record Layout
Modifying the Grima Configuration Files
Developing the API for Grima
Conclusion
Questions

2

I am hoping that the background information that I will be providing under the first two bullet points will be universal information that can be used when others are developing their API tool. I will be demonstration how to create a single Item Record using the Ex Libris Developer Network and then integrating that workflow into an API tool to batch create Item Records from a list of Holdings Id numbers.

I would like to point out that later in the presentation I will be referencing Grima which is a program that aids in developing small web-based tools to communicate with Alma via API. Grima was developed by Kathryn Lybarger and the coding can be found on github. Grima is open source, written in PHP, and can be ran from a web server or locally.

https://github.com/zemkat/grima

3 of 22

Why use an API?�

Alma’s Current Limitations

Manual Jobs
Import Profiles

Alma (REST) API’s do simple tasks (CRUD)

POST /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items

Create an item record

3

So, Why use an API? With Alma’s current limitations, there is not built-in tool to create Physical Item Records in batch within Alma for legacy data. The available Alma Manual Jobs do not cover Item Record Creation, just modification or withdrawing.

Inventory can be created in batch using Import Profiles, but this is not a viable solution if you already have Holdings Records established within Alma. If you are needing to batch create Item Records and Holdings Records for a set of Bibliographic Records, an Import Profile might be the easiest option for you.

REST APIs do simple tasks and modifications are often instantaneous, creating a streamlined workflow.

Application Programming Interface (API)

Create, Read, Update, and Delete (CRUD)

Alma (REST) APIs do simple tasks (CRUD)

4 of 22

Item Record Layout

How will the Item Record be used?

Making the Item Record Distinct

Does the Item Record need a Barcode?

4

Before the Item Records are Created in Batch, you need to identify which fields you want the API to populate when the Item Record is created. When deciding the Item Record layout consider the following:

How will the Item Record be used?

Will the Batch created Item Record be the permanent inventory record for the resource? Or will you have staff modify the Item Record as part of a larger project?

Making the Item Record Distinct so that they can be easily identified by staff

Add specific identifiers that can be used when creating Analytics Reports

Does the barcode field need to be populated?

Will you leave the barcode field blank or use Alma’s Barcode Generation to populate a barcode either a permenant or temporary one?

https://knowledge.exlibrisgroup.com/Alma/Product_Documentation/010Alma_Online_Help_(English)/Physical_Resource_Management/070_Configuring_Resource_Management/070_Configuring_the_Barcode_Generation_Method_and_Barcode_Validation

5 of 22

Item Record Layout cont.

5

Any field within the Item record can be populated by an API. The two images here provide you with an example of what fields were populated by via API.

I would like to point out that technically the barcode field was not populated by the API but that the Barcode Generation Configuration was setup within Alma when the API created the Item Record. By leaving the barcode field blank in the body of the API Alma will automatically generate the barcode when the Item record is created.

Before the Item Records are Created in Batch, you need to identify which fields you want the API to populate when the Item Record is created. When deciding the Item Record layout consider the following:

How will the Item Record be used?

Will the Batch created Item Record be the permanent inventory record for the resource? Or will you have staff modify the Item Record as part of a larger project?

Making the Item Record Distinct so that they can be easily identified by staff

Add specific identifiers that can be used when creating Analytics Reports

Does the barcode field need to be populated?

Will you leave the barcode field bland or use Alma’s Barcode Generation to populate a barcode either a permenant or temporary one?
https://knowledge.exlibrisgroup.com/Alma/Product_Documentation/010Alma_Online_Help_(English)/Physical_Resource_Management/070_Configuring_Resource_Management/070_Configuring_the_Barcode_Generation_Method_and_Barcode_Validation

6 of 22

Test Item Record

Manually Create an Item Record

Ex Libris Developer Network

GET /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid}

6

After Identifying the Item Record Fields you want populated by the API, I recommend creating a test record. Within the Alma Sandbox Environment, Create an Item Record that will reflect the Item Records that will be created in batch.

Because we will be creating a brand new record using an API, we need to make sure the request body contains the fields we want to populate. The easiest way to do this is to retrieve the xml form of an Item Record already created in Alma. This can be done using the Ex Libris Developer Network API Console.

I am going to

https://developers.exlibrisgroup.com/alma/apis/

Retrieve Item Record:

https://developers.exlibrisgroup.com/alma/apis/docs/bibs/R0VUIC9hbG1hd3MvdjEvYmlicy97bW1zX2lkfS9ob2xkaW5ncy97aG9sZGluZ19pZH0vaXRlbXMve2l0ZW1fcGlkfQ==/

Create Item Record: https://developers.exlibrisgroup.com/alma/apis/docs/bibs/UE9TVCAvYWxtYXdzL3YxL2JpYnMve21tc19pZH0vaG9sZGluZ3Mve2hvbGRpbmdfaWR9L2l0ZW1z/

7 of 22

7

I am going to play a video that I created early demonstrating how to use the API Console to retrieve an Item Record and how to Create an Item record.

I have created an Item Record within Alma Sandbox, populating the fields you see here.

Within the API Console make sure the Server is the correct URL and that you are using an API Key that has Sandbox Read/write permissions.

I will be using the GET /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid} Retrieve Item and label printing information

Execute,

Now, to create an Item record within the API console we will need to provide the xml body. So copy the XML body and paste into your preferred editing program.

The only tags that are needed are for the fields we want to populate in the new Item Record. I have already done this, so I am going to copy the reduced xml body and paste it into the Create Item body. Make sure the Request body formt is xml and that the out put is xml too and click execute.

Refresh the Alma page and you can see that I have created a new Item Record using the API Console. I will use the xml body to aid in developing the Actions file for the Grima later in the presentation.

8 of 22

Grima Configuration Files

Update Item.xml template

grima>grimas>templates>Item.xml

Update grima-lib.php

grima>grimas>grima-lib.php

Line 2243 public static function getMmsFromHoldingID($holding_id)
Line 2435 class Item extends AlmaObject

8

9 of 22

��Grima Configuration Files cont.��Item.xml �

9

10 of 22

Grima Configuration Files cont.�grima-lib.php

10

11 of 22

�Grima Configuration Files�grima-lib.php cont.

11

12 of 22

Grima Configuration Files�grima-lib.php cont.�

12

13 of 22

Grima Body�Input and Actions

Directory

XML file—BatchItem.xml

Specifying the Input

PHP file—BatchItem.php

Contains the actions

Output—splats folder

OPTIONAL

Documentation

OPTIONAL

grima>grimas>BatchItem

13

14 of 22

Input--BatchItem.xml

14

15 of 22

Input--BatchItem.xml cont.

15

16 of 22

Actions—BatchItem.php

16

Here is the php file that will put together the Item Record Body for the API call.

{NEXT SLIDE}

First line: preg_split('/\r\n|\r|\n/',$this['holding_id'])

1st Alternative \r\n

\r matches a carriage return (ASCII 13)

\n matches a line-feed (newline) character (ASCII 10)

2nd Alternative \r

\r matches a carriage return (ASCII 13)

3rd Alternative \n

\n matches a line-feed (newline) character (ASCII 10)

$this['mms_id'] = Holding::getMmsFromHoldingID($holdingid)

makes the call to the Analytics report to retrieve the MMS Id

$holding->loadFromAlma($this['mms_id'],$holdingid);

Loads the Holdings Record Information

$item = new Item();

Everything that follows will be added to the Item Record Body to be created

$item->addToAlmaHolding($this['mms_id'],$holdingid);

Sends the call to Alma to create the Item Record

$this->addMessage('success',"Successfully added an Item Record to {$holdingid} with item PID: {$item['item_pid']}")

Successfully created

17 of 22

Actions—BatchItem.php

17

Line 9 uses Regular Expression so that each Holding Id number is passed through the Grima as a single number and not all of the numbers at once.

Line 11 takes the Holding ID and sends it through the Analytics Report to retrieve the MMS Id number.

Line 15 loads the Bib and Holding Data for the API body, so when I demonstrated retrieving the Item xml body using the API console it contained bibliographic and Holding record data, this is how it will be populated for the new Item Record.

{NEXT SLIDE}

Line 9: preg_split('/\r\n|\r|\n/',$this['holding_id'])

1st Alternative \r\n

\r matches a carriage return (ASCII 13)

\n matches a line-feed (newline) character (ASCII 10)

2nd Alternative \r

\r matches a carriage return (ASCII 13)

3rd Alternative \n

\n matches a line-feed (newline) character (ASCII 10)

Line 11:$this['mms_id'] = Holding::getMmsFromHoldingID($holdingid)

makes the call to the Analytics report to retrieve the MMS Id

Line 15:$holding->loadFromAlma($this['mms_id'],$holdingid);

Loads the Holdings Record Information

18 of 22

Actions—BatchItem.php

18

19 of 22

Actions—BatchItem.php

19

20 of 22

Running the Batch Item Grima

20

Running the Batch Item Grima

I am going to play a video that I created earlier to demonstrate running the Batch Item Grima. On the left side of the screen I have a set of 22 bibs and holdings without Item Records. So on the right I am going to populate the fulfillment note with “ROUTE TO DATABASE MAINTENANCE”, leave the Statistics Note 3 option as Physical Condition Review, and then finally paste the 22 Holdings Ids in the form and click submit.

Within the Sandbox Environment, APIs tend to run a little slow just like everything else. This took roughly 53 seconds to run and you can see the individual success message for each Holdings ID in green.

If we go back to Alma and refresh the page, you can see that the bibs have Item Records now. And if we open one up we can see that the API populated all of the fields we told it to. And If you look at the History you will see what the API did.

21 of 22

Resources

21

22 of 22

Questions

Raymond E. Deiser II

rdeiser@ksu.edu

https://lib.k-state.edu/

Kansas State University Libraries

22