retrieve_quick_sets

General Purpose

This X-Service retrieves a list of QuickSets per user profile (institution / portal). QuickSets are identified by the user profile:

Guest user profile:
The user inherits the default user’s sets, according to the requester_ip. If the default user does not have any sets, the QuickSets are taken from the <institution></portal><language>/user. Authorization is based on requester IP, default user’s institution and default user’s group.Logged-in user profile:
Retrieves the QuickSets associated with one of the following default users, listed hierarchically:

<portal>-<language>-<group>

<portal>-<language>-in

<portal>-<language>

<Institute>-<group>

<Institute>-in

<Institute>

Authorization is based on requester-ip, user’s institution and user’s group.

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_quick_sets

Input Parameters

Mandatory

  1. SESSION_ID – X(50).
  2. QUICK_SETS_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
      • PDS_HANDLE – X(50)

Optional

  1. FILTER_IRD_AUTHORIZATION
    • REQUESTER-IP – X(12).

Explanation of the mandatory and optional parameters:

  • session_id – The session ID is the unique identifier of the login.
  • quick_set_association – One of the following:
    1. requester_ip – IP of the machine to which the requester is connected.
    2. Source_id – source_ID of user requesting QuickSets.
      Institute – User’s institution.
      Verification – User’s password
    3. Bor_Id – User_ID of the user requesting QuickSets.
      Verification – User’s password
    4. pds_handle – User’s unique token returned by the remote authentication system
  • Filter_ird_authorizationRequester_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_quick_sets_request>
    <session_id>32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
    <quick_sets_association>
      <requester_ip>10.1.235.47</requester_ip>
    </quick_sets_association>
  </retrieve_quick_sets_request>
</x_server_request>

Logged-in user:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <retrieve_quick_sets_request>
    <session_id>32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
    <quick_sets_association>
      <source_id>metalib</source_id>
      <verification>metalib</verification>
      <institute>METALIB</institute>
    </quick_sets_association>
  </retrieve_quick_sets_request>
</x_server_request>

Input URL Syntax

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

MetalibPath:port/X?op=retrieve_quick_sets_request&requester_ip= requester_ip&session_id=session_id

Or

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

Example URL Syntax

Example 1:

http://ram47:8334/X?op=retrieve_quick_sets_request&filter_ird_authorization=Y&requester_ip=10.1.235.47&session_id=L9UUHVLPA7LUTEQYM7YJX8GLH6FDR2V77GRG6TIQ21UIXQEXH2

Example 2:

http://ram47:8334/X?op=retrieve_quick_sets_request&source_id=metalib&verification=metalib&institute=METALIB&session_id

Output XML Format

Information about each QuickSet:

  • Set sequence – Unique key in MetaLib. Use this key for searching the QuickSet by the search_quick_sets X-Service.
  • Set name – Name of the QuickSet.
  • Set description – Description of the QuickSet.
  • No bases – Number of resources, defined in the QuickSet.
  • No of authorized bases – Number of resources, defined in the QuickSet, that are available only to authorized users.
  • Locked set – Defines whether the number of restricted resources is above or below threshold (www_metalib.conf/www_quick_threshold) (For authorization mode only, that is, filter_ird_authorization=Y).
    <?xml version = "1.0" encoding = "UTF-8"?>
    <x_server_response metalib_version="4.00 (20)">
      <retrieve_quick_sets_response>
      <set_info>
        <set_sequence>000000001</set_sequence>
        <set_name>Medical Information</set_name>
        <set_description></set_description>
        <no_bases>000000007</no_bases>
        <no_authorized_bases>000000005</no_authorized_bases>
        <locked_set>N</locked_set>
      </set_info>
      <set_info>
        <set_sequence>000000002</set_sequence>
        <set_name>National Libraries</set_name>
        <set_description></set_description>
        <no_bases>000000005</no_bases>
        <no authorized_bases>000000005</no_authorized_bases>
        <locked_set>N</locked_set>
      </set_info>
      <set_info>
        <set_sequence>000000003</set_sequence>
        <set_name>Science for Everyone</set_name>
        <set_description></set_description>
        <no_bases>000000003</no_bases>
        <no_ authorized_bases>000000005</no_authorized_bases>
        <locked_set>N</locked_set>
      </set_info>
      <set_info>
        <set_sequence>000000004</set_sequence>
        <set_name>US Gov't Information</set_name>
        <set_description></set_description>
        <no_bases>000000005</no_bases>
        <no_authorized_bases>000000005</no_authorized_bases>
        <locked_set>Y</locked_set>
      </set_info>
      <session_id new_session="n">32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
      </retrieve_quick_sets_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 there are no QuickSets associated with the request:

    <error_code>6002</error_code>
    <error_text>Quick Set Association is mandatory</error_text>

    5. If the requested user has no sets:

    <error_code>6003</error_code>
    <error_text>QuickSet Association has no QuickSets</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 format of the pds_handle is incorrect:

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

    8. If the pds_handle is not valid:

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

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

    Notes

    Up to MetaLib version 4.3.4 (657):

    This service is not up to date with the new Quickset management system which supports multilingual translations. Considering the portal feature as well, requester_ip alone is not enough to determine which quicksets should be retrieved. Therefore option 2 must be used for parameters:

    • SOURCE_ID – X(40)
    • INSTITUTE – X(30)
    • VERIFICATION – X(20)

    One problem you might encounter is that the default users (and their passwords for verification) are no longer directly accessible from the user list in the management interface. You have to get their bor_id using bor_info_request and then use a link hostname/M/SESSION/user-update?user_institute=INSTITUTE&user_id=BOR_ID to edit the user record.

    It would be quite convenient to have an option such as:

    • INSTITUTE
    • PORTAL
    • LANGUAGE
    • and a flag for Guest sets?