update_bor

General Purpose

This service performs various actions (Update / Insert / Delete) involving the updating of patron details.

Actions affect the Z303, Z304, Z305, and Z308 tables based on input XML specifying which action is to be taken on each table and on which patron. The XML includes all of the table’s data and is only for a single patron.

Interface Type

X-Service

Product Version Compatibility

Version 18 and later

Input Parameters

1. LIBRARY – X (5).
2. UPDATE_FLAG – X (1).
3. XML_FULL_REQ – X (20000).

NOTE:

  • All logical issues regarding available actions and validation checks are identical to those for the file-20 (PLIF – Patron Loader) service. Refer to the Help file of the Patron loader service in the Circulation GUI.
  • Unlike other X-Services, the parameters can include XML up to 20000 characters long. 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 to call the X-Service (update-bor) and send the parameters using the POST method.
  • Library: Insert the library in which the patron is stored (or will be stored).
  • Update_flag: This Y/N flag indicates whether or not the actions are transferred to the database. Enter N to view the output XML to predict changes if the database is updated with actually transferring the actions to the database. The default is N.
  • xml_full_req: This is the input XML which specifies changes to be performed for the given patron. There are two options for this XML structure:
    • Option 1: The regular XML structure used for this X-Service up until now.
    • Option 2: An Oracle table-based structure (based on the Z303, Z304, Z305 and Z308 tables), as created via UTIL/F/2/5/2. This utility is a user-friendly tool for creating an XML file for a patron which can be modified for subsequent use as XML input for this X-Service.

Example of XML input using Option 1:

