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.