retrieve_resources_by_quick_sets

General Purpose

This X-Service allows you to retrieve a list of resources included in a specific QuickSet defined by a MetaLib institution/portal.

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
  • bor_auth (optional) – authenticates the user and retrieves the user’s valid borrower’s ID.
  • retrieve_quick_sets – retrieves the QuickSet’s ID.
  • retrieve_resources_by_quick_sets

Input Parameters

Mandatory
1. SESSION_ID – X(50)
2. QUICK_SETS_ID – X(9)

Optional
1. SOURCE_FULL_INFO_FLAG – X(1)
2. FILTER_SOURCE_AUTHORIZATION

  • Option 1
    • REQUESTER_IP – X(12)
    • INSTITUTE – X(30)
    • USER_GROUP – X(30)
  • Option 2
    • REQUESTER_IP – X(12)
    • INSTITUTE – X(30)
  • Option 3
    • REQUESTER_IP – X(12)
  • Option 4
    • INSTITUTE – X(30)
  • Option 5
    • INSTITUTE – X(30)
    • USER_GROUP – X(30)
  • Option 6
    • REQUESTER_IP – X(12)
    • PDS_HANDLE – X(50)
  • Option 7
    • PDS_HANDLE – X(50)

3. PRIMO_DETAILS – X(1)

Explanation of the mandatory and optional parameters:

  • session_id – The session ID is the unique identifier of the login.
  • quick_sets_id – The requested QuickSet. The QuickSet’s ID is provided by the retrieve_quick_sets service.
    Note: There are two options for retrieving sets

    • my_sets_id 000000001 – Retrieve resources from a single set
    • my_sets_id 000000001, 000000010, 000000005 – Retrieve resources from multiple sets
  • source_full_info_flag – Resource information retrieval indicator. Valid values are:
    • N – Retrieves partial information for each resource in the QuickSet.
    • Y – Retrieves full information for each resource in the QuickSet.
  • filter_source_authorization – wrapper of three input parameters (requester_ip, institute and user group) used for filtering of resources. If filter_source_authorization is not provided, the requester_ip, institute and user_group are ignored.
  • requester_ip – User’s IP address, in case resource filtering is needed
  • institute – User’s institution, in case resource filtering is needed.
  • group – User’s affiliation group, in case resource filtering is needed.
  • pds_handle – User’s unique token returned by the remote authentication system
  • primo_details \ – Additional information indicator. Valid values are:
    • N – Retrieves authorized resources only (according to the defined filter).
    • Y – Retrieves all resources with authorization data and the resource’s IP range (if defined)

Input XML Format

Example:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <retrieve_resources_by_quick_set_request>
    <session_id>32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
    <quick_sets_id>000000001</quick_sets_id>
    <filter_source_authorization>
      <requester_ip>10.1.247.35</requester_ip>
      <Institute>METALIB</institute>
      <user_group></user_group>
    </filter_source_authorization>
  </retrieve_resources_by_quick_set_request>
</x_server_request>

Input URL Syntax

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

MetalibPath:port/X?op=retrieve_resources_by_quick_set_request&quick_sets_id= id&requester_ip=ip&institute=institution&user_group=user_group&session_id=session_id

Example URL Syntax

http://ram47:8334/X?op=retrieve_resources_by_quick_set_request&quick_sets_id=000000001&requester_ip=10.1.235.47&institute=METALIB&session_id=L9UUHVLPA7LUTEQYM7YJX8GLH6FDR2V77GRG6TIQ21UIXQEXH2

Output XML Format

Explanation of the output values:

  • source_internal_number – Unique IRD (Resource) system number.
  • source_001 – Resource number. Unique number with the institution’s prefix.
  • source_name – Resource full name.
  • source_short_name – Resource display name.
  • source_searchable_flag – Link to resources or searchable resources.

Examples:

source_full_info_flag is N

If source_full_info_flag is N, partial information for each resource in the Quick Set is returned:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_response metalib_version="4.00 (20)">
  <retrieve_resource_by_quick_set_response>
    <source_info>
      <source_internal_number>000000389</source_internal_number>
      <source_001>CKB02166</source_001>
      <source_name>Ingenta Select (Ingenta)</source_name>
      <source_short_name>Ingenta Select (Ingenta)</source_short_name>
      <source_searchable_flag>Y</source_searchable_flag>
    </source_info>
    <source_info>
      <source_internal_number>000000443</source_internal_number>
      <source_001>CKB02241</source_001>
      <source_name>Journal of Medical Systems (Ingenta Select)</source_name>
      <source_short_name>Journal of Medical Systems (Ingenta Select)</source_short_name>
      <source_searchable_flag>Y</source_searchable_flag>
      </source_info>
      <session_id new_session="N">32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
  </retrieve_resource_by_quick_set_response>
</x_server_response>

source_full_info_flag is Y

If source_full_info_flag is Y, the full MARC format information for each resource is included in the QuickSet:

