Ready to Learn?Ex Libris products all provide open APIs

read_item

General Purpose

The service retrieves a requested item's record from a given ADM library in case such an item does exist in that ADM library.

 

Interface Type

X-Service

 

Product Version Compatibility

Version 20

 

Input Parameters

1. LIBRARY - X (5).
2. DOC_NUMBER - X (9).
3. ITEM_SEQUENCE - X (6).
4. ITEM_BARCODE - X (30).
 

  • Library: This is a mandatory field. This should be the ADM library of the item requested to be retrieved.
  • Doc_Number & Item_Sequence: Together, these two parameters point at a single unique item within the ADM library.
  • Item_Barcode: This is a unique identifier of a single item within the ADM library.

    NOTE:
  • It is not mandatory to send all parameters. If you would like to choose an item by its doc_number and item_sequence, the item_barcode parameter is not mandatory. If you would like to choose an item by its barcode, the parameters doc_number and item_sequence are not mandatory.
  • If all parameters are sent, but the doc_number & item_sequence point at the item while the item_barcode points at another item, the item pointed out by the doc_number and item_sequence are retrieved. A message is added to the XML indicating that only one item has been retrieved.
  • Permission - Each X-Service has its own permission. This enables the Aleph permission mechanism to vary between different X-Services relative to who is allowed to activate an X-Service and which X-Service. The permission is built from the Func / Sub-Func. The permission for Read-Item X-Service is for WWW-X / READ-ITEM.

 

Output XML Format

The output XML includes the following information:
 

  • The item's record (Z30) in case an item was found based on input parameters.
  • A reason is supplied in case of a failure.

 

Read-Item X-Service Activation

As with any other Aleph X-Service, activation is done using HTTP protocol with GET/POST methods. The Read-Item doesn't require an XML input file and can be activated using a GET method (simple URL). The application creating the GET request must contain the following mandatory parameters:

1. op=read-item.
2. library=ADM library of the Item to be retrieved.
3. doc_number & Item_sequence=Points at a unique Item.
OR
4. item_barcode=Points at a unique Item.

Aside from these three mandatory parameters, there is a list of non-mandatory parameters that can be sent to any Aleph X-Service and in a similar manner to Read-Item X-Service as well.

1. con_lng=The default is ENG (English)
2. translate=The default is 'Y,' which means use the Aleph translate mechanism.
3. session_id=Each Aleph X-Service retrieves the session_id in its output XML. It contains the user's details within it and can be used to continue using other X-Services with this user.
4. user_name=This is the staff user activating the X-Service. The permission granted to activate the X-Service is checked for this staff user. The default is 'WWW-X.'
5. user_password=This is the password for the staff user activating the X-Service. The permission granted to activate the X-Service is checked for this staff user. The default is 'WWW-X.'

The two URLs below provide the same reply. Note that in the first URL, the item is requested by its doc_number and item_sequence while in the second URL, it is requested by the item_barcode.
 

http://il-aleph07:8991/X?op=read-item&library=usm50&doc_number=000012224&item_sequence=000020
http://il-aleph07:8991/X?op=read-item&library=usm50&item_barcode=293



Example:

If everything processes successfully, the XML output appears as follows:

