retrieve_eShelf_folders

General Purpose

This X-Service is used to retrieve a list of eShelf folders defined for a logged-in user and retrieve information about each eShelf folder.

Flow

  • login – Called once by the calling application with valid /X user name and password. The session-id retrieved should be passed to all other API calls
  • Authentication (optional, either local or remote)
    • bor_auth – for local authentication of the user and to retrieve a valid borrower’s ID or bor_info
    • PDS authentication – for remote authentication of the user and to obtain a pds handle
  • bor_info (optional)
  • retrieve_category – optional, retrieves Categories ID, used in conjunction with WFL (see below)
  • retrieve_eshelf_folders

Input Parameters

Mandatory
1. SESSION_ID – X(50)
2. USER ID OPTIONS:
  • Option 1
    • SOURCE_ID – X(40)
    • INSTITUTE – X(30)
    • VERIFICATION – X(20)
  • Option 2
    • BOR_ID – X(12)
    • VERIFICATION – X(20)
  • Option 3
    • PDS_HANDLE – X(50)
Explanation of the mandatory parameters:
  • session_id – the unique identifier returned by the login request
  • user id – one of the following:
    • source_id – user login name
      institute – institution to which the user is affiliated
      verification – user password
    • bor_id – unique user ID
      verification – user password
    • pds-handle – user’s unique token returned by the remote authentication system

Input XML Format

Logged-in user, local authentication:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <retrieve_eshelf_folders_request>
    <session_id>32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
    <source_id>central</source_id>
    <verification>central44</verification>
    <institute>CENTRAL</institute>
  </retrieve_eshelf_folders_request>
</x_server_request>

Logged-in user, remote authentication:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <retrieve_eshelf_folders_request>
    <session_id>32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
    <pds_handle>2210200612344771422200610344712</pds_handle>
</retrieve_eshelf_folders_request>
</x_server_request>

Input URL Syntax

In order to retrieve eShelf folders, the input parameters must be embedded within the appropriate URL syntax:

MetalibPath:port/X?op=retrieve_eshelf_folders_request&bor_id=patron num&verification=***&session_id=session_id

Example URL Syntax

Logged-in user, local authentication:

http://ram47:8334/X?op=retrieve_eshelf_folders_request&source_id=David&verification=David123&institute=metalib&session_id=L9UUHVLPA7LUTEQYM7YJX8GLH6FDR2V77GRG6TIQ21UIXQEXH2

Logged-in user, remote authentication:

http://ram47:8334/X?op=retrieve_eshelf_folders_request&pds_handle=2210200612344771422200610344712&session_id=L9UUHVLPA7LUTEQYM7YJX8GLH6FDR2V77GRG6TIQ21UIXQEXH2

Output XML Format

Information about each eShelf folder:
  • Folder name – Name of the eShelf folder.
  • No documents – Number of results, defined in the eShelf folder.
Example:

<x_server_response metalib_version="4.00 (20)">
  <ret_eshelf_folders_response>
  <folder_info>
    <set_name>Basket</set_name>
    <no_bases>000000007</no_bases>
  </folder_info>
  <folder_info>
    <set_name>Computer Science</set_name>
    <no_bases>000000004</no_bases>
  </folder_info>
  <session_id new_session="n">32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
  </ret_eshelf_folders_response>
</x_server_response>

Possible Error Codes

1. If the session_id, provided as an input parameter, is not valid, the following error message appears in the XML output:

<error_code>0151</error_code>
<error_text> You are not authorized to use this function </error_text>

This can be caused by not using the session_id returned from the login X-Service.

2. If this X-Service was activated after the session had timed out:

<error_code>2050</error_code>
<error_text>session timeout</error_text>

3. If the user-id cannot be found:

<error_code>6001</error_code>
<error_text>User does not exist</error_text>

4. User ID is mandatory:

<error_code>6004</error_code>
<error_text>User Id is mandatory</error_text>

5. If the requested user has no eShelf folders:

<error_code>6006</error_code>
<error_text>User has no eShelf folders</error_text>

6. If the institution does not exist:

<error_code>6025</error_code>
<error_text>Institution does not exist</error_text>

7. If the number of eShelf folders is higher than the limit:

<error_code>6013</error_code>
<error_text>The number of eshelf folders is higher than the eShelf limit</error_text>

8. If the PDS handle is invalid, the user will be treated as guest:

<error_code>6061</error_code>
<error_text>PDS handle is invalid</error_text>

9. If the format of the pds_handle is incorrect:

<error_code>6062</error_code>
<error_text>Invalid pds_handle format</error_text>

10. If the pds_handle is not valid:

<error_code>6061</error_code>
<error_text>Invalid pds_handle</error_text>

Note:
If 9 or 10 above are returned, the request will not terminate in error. The onus is on the calling application as to how to proceed.

Notes

Output XML Formal example is wrong (or valid only for a very old MetaLib version).  The folder_info elements are not set_name and no_bases, instead they are folder_name and no_documents.  Example:

<?xml version="1.0" encoding="UTF-8"?>
<x_server_response metalib_version="4.4.3 (731)">
  <ret_eshelf_folders_response>
    <folder_info>
      <folder_name>Basket</folder_name>
      <no_documents>000000019</no_documents>
    </folder_info>
    <folder_info>
      <folder_name>Temporary folder</folder_name>
      <no_documents>000000000</no_documents>
    </folder_info>
    <session_id new_session="N">UR09VKAUX9EA38CGLYX878R59X1LDJ55XHJ3AZQIEV7RT8YIY8</session_id>
  </ret_eshelf_folders_response>
</x_server_response>