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
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)
2. FILTER_SOURCE_AUTHORIZATION
- REQUESTER_IP – X(12).
- 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
- category_name – name of the category
- 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.