update_item
General Purpose
The service updates an existing item in the required ADM library after performing all relevant initial checks prior to that action.
Interface Type
X-Service
Product Version Compatibility
Version 20
Input Parameters
1. XML_FULL_REQ – X (20000).
2. LIBRARY – X (5).
Xml_Full_Req: This is the input xml representing the new item. It is detailed in the example. This is a mandatory parameter.
Library: This is a mandatory parameter to determine the Administrative library of the item to be updated.
NOTE:
- It is possible to update the Item’s barcode. Updating can be configured to work with the barcode checksum mechanism. For example when no barcode is sent in the input XML, it can be created by the checksum mechanism. If a barcode is sent, it can be corrected and validated using this mechanism.
- If a barcode is changed for a temporary item that arrived as a result of an ILL borrowing request, the relevant ILL borrowing request record (Z411) is updated with this new item’s barcode.
- It is impossible to change doc_number or item_sequence.
- All validation checks and corrections are done similar to creating an item via the Cataloging module.
If the sub-library or item-status are updated and the item used to or is about to be an advance booking item, the relevant records are deleted or updated with the new data (Z320/Z321). - The X-Service expects an input XML containing the Item’s record with the updated fields. The doc_number and item_sequence MUST be included in that XML because this information is used to update the item. There are two options for structure of the input XML as follows:
- Full Item record (Z30) is sent via XML with all values within it.
- A partial Item record is sent via XML.
The key to the table (doc & item sequence) must be included and only the fields to be updated are included in the XML. Fields not to be changed are NOT included in the XML. All fields not included in the XML remain the same.
- 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 Update-Item X-Service is for WWW-X / UPD-ITEM.
Output XML Format
The output XML includes the following information:
- The item’s record (Z30).
- The Success / Failure message for updating a new item.
- A reason is supplied in case of a failure.
Update-Item X-Service Activation
Activation is done using the HTTP protocol with POST method. The Create-Item requires an XML input file and as such, it cannot be activated using a regular GET method (simple URL). The application creating the POST request must contain the following mandatory parameters:
1. op=update-item.
2. library=ADM library of the Item to be updated.
3. xml_full_req=The xml containing the updated values 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 to Read-Item X-Service as well.
1. con_lng=Default is ENG (English)
2. translate=Default is ‘Y,’ meaning use the Aleph translate mechanism.
3. session_id=Each Aleph X-Service retrieves session_id in its output XML. It contains the user’s details and can be used to continue using other X-Services with this user.
4. user_name=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=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.’
Example for activating Update-Item X-Service using a Perl application:
Assume the input XML representing the Item to be updated is as follows:
./adm_library/scratch/item_to_update.xml
The file can look like the following:
<?xml version="1.0" encoding="UTF-8" ?>
<update-item>
<z30>
<z30-doc-number>51077</z30-doc-number>
<z30-item-sequence>10</z30-item-sequence>
<z30-barcode>B51872</z30-barcode>
<z30-sub-library>WID</z30-sub-library>
<z30-material>BOOK</z30-material>
<z30-item-status>01</z30-item-status>
<z30-open-date>20011017</z30-open-date>
<z30-update-date>20020516</z30-update-date>
<z30-cataloger>EXLIBRIS</z30-cataloger>
<z30-date-last-return>20080419</z30-date-last-return>
<z30-hour-last-return>1631</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>GEN</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-key>
<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>BD</z30-item-process-status>
<z30-copy-id>1</z30-copy-id>
<z30-hol-doc-number></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>
</update-item>An example for a Perl application (for programmers) called ‘update_item.pl:’
...
use strict;
require LWP::UserAgent;
$| = 1; # unbuffered output
my $ua = LWP::UserAgent->new;
$ua->timeout(30);
$ua->env_proxy;
my $data;
my $in_file = shift or die "input XML file needed\n";
open( IN_F, $in_file) or die "Cannot open file as input\n" ;
while (<IN_F>) { $data.=$_; }
my $url= 'http://localhost:'.$ENV{'HTTPD_PORT'}.'/X';
my %form;
$form{'xml_full_req'} = $data;
$form{'op'} = 'update_item' ;
$form{'library'} = 'usm50' ;
my $res = $ua->post("$url",\%form);
if ($res->is_success) {
print ($res->content);
printf "\n--------------------\nfetched %d bytes\n", length($res->content);
} else {
print "\nError: " . $res->code . " " . $res->message;
}To activate Update-Item X-Service with this Perl application on the input file, use the following:
perl update_item.pl item_to_update.xml
The Update-Item X-Service is activated in order to update item in the USM50 library.
Update-Item X-Service reply example:
If this processed successfully, the output XML contains all the relevant information.
<?xml version = "1.0" encoding = "UTF-8"?> <update-item> <z30> <z30-doc-number>50706</z30-doc-number> <z30-item-sequence>10</z30-item-sequence> <z30-barcode>B51872</z30-barcode> <z30-sub-library>Main Library</z30-sub-library> <z30-material>Book</z30-material> <z30-item-status>At bindery</z30-item-status> <z30-open-date>17/10/2001</z30-open-date> <z30-update-date>21/11/2018</z30-update-date> <z30-cataloger>WWW-X</z30-cataloger> <z30-date-last-return>19/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 heb 2106.385.5</z30-call-no-key> <z30-call-no-2-type></z30-call-no-2-type> <z30-call-no-2></z30-call-no-2> <z30-call-no-2-key></z30-call-no-2-key> <z30-description>v.1</z30-description> <z30-note-opac></z30-note-opac> <z30-note-circulation></z30-note-circulation> <z30-note-internal></z30-note-internal> <z30-order-number></z30-order-number> <z30-inventory-number></z30-inventory-number> <z30-inventory-number-date></z30-inventory-number-date> <z30-last-shelf-report-date>00000000</z30-last-shelf-report-date> <z30-price></z30-price> <z30-shelf-report-number></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-vendor-code> <z30-invoice-number></z30-invoice-number> <z30-line-number>00000</z30-line-number> <z30-pages></z30-pages> <z30-issue-date></z30-issue-date> <z30-expected-arrival-date></z30-expected-arrival-date> <z30-arrival-date></z30-arrival-date> <z30-item-statistic></z30-item-statistic> <z30-item-process-status>BD</z30-item-process-status> <z30-copy-id>1</z30-copy-id> <z30-hol-doc-number>000000000</z30-hol-doc-number> <z30-temp-location>No</z30-temp-location> <z30-enumeration-a></z30-enumeration-a> <z30-enumeration-b></z30-enumeration-b> <z30-enumeration-c></z30-enumeration-c> <z30-enumeration-d></z30-enumeration-d> <z30-enumeration-e></z30-enumeration-e> <z30-enumeration-f></z30-enumeration-f> <z30-enumeration-g></z30-enumeration-g> <z30-enumeration-h></z30-enumeration-h> <z30-chronological-i></z30-chronological-i> <z30-chronological-j></z30-chronological-j> <z30-chronological-k></z30-chronological-k> <z30-chronological-l></z30-chronological-l> <z30-chronological-m></z30-chronological-m> <z30-supp-index-o></z30-supp-index-o> <z30-85x-type></z30-85x-type> <z30-depository-id></z30-depository-id> <z30-linking-number>000000000</z30-linking-number> <z30-gap-indicator></z30-gap-indicator> <z30-maintenance-count>007</z30-maintenance-count> <z30-process-status-date>20181121</z30-process-status-date> <z30-upd-time-stamp>201811210803505</z30-upd-time-stamp> <z30-ip-last-return-v6></z30-ip-last-return-v6> </z30> <error>Item has been updated successfully</error> <session-id>5F8BR7PXP25F2Q7R71JLHAY2CBXGU1IAKCTRKQA78EKY5ED7AT</session-id> </update-item>
Possible Error Codes
1. If no item exists based on the given doc_number and item_sequence in the input XML, the following message is displayed in the output XML:
< error>no item exist based on given doc number and item sequence</error>
2. All regular validity checks and error messages as they appear in the error table h_error_eng/check_z30 might occur and display in the output xml.
< error>Input ADM document doesn’t exist. Item cannot be created</error>
3. If for some reason the item could not be updated, the following message is displayed in the output xml:
< error>Failed to update the item </error>
4. 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>
5. If an xml was not provided, the following message is displayed in the output xml:
< error>xml must be provided to update Item </error>
6. If the item used to be an advance booking item and its sub-library or item status was changed in a way that requires a change in the advance booking item’s data but that item has advance booking requests, the following message is displayed:
< error> Item has Short-term requests. Item Information can’t be updated</error>