<UPDATE-BOR>
        <USER-REC>    <!-- /* affects Z303 . Only one such record !! */ -->
          <USER-REC-ACTION></USER-REC-ACTION>
          <USER-REC-MATCH-ID-TYPE></USER-REC-MATCH-ID-TYPE>
          <USER-REC-MATCH-ID></USER-REC-MATCH-ID>
          <USER-REC-ID-1></USER-REC-ID-1>
          <USER-REC-ID-2></USER-REC-ID-2>
          <USER-REC-VERIFICATION-1></USER-REC-VERIFICATION-1>
          <USER-REC-VERIFICATION-2></USER-REC-VERIFICATION-2>
          <USER-REC-VERIFICATION-3></USER-REC-VERIFICATION-3>
          <USER-REC-NAME-TITLE></USER-REC-NAME-TITLE>
          <USER-REC-NAME></USER-REC-NAME>
          <USER-REC-BIRTH-DATE></USER-REC-BIRTH-DATE>
          <USER-REC-BUDGET></USER-REC-BUDGET>
          <USER-REC-EXPORT-CONSENT></USER-REC-EXPORT-CONSENT>
          <USER-REC-DELINQ-INDEX></USER-REC-DELINQ-INDEX>
          <USER-REC-DELINQ></USER-REC-DELINQ>
          <USER-REC-DELINQ-N></USER-REC-DELINQ-N>
          <USER-REC-FIELD-INDEX></USER-REC-FIELD-INDEX>
          <USER-REC-FIELD></USER-REC-FIELD>
          <USER-REC-PROFILE-ID></USER-REC-PROFILE-ID>
          <USER-REC-ILL-LIBRARY></USER-REC-ILL-LIBRARY>
          <USER-REC-HOME-LIBRARY></USER-REC-HOME-LIBRARY>
          <USER-REC-ILL-TOTAL-LIMIT></USER-REC-ILL-TOTAL-LIMIT>
          <USER-REC-ILL-ACTIVE-LIMIT></USER-REC-ILL-ACTIVE-LIMIT>
          <USER-REC-SEND-ALL-LETT></USER-REC-SEND-ALL-LETT>
          <USER-REC-PROXY-FOR-ID></USER-REC-PROXY-FOR-ID>
          <USER-REC-PRIMARY-ID></USER-REC-PRIMARY-ID>
          <USER-REC-CON-LNG></USER-REC-CON-LNG>
          <USER-REC-TYPE></USER-REC-TYPE>
          <USER-REC-PLAIN-HTML></USER-REC-PLAIN-HTML>
          <USER-REC-WANT-SMS></USER-REC-WANT-SMS>
          <USER-REC-NOTE-INDEX></USER-REC-NOTE-INDEX>
          <USER-REC-NOTE></USER-REC-NOTE>
          <USER-REC-SALUTATION></USER-REC-SALUTATION>
          <USER-REC-TITLE-REQ-LIMIT></USER-REC-TITLE-REQ-LIMIT>
          <USER-REC-GENDER></USER-REC-GENDER>
          <USER-REC-BIRTHPLACE></USER-REC-BIRTHPLACE>
         </USER-REC>
        <NO-ID-REC>00</NO-ID-REC>    <!-- /* - This field specifies how many login records are about to be specified - affects Z308*/ -->
        <NO-ADDR-REC>00</NO-ADDR-REC>  <!-- /* - This field specifies how many address records are about to be specified - affects Z304*/ -->
        <NO-BOR-REC>00</NO-BOR-REC>  <!--/* - This field specifies how many bor records are about to be specified - affects Z305*/ -->
        <LOGIN-REC>
          <LOGIN-REC-ACTION></LOGIN-REC-ACTION>
          <LOGIN-REC-TYPE></LOGIN-REC-TYPE>
          <LOGIN-REC-LOGIN></LOGIN-REC-LOGIN>
          <LOGIN-REC-VERIFICATION></LOGIN-REC-VERIFICATION>
          <LOGIN-REC-VERIFICATION-TYPE></LOGIN-REC-VERIFICATION-TYPE>
          <LOGIN-REC-STATUS></LOGIN-REC-STATUS>
          <LOGIN-REC-ENCRYPTION></LOGIN-REC-ENCRYPTION>
       </LOGIN-REC>          <!-- /* If <no-id-rec> is bigger than 1, then now we will have more <login-rec> like the number specified. */ -->
     <ADDR-REC>
        <ADDR-REC-ACTION></ADDR-REC-ACTION>
        <ADDR-REC-SEQUENCE></ADDR-REC-SEQUENCE>
        <ADDR-REC-TYPE></ADDR-REC-TYPE>
        <ADDR-REC-ADDR-1></ADDR-REC-ADDR-1>
        <ADDR-REC-ADDR-2></ADDR-REC-ADDR-2>
        <ADDR-REC-ADDR-3></ADDR-REC-ADDR-3>
        <ADDR-REC-ADDR-4></ADDR-REC-ADDR-4>
        <ADDR-REC-ADDR-5></ADDR-REC-ADDR-5>
        <ADDR-REC-ZIP></ADDR-REC-ZIP>
        <ADDR-REC-PHONE></ADDR-REC-PHONE>
        <ADDR-REC-PHONE-2></ADDR-REC-PHONE-2>
        <ADDR-REC-PHONE-3></ADDR-REC-PHONE-3>
        <ADDR-REC-PHONE-4></ADDR-REC-PHONE-4>
        <ADDR-REC-E-MAIL></ADDR-REC-E-MAIL>
        <ADDR-REC-START-DATE></ADDR-REC-START-DATE>
        <ADDR-REC-STOP-DATE></ADDR-REC-STOP-DATE>
        <ADDR-REC-SMS-NUMBER></ADDR-REC-SMS-NUMBER>
      </ADDR-REC>  <!-- /* If <no-addr-rec> is bigger than 1, then now we will have more <addr-rec> like the number specified. */ -->
     <BOR-REC>
            <BOR-REC-ACTION></BOR-REC-ACTION>
            <BOR-REC-SUB-LIBRARY></BOR-REC-SUB-LIBRARY>
            <BOR-REC-TYPE>TT</BOR-REC-TYPE>
            <BOR-REC-STATUS></BOR-REC-STATUS>
            <BOR-REC-EXPIRY-DATE></BOR-REC-EXPIRY-DATE>
     <BOR-REC-REGISTRATION-DATE></BOR-REC-REGISTRATION-DATE>
    </BOR-REC>   <!-- /* If <no-bor-rec> is bigger than 1, then now we will have more <bor-rec> like the number specified. */  -->
    </UPDATE-BOR>

