update_doc

Ex Libris Developer Network Aleph Documentation Aleph APIs Aleph X-Services update_doc

General Purpose

The service performs actions (Update / Insert / Delete) related to the update of a document.

(The service uses pc_cat_c0203 which updates a document via the GUI).

Interface Type

X-Service

Product Version Compatibility

Version 18 and later

Input Parameters

1. LIBRARY – X (5).
2. USER_NAME . X (10).
3. USER_PASSWORD . X (10).
4. DOC_ACTION . X (10).
5. DOC_NUMBER . 9 (9).
6. XML_FULL_REQ . X (40000).

NOTE:

The input XML must be the OAI XML format of the given document.
You can use the find-doc X-Service to retrieve the OAI XML format for the given document and base.
Afterwards, you can change this XML in the places in the document which you want to change.
When sending a new record, the <varfield> tag must have its attributes in the specific order starting with the “id” attribute.
For example:
```
<varfield id="245" i1= "0" i2="1">
```
If the <varfield> tag is sent with different order of attributes (this is fully xml compliant),
for example:
```
<varfield i1= "0" i2="1" id="245">
```
(the id=”245″ is in the end) – then the action on the XML document is rejected, due to missing 245 field and unknown 0 field.

All logic issues regarding the updating procedure are identical to the updating procedure in the GUI.

In both cases (GUI and X-service) the same routine is in use.

Unlike other X-Services, the parameters can include XML up to 20,000 characters in length.

The usual GET /X option is not in use because of the limit in the number of bytes that can be transferred.

You need to create a CGI script that calls the X-Service (update-doc) and sends the parameters using the POST method.

Library: Type the name of the library in which the document to be updated is located.
User_name: Type the user name for performing the update. The permission check is for CATALOG UPDATE and CATALOG DELETE
User_password: Type the user password for the permission check.
Doc_action: Fill in the action to be performed on the given document.
- If you insert action = UPDATE, updating takes place provided there are no mandatory errors.
- If you insert action = UPDATE-CHK, a list of errors will appear in the output XML along with their types (warning, trigger, mandatory). Note that with the UPDATE-CHK action – if there are no errors of any type (warning, trigger, mandatory), then update will take place.
- If you insert action = DELETE the document you supply is deleted.
Doc_number / doc_num / doc-number/ doc-num: The document’s number to be updated. If you want to insert a new document, then the doc_number you supply should be all zeroes.
Xml_full_req: This is the input XML representing the appropriate document to be updated.

Output XML Format

The output XML includes the Patron ID for which actions are taken and specifies how many records are to be inserted / updated / deleted per table. If the service is not executed properly, the XML generated includes an error message.

Example:
Let us assume you want to update document number 50388 in USM01.

To retrieve an OAI XML of this document, enter the following syntax:

http://ram19:8997/X?op=find-doc&doc_num=000050388&base=usm01

The output OAI XML is:

