create_item

General Purpose

The service creates a new item in the required ADM library after performing all relevant initial checks prior to that action.

The item can be created for a bib record when no ADM record is linked to it yet, or it can be created to an ADM record with existing items.

Interface Type

X-Service

Product Version Compatibility

Version 20

Input Parameters

1. XML_FULL_REQ – X (20000).
2. ADM_LIBRARY – X (5).
3. ADM_DOC_NUMBER – X (9).
4. BIB_LIBRARY – X (5).
5. BIB_DOC_NUMBER – X (9).

Xml_Full_Req: This is the input XML representing the new item. It is detailed in the example. Mandatory parameter.

Adm_Library: This is a mandatory parameter to determine the Administrative library in which new item is to be created.

Adm_Doc_Number: This parameter is not mandatory. It should be used when the new item should be created for an already existing ADM record. But if this parameter is provided and there is no such ADM record, then service is aborted.

Bib_Library: This parameter is not mandatory. It should be used when the new item should be created for a bib record. If no Adm_Doc_Number is specified, then this parameter is a must.

Bib_Doc_Number: The same as Bib_Library.

NOTE:
The value in the input XML file is ignored in any case. If Adm_Doc_Number is given, then this will be the z30-doc-number. If no Adm_Doc_Number is given, then it is determined by the new ADM record’s number, created based on the input Bib Doc Number.
In any case, the new item’s sequence is calculated by Aleph, so this can be left zeroed out.
The item’s barcode creation can be configured to work with the barcode checksum mechanism so that when no barcode is sent in the input XML, it can be created by the checksum mechanism and if a barcode is sent, it can be corrected and validated using this mechanism.

The z30-no-loans field is zero, regardless of what exists in the input XML file.

The z30-open-date/z30-update-date fields have a creation date, regardless of what exists in the input XML file.

All validations, checks, and corrections are done in the same manner as creating an item via the Cataloging module.

If the new item is configured to be an advance booking item, then create a relevant record for the item (Z320/Z321).

Permission – Each X-Service has its own permission. This way, the Aleph permission mechanism can vary between different X-Services in terms of who is allowed to activate an X-Service and which X-Services can be activated. The permission is built from the Func / Sub-Func. The permission for Create-Item X-Service is for WWW-X / CRE-ITEM.

Output XML Format

The output XML includes the following information:

  • Item’s record (Z30).
  • Success / Failure message for creating new item.
  • In case of a failure, a reason is supplied.

Create-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=create-item
2. library=ADM library of the item to be created.
3. xml_full_req=The XML containing the new 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 this manner, to Create-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 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=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 Create_Item X-Service using a Perl application:

Assuming the input XML representing the item to be created is:

./adm_library/scratch/new_item_to_create.xml

The file looks like this:

<?xml version="1.0" encoding="UTF-8" ?>
  <z30>
  <z30-doc-number>15</z30-doc-number>
  <z30-item-sequence>10</z30-item-sequence>
  <z30-barcode>32044003924339</z30-barcode>
  <z30-sub-library>WID</z30-sub-library>
  <z30-material>BOOK</z30-material>
  <z30-item-status>01</z30-item-status>
  <z30-open-date>19980804</z30-open-date>
  <z30-update-date>20020708</z30-update-date>
  <z30-cataloger>EXLIBRIS</z30-cataloger>
  <z30-date-last-return>20080607</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>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>

An example for a Perl application (for programmers) called ‘create_new_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'}            = 'create_item' ;
$form{'adm_library'}       = 'usm50' ;
$form{'bib_library'}       = '' ;
$form{'adm_doc_number'}       = '000000015' ;
$form{'bib_doc_number'}       = '' ;

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 Create-Item X-Service with this Perl application on the input file:

perl create_new_item.pl new_item_to_create.xml

That way the Create-Item X-Service is activated in order to create a new item in the USM50 library.

Create-Item X-Service reply example:

If the above is successful, the output XML contains all relevant information:

<?xml version="1.0" encoding="UTF-8" ?>
  <create-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-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>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>
  <error>Item has been created successfully</error>
  <session-id>G926LP7AN9JLVET1VTFXLRLVL1H5SII7HV1QPMTESUIMQBN5SV</session-id>
  </create-item>

Possible Error Codes

1. If no Adm_Doc_Number nor Bib_Doc_Number is provided, then the following message is displayed in the output XML:

< error>ADM doc number or a BIB doc number must be provided</error>

2. If a non-exist adm_doc_number was supplied for the new item, then the following message is displayed in the output XML:

< error>Input ADM document doesn’t exist. Item cannot be created</error>

3. All regular validity checks and error messages as they appear in error table h_error_eng/check_z30 might occur and display in the output XML.

4. If no adm_doc_number is provided and the Bib_Doc_Number provided does not exist in Bib_Library provided, then the following message is displayed in the output XML:

< error>Input BIB document doesn’t exist. Item cannot be created </error>

5. If from some reason item could not be created, then the following message is displayed in the output XML:

< error>Failed to create the item. Please try again </error>

6. If the input adm_library is not an ADM library, then the following message is displayed in the output XML:

< error> An Administrative library must be provided</error>

7. If an xml was not provided, then the following message is displayed in the output XML:

< error> xml must be provided to create an item </error>

8. If a failure occurred while trying to create ADM record for a given Bib document, then the following message is displayed in the output XML:

< error>Failed to create new ADM document based on Bib library and document. Item cannot be created </error>

9. If the input XML specified a barcode to be given to the new Item and there is already an Item with that Barcode, then the following message is displayed in the output XML:

< error>There is already an item matching given barcode. Cannot create item </error>

10. If a failure occurred while trying to create the new item, then the following message is displayed in the output XML:

< error> Failed to create new item</error>