Important:

The three counters within the XML:

<NO-ID-REC>00</NO-ID-REC>
<NO-ADDR-REC>00</NO-ADDR-REC>
<NO-BOR-REC>00</NO-BOR-REC>

Must be in this order within the XML. If <NO-BOR-REC> is not the last of these, an error occurs.

Example of XML input using Option 2:

<p-file-20>
    <patron-record>
        <z303>
            <match-id-type>00</match-id-type>
            <match-id>GILAD72</match-id>
            <record-action>A</record-action>
            <z303-id>GILAD72</z303-id>
            <z303-proxy-for-id>00000036</z303-proxy-for-id>
            <z303-primary-id></z303-primary-id>
            <z303-name-key>testoneGILAD72</z303-name-key>
            <z303-user-type>REG</z303-user-type>
            <z303-user-library></z303-user-library>
            <z303-open-date>20060423</z303-open-date>
            <z303-update-date>20060423</z303-update-date>
            <z303-con-lng>ENG</z303-con-lng>
            <z303-alpha>L</z303-alpha>
            <z303-name>Test,one</z303-name>
            <z303-title></z303-title>
            <z303-delinq-1>00</z303-delinq-1>
            <z303-delinq-n-1></z303-delinq-n-1>
            <z303-delinq-1-update-date>00000000</z303-delinq-1-update-date>
            <z303-delinq-1-cat-name></z303-delinq-1-cat-name>
            <z303-delinq-2>00</z303-delinq-2>
            <z303-delinq-n-2></z303-delinq-n-2>
            <z303-delinq-2-update-date>00000000</z303-delinq-2-update-date>
            <z303-delinq-2-cat-name></z303-delinq-2-cat-name>
            <z303-delinq-3>00</z303-delinq-3>
            <z303-delinq-n-3></z303-delinq-n-3>
            <z303-delinq-3-update-date>00000000</z303-delinq-3-update-date>
            <z303-delinq-3-cat-name></z303-delinq-3-cat-name>
            <z303-budget></z303-budget>
            <z303-profile-id></z303-profile-id>
            <z303-ill-library>ILL_LAW</z303-ill-library>
            <z303-home-library>LAW</z303-home-library>
            <z303-field-1></z303-field-1>
            <z303-field-2></z303-field-2>
            <z303-field-3></z303-field-3>
            <z303-note-1></z303-note-1>
            <z303-note-2></z303-note-2>
            <z303-salutation></z303-salutation>
            <z303-ill-total-limit>0100</z303-ill-total-limit>
            <z303-ill-active-limit>0200</z303-ill-active-limit>
            <z303-dispatch-library></z303-dispatch-library>
            <z303-birth-date>19780605</z303-birth-date>
            <z303-export-consent>Y</z303-export-consent>
            <z303-proxy-id-type>00</z303-proxy-id-type>
            <z303-send-all-letters>Y</z303-send-all-letters>
            <z303-plain-html>H</z303-plain-html>
            <z303-want-sms>N</z303-want-sms>
            <z303-plif-modification></z303-plif-modification>
            <z303-title-req-limit>0000</z303-title-req-limit>
            <z303-gender>M</z303-gender>
            <z303-birthplace>Haifa</z303-birthplace>
        </z303>
        <z304>
            <record-action>A</record-action>
            <z304-id>GILAD72</z304-id>
            <z304-sequence>01</z304-sequence>
            <z304-address-0>OscarAaberg</z304-address-0>
            <z304-address-1>HillAvenue</z304-address-1>
            <z304-address-2>BostonMA90917</z304-address-2>
            <z304-zip>90917</z304-zip>
            <z304-email-address>12add2@hotmail.com</z304-email-address>
            <z304-telephone>212-99334455</z304-telephone>
            <z304-date-from>20020814</z304-date-from>
            <z304-date-to>20060830</z304-date-to>
            <z304-address-type>02</z304-address-type>
            <z304-telephone-2></z304-telephone-2>
            <z304-telephone-3></z304-telephone-3>
            <z304-telephone-4></z304-telephone-4>
            <z304-sms-number></z304-sms-number>
            <z304-update-date>20060423</z304-update-date>
            <z304-cat-name>BATCH</z304-cat-name>
        </z304>
        <z305>
            <record-action>A</record-action>
            <z305-id>GILAD72</z305-id>
            <z305-sub-library>LAW</z305-sub-library>
            <z305-open-date>20060423</z305-open-date>
            <z305-update-date>20060423</z305-update-date>
            <z305-bor-type></z305-bor-type>
            <z305-bor-status>12</z305-bor-status>
            <z305-registration-date>00000000</z305-registration-date>
            <z305-expiry-date>20120101</z305-expiry-date>
            <z305-note></z305-note>
            <z305-loan-permission>Y</z305-loan-permission>
            <z305-photo-permission>N</z305-photo-permission>
            <z305-over-permission>Y</z305-over-permission>
            <z305-multi-hold>N</z305-multi-hold>
            <z305-loan-check>Y</z305-loan-check>
            <z305-hold-permission>Y</z305-hold-permission>
            <z305-renew-permission>Y</z305-renew-permission>
            <z305-rr-permission>Y</z305-rr-permission>
            <z305-ignore-late-return>N</z305-ignore-late-return>
            <z305-last-activity-date>00000000</z305-last-activity-date>
            <z305-photo-charge>C</z305-photo-charge>
            <z305-no-loan>0000</z305-no-loan>
            <z305-no-hold>0000</z305-no-hold>
            <z305-no-photo>0000</z305-no-photo>
            <z305-no-cash>0000</z305-no-cash>
            <z305-cash-limit>0.00</z305-cash-limit>
            <z305-credit-debit></z305-credit-debit>
            <z305-sum>0.00</z305-sum>
            <z305-delinq-1>00</z305-delinq-1>
            <z305-delinq-n-1></z305-delinq-n-1>
            <z305-delinq-1-update-date>00000000</z305-delinq-1-update-date>
            <z305-delinq-1-cat-name></z305-delinq-1-cat-name>
            <z305-delinq-2>00</z305-delinq-2>
            <z305-delinq-n-2></z305-delinq-n-2>
            <z305-delinq-2-update-date>00000000</z305-delinq-2-update-date>
            <z305-delinq-2-cat-name></z305-delinq-2-cat-name>
            <z305-delinq-3>00</z305-delinq-3>
            <z305-delinq-n-3></z305-delinq-n-3>
            <z305-delinq-3-update-date>00000000</z305-delinq-3-update-date>
            <z305-delinq-3-cat-name></z305-delinq-3-cat-name>
            <z305-field-1></z305-field-1>
            <z305-field-2></z305-field-2>
            <z305-field-3></z305-field-3>
            <z305-hold-on-shelf>N</z305-hold-on-shelf>
            <z305-end-block-date>00000000</z305-end-block-date>
            <z305-booking-permission>Y</z305-booking-permission>
            <z305-booking-ignore-hours>N</z305-booking-ignore-hours>
        </z305>
        <z308>
            <record-action>A</record-action>
            <z308-key-type>00</z308-key-type>
            <z308-key-data>GILAD72</z308-key-data>
            <z308-user-library></z308-user-library>
            <z308-verification>GILAD72</z308-verification>
            <z308-verification-type>00</z308-verification-type>
            <z308-id>GILAD72</z308-id>
            <z308-status>AC</z308-status>
            <z308-encryption>N</z308-encryption>
        </z308>
        <z308>
            <record-action>A</record-action>
            <z308-key-type>01</z308-key-type>
            <z308-key-data>PB447</z308-key-data>
            <z308-user-library></z308-user-library>
            <z308-verification>PB447</z308-verification>
            <z308-verification-type>00</z308-verification-type>
            <z308-id>GILAD72</z308-id>
            <z308-status>AC</z308-status>
            <z308-encryption>N</z308-encryption>
        </z308>
    </patron-record>
