retrieve_resources_by_category

Ex Libris Developer Network MetaLib Documentation MetaLib APIs X-Services retrieve_resources_by_category

General Purpose

This X-Service enables the retrieval of a list of resources included in a specific category/subcategory 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
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 – retrieves Categories ID
retrieve_resources_by_categories

Input Parameters

Mandatory

1. SESSION_ID – X(50)

2. CATEGORY_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)
REQUESTER_IP – X(12)
INSTITUTE – X(30)
INSTITUTE – X(30)
USER_GROUP – X(30)
REQUESTER_IP – X(12)
PDS_HANDLE – X(50)
PDS_HANDLE – X(50)
Option 3
Option 4
Option 5
Option 6
Option 7

3. CALLING_APPLICATION – X(100)

4. PRIMO_DETAILS – X(1)

Explanation of the mandatory and optional parameters:

session_id: The session ID is the unique identifier of the login.
category_id – The requested category. The category’s ID is provided by the()retrieve_categories() (master_sequence) service.
source_full_info_flag – Resource information retrieval indicator. Valid Values:
- N – Default – Retrieve partial information for each resource in the category/subcategory.
- Y – Retrieve full information for each resource in the category/subcategory.
filter_source_authorization – wrapper of three input parameters (requester_ip, institution 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.
user_group – User’s affiliation group, in case resource filtering is needed.
pds_handle – User’s unique token returned by the remote authentication system
calling_application – Name of the calling application. If not specified, default name is “X-SERVER”, and it will be stored in exact case.
primo_details – Additional information indicator. Valid Values:
N – Default – 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>
quesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesquesques>
    <session_id>32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
    <category_id>000000001</category_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_category_request>
</x_server_request>

Input URL Syntax

In order to retrieve a list of resources contained in a category(ies), the input parameters must be embedded within the appropriate URL syntax:

MetalibPath:port/X?op=retrieve_resources_by_category_request&category_id=category_id&requester_ip=requester_ip&institute=institution&user_group=user_group&session_id=session_id

Example URL Syntax

Example:

http://ram47:8334/X?op=retrieve_resources_by_category_request&category_id=000000001&filter_source_authorization=&requester_ip=10.1.235.47&institute=METALIB&session_id=L9UUHVLPA7LUTEQYM7YJX8GLH6FDR2V77GRG6TIQ21UIXQEXH2

Output XML Format

Explanation of the output values:

source_internal_number – Unique system resource 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.
ird_permission – Resource’s authorization status.
ip_filter_from/ip_filter_to – Resource’s IP range indicators.

Examples:

source_full_info_flag is N

If the source_full_info_flag is N, partial information for each resource in the category/subcategory is returned:

<x_server_response metalib_version="4.00 (20)">
  ponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponspons>
    <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_category_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 in the category/subcategory is returned:

<x_server_response> metalib_version="4.00 (20)>
  ponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponspons>
    <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 IRD 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>
  ponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponsponspons>
<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 category is not found:

<error_code>6014</error_code>
<error_text>Category does not exist</error_text>

4. If the category ID is missing:

<error_code>6015</error_code>
<error_text>Category ID is mandatory</error_text>

5. If the category is not found:

<error_code>6022</error_code>
<error_text>All the resources are not authorized</error_text>

6. If the category ID is missing:

<error_code>6023</error_code>
<error_text>Category has no resources</error_text>

7. If the institution does not exist:

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

8. If the format of the pds_handle is incorrect:

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

9. If the pds_handle is not valid:

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

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