<?xml version = "1.0" encoding = "UTF-8"?>
<find-doc>
  <record>
    <metadata>
      <oai_marc>
        <fixfield id="FMT">BK</fixfield>
        <fixfield id="LDR">00000nam^^22002415i^4500</fixfield>
        <fixfield id="001">000050388</fixfield>
        <fixfield id="005">20170309144254.0</fixfield>
        <fixfield id="008">170223s2017^^^^nyu^^^^^^^^^^^000^0^eng^^</fixfield>
        <varfield id="010" i1=" " i2=" ">
          <subfield label="a">2017934891</subfield>
        </varfield>
        <varfield id="020" i1=" " i2=" ">
          <subfield label="a">9781484200292 (hard : alk. paper)</subfield>
        </varfield>
        <varfield id="040" i1=" " i2=" ">
          <subfield label="a">DLC</subfield>
          <subfield label="b">eng</subfield>
          <subfield label="e">rda</subfield>
          <subfield label="c">DLC</subfield>
        </varfield>
        <varfield id="042" i1=" " i2=" ">
          <subfield label="a">pcc</subfield>
        </varfield>
        <varfield id="245" i1="0" i2="0">
          <subfield label="a">Beginning python :</subfield>
          <subfield label="b">from novice to professional /</subfield>
          <subfield label="c">[edited by] Magnus Lie Hetland.</subfield>
        </varfield>
        <varfield id="263" i1=" " i2=" ">
          <subfield label="a">1703H</subfield>
        </varfield>
        <varfield id="264" i1=" " i2="1">
          <subfield label="a">New York, NY :</subfield>
          <subfield label="b">Springer Science+Business Media,</subfield>
          <subfield label="c">2017.</subfield>
        </varfield>
        <varfield id="300" i1=" " i2=" ">
          <subfield label="a">pages cm.</subfield>
        </varfield>
        <varfield id="856" i1="4" i2="2">
          <subfield label="u">http://www.apress.com/gp/book/9781590599822</subfield>
          <subfield label="x">About this book</subfield>
          <subfield label="3">About this book - Publisher page</subfield>
          <subfield label="y">About this book: Beginning Python - From Novice to Professional | Magnus Lie Hetland | Apress</subfield>
        </varfield>
        <varfield id="OWN" i1=" " i2=" ">
           <!--  ...  -->
        </varfield>
      </oai_marc>
    </metadata>
  </record>
  <session-id>7YJ655A38MITDBEXJNQ4HKLHH9IBI6BP49B5XGB99V548I1L89</session-id>
</find-doc>

To update the title (field 245) to document for testing instead of document for update doc x-service, change the title in the input XML for the update-doc X-Service.

To perform an initial check in order to know what errors occur in the XML for update, edit the the CGI script. The parameters sent using the POST method should look like this:

op parameter should be set to: update-doc.
library parameter should be set to usm01.
doc_action should be set to UPDATE-CHK.
xml_full_req parameter will be set to an XML of the document along with the changes we would like to perform.

In our example, the following XML is generated:

<?xml version = "1.0" encoding = "UTF-8"?>
<find-doc>
  <record>
    <metadata>
      <oai_marc>
        <fixfield id="FMT">BK</fixfield>
        <fixfield id="LDR">00000nam^^22002415i^4500</fixfield>
        <fixfield id="001">000050388</fixfield>
        <fixfield id="005">20170309144254.0</fixfield>
        <fixfield id="008">170223s2017^^^^nyu^^^^^^^^^^^000^0^eng^^</fixfield>
        <varfield id="010" i1=" " i2=" ">
          <subfield label="a">2017934891</subfield>
        </varfield>
        <varfield id="020" i1=" " i2=" ">
          <subfield label="a">9781484200292 (hard : alk. paper)</subfield>
        </varfield>
        <varfield id="040" i1=" " i2=" ">
          <subfield label="a">DLC</subfield>
          <subfield label="b">eng</subfield>
          <subfield label="e">rda</subfield>
          <subfield label="c">DLC</subfield>
        </varfield>
        <varfield id="042" i1=" " i2=" ">
          <subfield label="a">pcc</subfield>
        </varfield>
        <varfield id="245" i1="0" i2="0">
          <subfield label="a">Testing DOC Beginning python :</subfield> <!--     /* Here is the change to be updated */ --> 
          <subfield label="b">from novice to professional /</subfield>
          <subfield label="c">[edited by] Magnus Lie Hetland.</subfield>
        </varfield>
        <varfield id="263" i1=" " i2=" ">
          <subfield label="a">1703H</subfield>
        </varfield>
        <varfield id="264" i1=" " i2="1">
          <subfield label="a">New York, NY :</subfield>
          <subfield label="b">Springer Science+Business Media,</subfield>
          <subfield label="c">2017.</subfield>
        </varfield>
        <varfield id="300" i1=" " i2=" ">
          <subfield label="a">pages cm.</subfield>
        </varfield>
        <varfield id="856" i1="4" i2="2">
          <subfield label="u">http://www.apress.com/gp/book/9781590599822</subfield>
          <subfield label="x">About this book</subfield>
          <subfield label="3">About this book - Publisher page</subfield>
          <subfield label="y">About this book: Beginning Python - From Novice to Professional | Magnus Lie Hetland | Apress</subfield>
        </varfield>
        <varfield id="OWN" i1=" " i2=" ">
           <!--  ...  -->
        </varfield>
      </oai_marc>
    </metadata>
  </record>
  <session-id>7YJ655A38MITDBEXJNQ4HKLHH9IBI6BP49B5XGB99V548I1L89</session-id>