</p-file-20>

Important Suggestion:

The second XML structure is much more recommended than the first one for three main reasons: 

1. Since the UTIL already makes this kind of XML file, it can be used (after modification) as a template for the XML sent to this X-Service from the point-of-view of the XML tag names.

2. More importantly the second XML structure will provide support for new fields added in the future to any of these tables (Z303, Z304, Z305, Z308), while the first structure will not support such changes.

3. The first XML structure has no flexibility regarding certain fields. Not all fields are supported and only some of the fields in the Oracle tables can be changed (especially in the Z305 table). In the second XML structure, all fields are supported, depending, of course, on relevant restrictions such as violations of primary keys of Oracle tables and so on.

Important Notes:

1. Only one patron can be included in the input XML (relevant for both XML structures).

2. The UTIL does not retrieve the actual ‘Z308-VERIFICATION’ as it is in the database (encrypted for most customers). The ‘Z308-VERIFICATION’ in the output files – both “flat” (sequential) and XML format – is filled with the contents of ‘Z308-KEY-DATA’.

Two Patron Name Fields (Z303 – First Name and Last Name – Aleph 22 and later)

In Aleph 22 and later, customers can use new formatted name structure by setting the “PATRON-NAME-FORMAT” flag in ./alephe/tab/tab100 .

