Tech Blog

Managing vendor collections using the Provider Zone API

This blog will describe in detail the process of managing vendors’ collections using the Provider Zone API. Vendors who were given access to manage their own content in the Alma Community Zone will be able to add new collections and portfolios, and optionally bibliographic records. Additionally, vendors can take ownership of their existing Community Zone collections (based on a list provided by Ex Libris) and manage them by adding/updating/deleting portfolios that are part of the collections.

API key

In order for vendors to be able to manage their content in the Alma Community Zone using the Provider Zone API, an API key must be obtained. The key will be generated by Ex Libris upon agreement and will serve as a unique identifier for the vendor running the API.

An example for calling the API with the key on the URL:

POST https://api-na.hosted.exlibrisgroup.com/almaws/v1/providerzone/e-collection?apiKey=<api_key>

API payload (XML)

The API call must include a payload (XML) attached to it. The payload structure includes the following tags:

  • Collection name – mandatory
  • KBART title list – mandatory
    • Mode (the loading policy) – mandatory
      • “complete” – complete set of portfolios that are part of the collection
      • “incremental” – a sub set of portfolios that have been changed since the previous load
    • Link (full path to a KBART file) – mandatory
    • Action – mandatory for mode=”incremental”, not required for mode=”complete” (by default will perform the add, update and delete actions).
      For every title in the KBART file search for a corresponding portfolio in the collection using the identifier:
ActionMode=”complete”Mode=”incremental”
“add”
  • Upon multi match, reject portfolio
  • Upon match, do nothing
  • Upon no match, search for bib record:
    • Upon multi match, reject portfolio
    • Upon match to vendor or CZ bib record, create new portfolio and link to it
    • Upon no match, create a slim bib record
  • Upon multi match, reject portfolio
  • Upon match, do nothing
  • Upon no match, search for bib record:
    • Upon multi match, reject portfolio
    • Upon match to vendor or CZ bib record, create new portfolio and link to it
    • Upon no match, create a slim bib record
“update”
  • Upon multi match, reject portfolio
  • Upon match, update portfolio
  • Upon no match, do nothing
  • Upon multi match, reject portfolio
  • Upon match, update portfolio
  • Upon no match, do nothing
“delete”
  • Portfolios that exist under the vendor collection but not in the file will be deleted
  • Portfolios that do not exist under the vendor collection but do exist in the file will be created
  • Upon match, delete portfolio
  • Upon no match, do nothing
  • Marc file link (full path to a Marc XML file) – optional
  • Email (the email the report will be sent to) – optional

Payload structure:

<pzparameters>
  <collection_name>collection_name</collection_name>
  <kbart_title_list>
    <mode>[complete|incremental]</mode>
    <link>http://kbart_file_path/kbart_title_list.txt</link>
    <actions>
      <action>[add|update|delete]</action>
    <actions/>
  </kbart_title_list>
  <marc_file_link>http://marc_file_path/file.mrc</marc_file_link>
  <email>provider_email@provider_zone.com</email>
</pzparameters>

KBART Input File

The Provider Zone API uses a KBART format file with the electronic portfolio information. The payload (XML) provided to the API includes a link to the KBART file. The file can be retrieved via HTTP or FTP. The file will processed to create/update the collection portfolios based on the selected mode and actions defined on the payload.

The following table includes the supported KBART columns:

KBART columnDescriptionMandatory
publication_titleTitleV
print_identifierISBNV
online_identifierISSNV
date_first_issue_onlineFrom year
num_first_vol_onlineFrom volume
num_first_issue_onlineFrom issue
date_last_issue_onlineTo year
num_last_vol_onlineTo volume
num_last_issue_onlineTo issue
title_urlURL
publisher_namePublisher
first_authorAuthor
embargo_infoEmbargo

An example for a KBART file structure can be found here: kbart file structure.

Marc XML Input File

Vendors have the option to manage their own bibliographic records related to the portfolios that are part of the collection. This can be done by supplying the link to a Marc XML file on the API payload. The bibliographic data in this file should be in a Marc XML format.