Example:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_response> metalib_version="4.00 (20)">
  <retrieve_resource_by_quick_set_response>
    <source_full_info>
      <source_info>
        <source_internal_number>000000389</source_internal_number>
        <source_001>CKB02166</source_001>
        <source_name>Ingenta Select (Ingenta)</source_name>
        <source_short_name>Ingenta Select (Ingenta)</source_short_name>
        <source_searchable_flag>Y</source_searchable_flag>
      </source_info>
      <record xmlns="http://www.loc.gov/MARC21/slim/"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.loc.gov/MARC21/slim
      >http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd"
        <controlfield tag="001">CKB02166</controlfield>
        <datafield tag="245" ind1="1" ind2=" ">
          <subfield code="a">Ingenta Select (Ingenta)</subfield>
        </datafield>
        <datafield tag="246" ind1="1" ind2=" ">
          <subfield code="a">was Catchword</subfield>
        </datafield>
        <datafield tag="210" ind1=" " ind2=" ">
          <subfield code="a">Ingenta Select (Ingenta)</subfield>
        </datafield>
        <datafield tag="520" ind1=" " ind2=" ">
          <subfield code="a">Providing access to thousands of online journals from leading
          scholarly, academic and business publishers, the Ingenta Select service provides fast and
          reliable access from a global network of servers to users' desktops around the world.
          ## ##Ingenta Select provides access to more than 5,000 electronic
          publications from over 190 publisher clients and bring together an extensive range of
          services for the librarian and end-user alike</subfield>
        </datafield>
        <datafield tag="594" ind1=" " ind2=" ">
          <subfield code="a">FREE</subfield>
        </datafield>
        <datafield tag="592" ind1=" " ind2=" ">
          <subfield code="a">There are no ISBNs in this resource.
          ## ##Year searches are not supported.</subfield>
        </datafield>
        <datafield tag="595" ind1=" " ind2=" ">
          <subfield code="a">There are no ISBNs in this resource.
          ## ##Year searches are not supported.</subfield>
        </datafield>
        <datafield tag="593" ind1=" " ind2=" ">
          <subfield code="a">This resource uses WEBConfig. The Hostname:Port
          is http://www.ingentaselect.com/rpsv//cgi-bin/jsearch?mode=search&form=expert
          &search1=&action~searchdb=Search& ## ##
          The CKB also includes an example of an SOURCE that searches one journal in
          Ingenta Select. See Journal of Medical Systems. The parameter LimitToTitle=0148-5598
          & is added to the Hostname:Port to limit searches just to that journal.</subfield>
        </datafield>
        <datafield tag="110" ind1="2" ind2=" ">
          <subfield code="a">Ingenta</subfield>
        </datafield>
        <datafield tag="260" ind1=" " ind2=" ">
          <subfield code="b">Ingenta</subfield>
        </datafield>
        <datafield tag="TAR" ind1=" " ind2=" ">
          <subfield code="a">INGENTA_SELECT</subfield>
          <subfield code="f">Y</subfield>
        </datafield>
        <datafield tag="ZHS" ind1=" " ind2=" ">
          <subfield code="a">http://www.ingentaselect.com/rpsv//cgi-bin/jsearch?mode=search
          &form=expert&search1=&action~searchdb=Search&</subfield>
        </datafield>
        <datafield tag="AF1" ind1=" " ind2=" ">
          <subfield code="a">METALIB</subfield>
        </datafield>
        <datafield tag="AF3" ind1=" " ind2=" ">
          <subfield code="a">GUEST</subfield>
        </datafield>
        <datafield tag="STA" ind1=" " ind2=" ">
          <subfield code="a">ACTIVE</subfield>
        </datafield>
        <datafield tag="FIL" ind1=" " ind2=" ">
          <subfield code="a">General Interest</subfield>
        </datafield>
        <datafield tag="LUP" ind1=" " ind2=" ">
          <subfield code="a">20040709</subfield>
        </datafield>
        <controlfield tag="FMT">DD</controlfield>
        <datafield tag="856" ind1="4" ind2="2">
          <subfield code="u"></subfield>
        </datafield>
        <datafield tag="856" ind1="4" ind2="1">
          <subfield code="u"></subfield>
        </datafield>
        <datafield tag="655" ind1=" " ind2=" ">
          <subfield code="a">Index</subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2=" ">
          <subfield code="c">20040518</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">1744</subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2=" ">
          <subfield code="a">chrisr</subfield>
          <subfield code="b">00</subfield>
          <subfield code="c">20040630</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">1735</subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2=" ">
          <subfield code="a">chrisr</subfield>
          <subfield code="b">00</subfield>
          <subfield code="c">20040708</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">1119</subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2=" ">
          <subfield code="c">20040723</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">0902</subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2=" ">
          <subfield code="c">20040723</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">0905</subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2=" ">
          <subfield code="c">20040723</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">1639</subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2=" ">
          <subfield code="c">20040805</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">1348</subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2=" ">
          <subfield code="c">20041130</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">1646</subfield>
        </datafield>
      </record>
    </source_full_info>
    <session_id new_session="N">3B7F9EQE259KNK1YUK462VCCG4455T4BUPUC5B9LVQS9XD16U6</session_id>
  </x_server_response>
</retrieve_resource_by_quick_set_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 quick_set_id does not exist:

<error_code>3101</error_code>
<error_text>Set '$1' does not exist</error_text>

4. If the quick_set_id parameter is missing:

<error_code>3102</error_code>
<error_text>Set ID is mandatory</error_text>

5. If an invalid quick_set_id is specified:

<error_code>3104</error_code>
<error_text>Set Id input parameter is not correct</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

Ere Maijala

I think there’s an ‘s’ missing in the tag name in the example XML returned. The tag should be retrieve_resources_by_quick_set_response (plural ‘resources’). Probably the same with the full info example.

Erik Altmann

I believe it’s:

<retrieve_resources_by_quick_set_response>
 <set_info>
   <source_info> or <source_full_info><source_info>...
   <source_info> or <source_full_info><source_info>...
 </set_info>
</retrieve_resources_by_quick_set_response>

rather than:

<retrieve_resources_by_quick_set_response>
 <source_info> or <source_full_info><source_info>...

MetaLib 4.2.2 and 4.3