When using this new tab100 flag, patron names are stored in Z303‐NAME and also divided into two fields – Z303-FIRST-NAME and Z303-LAST-NAME fields.Therefore the input XML can contain the fields “<z303-first-name>…</z303-first-name>” and “<z303-last-name> … </z303-last-name>”.

For example:

<z303>
    ...
    <z303-name>Fleming, Ian Lancaster</z303-name>
    ...
    <z303-last-name>Fleming</z303-last-name>
    <z303-first-name>Ian Lancaster</z303-first-name>
</z303>

Output XML Format

The XML output includes the patron ID on which actions have be taken and specifies how many records are to be inserted / updated / deleted per each table. If the service is not successful, the XML includes an error message.

Example:

To perform actions for a new patron in USM50 and to transfer changes to the database in the CGI written, the parameters sent with the POST method should be set to the following values:

  • op should be set to update-bor.
  • library should be set to usm50.
  • update_flag should be set to ‘Y’, since we would like changes to be updated to DB.
  • xml_full_req should be set to an XML built as described above (In “Input Parameters” Section) and include the data to be updated/deleted/inserted to DB.

If the input parameters are correct and the update is successful, the XML output is:

<?xml version = "1.0" encoding = "UTF-8"?>
<update-bor>
<patron-id>GILAD72</patron-id>
<error>Succeeded to WRITE table z303. cur-id GILAD72.</error>
<error>Succeeded to WRITE table z304. cur-id GILAD72.</error>
<error>Succeeded to WRITE table z305. cur-id GILAD72.</error>
<error>Succeeded to WRITE table z305. cur-id GILAD72.</error>
<error>Succeeded to WRITE table z308. cur-id GILAD72.</error>
<error>Succeeded to WRITE table z308. cur-id GILAD72.</error>
<table>z303-user record</table>
<num-of-new-rec-inserted>01</num-of-new-rec-inserted>
<num-of-updated-rec>00</num-of-updated-rec>
<num-of-deleted-rec>00</num-of-deleted-rec>
<table>z308-login record</table>
<num-of-new-rec-inserted>02</num-of-new-rec-inserted>
<num-of-updated-rec>00</num-of-updated-rec>
<num-of-deleted-rec>00</num-of-deleted-rec>
<table>z304-address record</table>
<num-of-new-rec-inserted>01</num-of-new-rec-inserted>
<num-of-updated-rec>00</num-of-updated-rec>
<num-of-deleted-rec>00</num-of-deleted-rec>
<table>z305-bor record</table>
<num-of-new-rec-inserted>02</num-of-new-rec-inserted>
<num-of-updated-rec>00</num-of-updated-rec>
<num-of-deleted-rec>00</num-of-deleted-rec>
<session-id>QT4PJX1VV2855TRT74AG5TRTX329IULN7K48RM6HNSCIJEJN8Y</session-id>
</update-bor>

