retrieve_category

NAVIGATE CONTENT
Ex Libris Developer Network MetaLib Documentation MetaLib APIs X-Services retrieve_category

General Purpose

This X-Service enables retrieval of a list of categories, with or without their subcategories, for a specific institution or portal.

The retrieved category list is sorted according to the order defined in the Category Administration module of the MetaLib Management Interface.

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
  • PDS authentication – for remote authentication of the user and to obtain a pds handle
  • retrieve_category

Input Parameters

Mandatory
1. SESSION_ID – X (50).
2. PORTAL_ ASSOCIATION
  • Option 1
    • REQUESTER_IP – X(12)
  • Option 2
    • SOURCE_ID – X(40)
    • INSTITUTE – X(30)
    • VERIFICATION – X(20)
  • Option 3
    • BOR_ID – X(12)
    • VERIFICATION – X(20)
  • Option 4
    • INSTITUTE – X(30)
    • PORTAL – X(30)
    • LANGUAGE – X(3)
  • Option 5
    • PDS_HANDLE – X(50)
Optional
1. RETRIEVE_SUBCATEGORY – X(1)
2. FILTER_SOURCE_AUTHORIZATION
  • REQUESTER_IP – X(12).
Explanation of the mandatory and optional parameters:
  • session_id – unique identifier returned by the login service.
  • portal_association – one of the following:
    • requester_ip – IP of the machine to which the requester is connected
    • source_id – source_ID of the user requesting categories
      • institute – requested user’s institution
      • verification – requested user’s password
    • bor_id – user_ID of the user requesting categories
      • verification – requested user’s password
    • institute – requested user’s institution
      • portal – requested user’s portal
      • language – requested category language
    • pds_handle – unique token returned by the remote authentication system
  • retrieve_subcategories – with or without subcategories for each category. Default value is Y, with subcategories included.
  • requester_ip – IP of the machine to which the requester is connected.

Input XML Format

Examples:

Guest user:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <retrieve_categories_request>
    <session_id>32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
      <portal_association>
        <requester_ip>10.1.235.47</requester_ip>
      </portal_association>
  </retrieve_categories_request>
</x_server_request>

Logged-in user, local authentication:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <retrieve_categories_request>
    <session_id>32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
      <portal_association>
        <source_id>METALIB</source_id>
        <verification>******</verification>
        <institute>metalib</institute>
        </portal_association>
      <retrieve_subcategories>N</retrieve_subcategories>
  </retrieve_categories_request>
</x_server_request>

Logged-in user, remote authentication:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <retrieve_categories_request>
    <session_id>32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
      <portal_association>
        <pds_handle>2210200612344771422200610344712</pds_handle>
      </portal_association>
      <retrieve_subcategories>N</retrieve_subcategories>
  </retrieve_categories_request>
</x_server_request>

Input URL Syntax

The input parameters must be embedded within the URL syntax:

MetalibPath:port/X?op=retrieve_categories_request&requester_ip=requester_ip&session_id=session id

Or

MetalibPath:port/X?op=retrieve_categories_request&source_id=name&verification=****&institute=institution&session_id=session_id

Example URL Syntax

Guest user:

http://ram47:8334/X?op=retrieve_categories_request&requester_ip=10.1.235.47&session_id=RA4M5D4M4J9YNYI2PX8YDKIN4ILJ978FB1LAY1TLTJG4V1VF5F

Logged-in user, remote authentication:

http://10.1.235.47:8334/X?op=source_locate_request&locate_command=WFL=000000179&source_full_info_flag=N&session_id=L9UUHVLPA7LUTEQYM7YJX8GLH6FDR2V77GRG6TIQ21UIXQEXH2

Output XML Format

Information about each category:
  • category_name – name of the category
Information about each subcategory:
  • sequence – unique key in MetaLib, used as input to the retrieve_resources_by_category service
  • subcategory_name – name of the subcategory
  • no_bases – number of resources defined in the subcategory
  • no_of_authorized_bases – number of resources defined in the category/subcategory limited to authorized users only

Examples:

Category list:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_response metalib_version="4.00 (20)">
  <retrieve_categories_response>
    <category_info>
      <sequence>000000149</sequence>
      <category_name>Arts</category_name>
      <no_bases>000000006</no_bases>
      <no_authorized_bases>000000005</no_authorized_bases>
    </category_info>
    <category_info>
      <sequence>000000149</sequence>
      <category_name>Education</category_name>
      <no_bases>000000005</no_bases>
      <no_authorized_bases>000000005</no_authorized_bases>
    </category_info>
    <session_id   new_session="N">32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
  </retrieve_categories_response>
</x_server_response>

Including subcategories:

<<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_response metalib_version="4.00 (20)">
  <retrieve_categories_response>
    <category_info>
      <category_name>Arts</category_name>
      <subcategory_info>
        <category_sequence>000000141</category_sequence>
        <subcategory_name>Architecture</subcategory_name>
        <no_bases>000000002</no_bases>
        <no_authorized_bases>000000002</no_authorized_bases>
      </subcategory_info>
    </category_info>
    <category_info>
      <category_name>Arts</category_name>
      <subcategory_info>
        <sequence>000000142</sequence>
        <subcategory_name>Film</subcategory_name>
        <no_bases>000000004</no_bases>
        <no_authorized_bases>000000003</no_authorized_bases>
      </subcategory_info>
    </category_info>
    <category_info>
      <category_name>Engineering</category_name>
      <subcategory_info>
        <sequence>000000149</sequence>
        <subcategory_name>Aerospace</subcategory_name>
        <no_bases>000000005</no_bases>
        <no_authorized_bases>000000005</no_authorized_bases>
      </subcategory_info>
    </category_info>
    <session_id new_session="N"> 32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D
</session_id>
  </retrieve_categories_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. If the institution cannot be found:

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

5. If the portal name is missing:

<error_code>6017</error_code>
<error_text>Portal ID is mandatory</error_text>

6. If the portal association has no categories:

<error_code>6024</error_code>
<error_text>No categories were found under portal</error_text>

7. If the password entered does not match the verification:

<error_code>0130</error_code>
<error_text>Your password pincode is not equal to the verification pincode</error_text>

8.If the user has expired:

<error_code>6020</error_code>
<error_text>User expired</error_text>

9.If there is no default user for the requested IP:

<error_code>6021</error_code>
<error_text>Could not find default user for ip 'requested_ip'</error_text>

10. If the format of the pds_handle is incorrect:

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

11. If the pds_handle is not valid:

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

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