</find-doc>

The output XML now includes the errors messages and the error types:

<?xml version="1.0" encoding="UTF-8" ?>
<update-doc>
<error>008/33: obsolete value ^.- warning error</error>
<error>/15-17: "^^^" is not a valid country code.- warning error</error>
<error>First indicator in tag "245" is not valid.- warning error</error>
<session-id>3CGFL7NXT2K392VA896FJ3D84QXK1G1GBDQB2UYMRA3DVSXNAR</session-id>
</update-doc>

According to the output, there are the errors, all warning errors. Since there are no mandatory errors, the actual update can take place (with mandatory errors, update is impossible and the X-service does not allow it). You can now send the same parameters with doc_action UPDATE.

After re-sending the parameters with the UPDATE action, the reply is:

<?xml version="1.0" encoding="UTF-8" ?>
<update-doc>
<error>008/33: obsolete value ^.- warning error</error>
<error>/15-17: "^^^" is not a valid country code.- warning error</error>
<error>First indicator in tag "245" is not valid.- warning error</error>
<error>Document: 000050388 was updated successfully.</error>
<session-id>PEE7K5N1EVINM94GFXUNICUQ1MQLDIMRGBBC2IUER3SKYEKLV7</session-id>
</update-doc>

Again, the errors are retrieved with their error types, but now another message has been added stating that the update for document number 50388 was successful.

The reason that the errors are retrieved again is so that you can UPDATE the document without first performing UPDATE-CHK. The X-service, in actual fact, performs UPDATE-CHK and sends the error messages and the types to the output XML, but at the same time, checks if there are mandatory errors. If there are none, it updates the document.

Possible Error Codes

1. If the document number given cannot be found under the given library, the following message appears. Since a default library might be given if no library has been entered, then the message might appear because a library has not been entered (or if the wrong number has been entered):

<error>Doc number given does not exist.</error>

2. If no XML input is provided:

<error>xml_full_req must be given as an input</error>

3. If no action is provided (UPDATE, UPDATE-CHK, and so on):

<error>Action must be supplied</error>

4. If no valid action is provided:

<error>Invalid action given.</error>

5. If the action given is REPLACE but no doc_number has been provided:

<error> Action cannot be REPLACE without giving doc number.</error>

6. If the document requested for update is already locked by another user when the update is about to be performed:

<error>Record is currently locked by another user. Your changes will not be saved on the server.</error>

7. If the cataloger in the input XML is different from the last cataloger in the actual document:

<error>Record was updated by another user. Your changes will not be saved on the server.</error>

8. If an error occurs while trying to lock the document:

<error>Error in locking the document.</error>

9. If the level of the cataloger trying to update the doc is lower than the last cataloger that updated the document:

<error>Record was last updated by a higher level cataloger. Your changes will not be
saved on the server.</error>

10. If the document number given for a new document already exists:

<error>The record number already exists, change the “last-doc-number” counter.</error>

11. If an error occurs while trying to unlock the document:

<error>Error unlocking record.</error>

12. If a user tries to delete a document without delete permission:

<error>Permission denied for delete operation.</error>

The rest of the error messages related to check doc, are generated from $aleph_error_eng/xml_update_doc table. They are the warning, trigger, and mandatory errors generated when trying to update a document. Note that locally defined error messages in the Library’s check_doc.<lng> are not displayed.