Possible Error Codes

1. If this X-Service is activated without a library having been entered, the following error message appears in the XML output:

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

2. If an XML file has not been provided:

< error> xml must be provided to update patron</error>

3. If, after filling the PLIF record based on the input XML, the length of the record is still zero:

< error> Can’t work on empty xml</error>

4. If one of the fields specifying how many records there are (no-id-rec, no-addr-rec, no-bor-rec) is non-numeric:

< error> Number of records specified in the input xml is not numeric</error>

5. If an action different to X, U, I , D, A has been inserted in the XML (for example, P):

< error> Unsupported action: P</error>

6. If the action requested for a record is Update / Delete, and no such record exists for the given Patron (for example, Z303 for patron 123):

< error> Cannot update / delete z303. No match found for ID: 123</error>

7. If the action requested for a record is Insert, and such a record already exists:

< error> Cannot Insert z303. Match found for ID: 123</error>

8. If a patron is requested to be deleted who still has outstanding cash transactions:

< error> Unable to delete due to cash</error>

9. If a patron is requested to be deleted who still has active loans:

< error> Unable to delete Z303 due to active loans</error>

10. If a new patron is being inserted and the system failed to generate a new bor_id:

< error> Failed to generate new User ID. Check tab100 or z52.last-bor-id</error>

11. If a login record is requested to be deleted / updated (Z308) and no such record exists:

< error> Cannot update / delete Z308. Login doesn’t exist.</error>

12. If a login record is requested to be deleted / updated (Z308) but the given Z308 record (in the XML) belongs to another user:

< error> Cannot update/delete Z308 record. Login record belongs to another user.</error>

13. If a login record is requested to be inserted and such a record already exists:

< error> Cannot insert Z308. Login record already exist</error>

14. If a Login record is requested to be inserted and the key data is empty (meaning, it is requested to be generated) and the key type is not 01 (barcode):

< error> System can not generate login for login-type other than 01</error>

15. If a login record is requested to be inserted and the key data is empty, and key type is 01 and there is a matching Z303 record:

< error> Cannot assign new barcode for an existing patron</error>

16. If a borrower record (Z305) is requested to be deleted and there are active hold requests for the patron:

< error> Unable to delete due to active hold requests</error>

17. If a failure occurred in generating a barcode for Z308:

< error> System could not generate “dummy” barcode. Check tab100 or z52.last-bor-id-1</error>

18. If a user record (Z303) is requested to be deleted and one of the other records (Z308, Z304, Z305) is requested to be Inserted / Updated:

< error> Cannot update / insert record when user record is being deleted</error>

19. If a user record (Z303) is requested to be inserted and one of the other records (Z308, Z304, Z305) is requested to be updated:

< error> Cannot update record when new user is being inserted</error>

20. If a barcode record (z308, type=01) is requested to be deleted and the user record (Z303) is not requested to be deleted:

< error> Cannot delete barcode from existing/new user</error>

21. If more than one barcode record (Z308, type=01) is requested to be inserted:

< error> Cannot insert more than one barcode</error>

22. If a user record is requested to be updated, and there is no permission for this action:

< error> TAB100-USER-PERMISSION doesn’t allow record’s updating</error>

23. If an address record (Z304) is requested to be updated, and there is no permission for this action:

< error> TAB100-USER-ADDR-PERMISSION doesn’t allow record’s updating</error>