<?xml version="1.0" encoding="UTF-8" ?>
- <read-item>
- <z30>
  <z30-doc-number>15</z30-doc-number>
  <z30-item-sequence>10</z30-item-sequence>
  <z30-barcode>32044003924339</z30-barcode>
  <z30-sub-library>Main Library</z30-sub-library>
  <z30-material>Book</z30-material>
  <z30-item-status>Regular loan</z30-item-status>
  <z30-open-date>13/10/1988</z30-open-date>
  <z30-update-date>08/07/2002</z30-update-date>
  <z30-cataloger>EXLIBRIS</z30-cataloger>
  <z30-date-last-return>08/04/2008</z30-date-last-return>
  <z30-hour-last-return>16:31</z30-hour-last-return>
  <z30-ip-last-return>CONV</z30-ip-last-return>
  <z30-no-loans>011</z30-no-loans>
  <z30-alpha>L</z30-alpha>
  <z30-collection>General</z30-collection>
  <z30-call-no-type>7</z30-call-no-type>
  <z30-call-no>Heb 2106.385.5</z30-call-no>
  <z30-call-no-key>7 selected
  <z30-call-no-2-type />
  <z30-call-no-2 />
  <z30-call-no-2-key />
  <z30-description>v.1</z30-description>
  <z30-note-opac />
  <z30-note-circulation />
  <z30-note-internal />
  <z30-order-number />
  <z30-inventory-number />
  <z30-inventory-number-date />
  <z30-last-shelf-report-date>00000000</z30-last-shelf-report-date>
  <z30-price />
  <z30-shelf-report-number />
  <z30-on-shelf-date>00000000</z30-on-shelf-date>
  <z30-on-shelf-seq>000000</z30-on-shelf-seq>
  <z30-doc-number-2>000000015</z30-doc-number-2>
  <z30-schedule-sequence-2>00000</z30-schedule-sequence-2>
  <z30-copy-sequence-2>00000</z30-copy-sequence-2>
  <z30-vendor-code />
  <z30-invoice-number />
  <z30-line-number>00000</z30-line-number>
  <z30-pages />
  <z30-issue-date />
  <z30-expected-arrival-date />
  <z30-arrival-date />
  <z30-item-statistic />
  <z30-item-process-status>XX</z30-item-process-status>
  <z30-copy-id>1</z30-copy-id>
  <z30-hol-doc-number>000000046</z30-hol-doc-number>
  <z30-temp-location>No</z30-temp-location>
  <z30-enumeration-a />
  <z30-enumeration-b />
  <z30-enumeration-c />
  <z30-enumeration-d />
  <z30-enumeration-e />
  <z30-enumeration-f />
  <z30-enumeration-g />
  <z30-enumeration-h />
  <z30-chronological-i />
  <z30-chronological-j />
  <z30-chronological-k />
  <z30-chronological-l />
  <z30-chronological-m />
  <z30-supp-index-o />
  <z30-85x-type />
  <z30-depository-id />
  <z30-linking-number>000000000</z30-linking-number>
  <z30-gap-indicator />
  <z30-maintenance-count>007</z30-maintenance-count>
  <z30-process-status-date>20080408</z30-process-status-date>
  </z30>
  <session-id>G926LP7AN9JLVET1VTFXLRLVL1H5SII7HV1QPMTESUIMQBN5SV</session-id>
  </read-item>

 

Possible Error Codes

1. If no item exists based on the given doc_number and item_sequence, the following message is displayed in the output XML:

< error>Item could not been found based on doc number: XXX and item sequence: YYY</error>

2. If no item exists based on the given item_barcode, the following message is displayed in the output XML:

< error>Item could not been found based on item barcode: ZZZ </error>

3. If the input library is not an ADM library, the following message is displayed in the output xml:

< error>Input library must be an Administrative library </error>

4. If no library is supplied, the following message is displayed in the output xml:

< error>Library must be included in service params </error>

5. If only the doc_number was supplied without the item_sequence or item_barcode, the following message is displayed in the output xml:

< error>Please provide item sequence or item barcode </error>

6. If only the Item_sequence was supplied without the doc_number or item_barcode, the following message is displayed in the output xml:

< error> Please provide doc number or item barcode </error>

7. If all parameters were sent, but the doc_number & Item_sequence points at one item and the item_barcode points at another item, the following message is displayed in the output xml:

< error> Note that input item barcode: XXX is a different item than doc number and item sequence. It was not retrieved </error>

8. If no doc number, item sequence, or item barcode was provided, the following message is displayed in the output xml:

< error>Item key must be given. Provide doc number and item sequence or item barcode </error>