An example for a Marc XML file:

<?xml version="1.0" encoding="UTF-8"?>
<collection>
  <record>
    <leader>00988nam  2200313 a 4500</leader>
    <controlfield tag="001">99112208980001021</controlfield>
    <controlfield tag="004">AEA5098</controlfield>
    <controlfield tag="005">20140609201721.0</controlfield>
    <controlfield tag="008">120610s1989    nyua          001 0 eng  </controlfield>
    <datafield tag="010" ind1=" " ind2=" ">
      <subfield code="a">88014446</subfield>
    </datafield>
    <datafield tag="020" ind1=" " ind2=" ">
      <subfield code="a">0385244320 :</subfield>
      <subfield code="c">$19.95</subfield>
    </datafield>
    <datafield tag="035" ind1=" " ind2=" ">
      <subfield code="a">(Aleph)000562490BCL01</subfield>
    </datafield>
    <datafield tag="035" ind1=" " ind2=" ">
      <subfield code="a">(OCoLC)ocm17841309</subfield>
    </datafield>
    <datafield tag="035" ind1="9" ind2=" ">
      <subfield code="a">AEA5098</subfield>
    </datafield>
    <datafield tag="040" ind1=" " ind2=" ">
      <subfield code="a">DLC</subfield>
      <subfield code="c">DLC</subfield>
    </datafield>
    <datafield tag="043" ind1=" " ind2=" ">
      <subfield code="a">n-us---</subfield>
    </datafield>
    <datafield tag="050" ind1="0" ind2=" ">
      <subfield code="a">E178.6</subfield>
      <subfield code="b">.G25 1989</subfield>
    </datafield>
    <datafield tag="082" ind1="0" ind2=" ">
      <subfield code="a">973</subfield>
      <subfield code="2">19</subfield>
    </datafield>
    <datafield tag="100" ind1="1" ind2=" ">
      <subfield code="a">Garraty, John Arthur,</subfield>
      <subfield code="d">1920-</subfield>
    </datafield>
    <datafield tag="245" ind1="1" ind2="0">
      <subfield code="a">1,001 things everyone should know about American history /</subfield>
      <subfield code="c">John A. Garraty.</subfield>
    </datafield>
    <datafield tag="246" ind1="3" ind2=" ">
      <subfield code="a">One thousand one things everyone should know about American history</subfield>
    </datafield>
    <datafield tag="246" ind1="3" ind2=" ">
      <subfield code="a">One thousand and one things everyone should know about American history</subfield>
    </datafield>
    <datafield tag="250" ind1=" " ind2=" ">
      <subfield code="a">1st ed.</subfield>
    </datafield>
    <datafield tag="260" ind1=" " ind2=" ">
      <subfield code="a">New York :</subfield>
      <subfield code="b">Doubleday,</subfield>
      <subfield code="c">c1989.</subfield>
    </datafield>
    <datafield tag="300" ind1=" " ind2=" ">
      <subfield code="a">viii, 207 p. :</subfield>
      <subfield code="b">ill. ;</subfield>
      <subfield code="c">27 cm.</subfield>
    </datafield>
    <datafield tag="500" ind1=" " ind2=" ">
      <subfield code="a">Includes index.</subfield>
    </datafield>
    <datafield tag="651" ind1=" " ind2="0">
      <subfield code="a">United States</subfield>
      <subfield code="x">History.</subfield>
      <subfield code="v">Miscellanea.</subfield>
    </datafield>
    <datafield tag="948" ind1=" " ind2=" ">
      <subfield code="a">LTI 08/08/2000</subfield>
    </datafield>
    <datafield tag="950" ind1=" " ind2=" ">
      <subfield code="a">OL</subfield>
    </datafield>
  </record>
</collection>

API response

  • The response of the API will be a detailed report that will be sent to the vendor’s email.
  • In addition, it can be accessed by calling the API with the job ID:
GET /almaws/v1/providerzone/jobs/create-collection/instances/{job_id}

Response example will be added soon

Leave a Reply