retrieve_cluster_facet
General Purpose
This X-Service enables the retrieval of cluster and facet data for the search results. The cluster engine (Vivisimo) provides the cluster and facet data.
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
- Search – performs a search request on a single resource or on a group of resources, using one of the services:
- find
- search_my_sets
- search_quick_sets
- find_group_info (optional) – returns the status of the search process
- merge_sort – merges several result sets into one result set from different resources, and returns the set number
- retrieve_cluster_facet
- present – the calling application should use the present service with specific document numbers in the doc_number field (comma delimited up to 100 doc numbers) in order to display the chosen facet records.
Input Parameters
Mandatory
1. SESSION_ID – X(50)
2. SET_NUMBER – X(6)
Optional
1. TYPE – X(20)
2. CALLING_APPLICATION – X(100)
3. INSTITUTION – X(30)
Explanation of the mandatory and optional parameters:
- session_id: The session ID is the unique identifier of the login.
- set_number – The merged set ID is returned by the merge_sort service. Limited to a single set ID.
- type
If not specified, default is all.- all – both cluster and facet results: Topic Cluster, Facet Year, Facet Author, Facet Journal, Facet Database, Facet Subject
- facet – all facet results: Facet Year, Facet Author, Facet Journal, Facet Database, Facet Subject
- cluster – Cluster results
- year – Facet Year results
- author – Facet Author results
- journal – Facet Journal results
- database – Facet Database results
- subject – Facet Subject results
- calling_application – Name of the calling application.
- institution – The requested user’s institution holding the cluster/facet configuraion. Has default value of METALIB
Input XML Format
Example:
<?xml version = "1.0" encoding = "UTF-8"?> <x_server_request> <retrieve_cluster_facet_request> <session_id>TL6HGNJDJ8A93JCAY39U18LCJ5AM3XX1MMAS343RAHC8M5VATM</session_id> <set_number>000026</set_number> </retrieve_cluster_facet_request> </x_server_request>
Input URL Syntax
Example:
MetalibPath:port/X?op=retrieve_cluster_facet_request&set_number= Set Number returned by merge_sort&session_id=Login session id
Example URL Syntax
http://10.1.235.60:8332/X?op=retrieve_cluster_facet_request&set_number=000034&session_id=MKR5G7DD5KU3VGSRLVLIHFK178J84P9BCCXRBKQH3SY1QMGI5V
Output XML Format
Explanation of the output values:
The XML output includes for each cluster and facet:
<cluster_facet name=”name”> – Name of Cluster or Facet: Topic, Date, Author, Journal Title, Database, Subject
<node_no_of_docs> – the number of document in each node
<node name=”name” node_level=”level”> – the name of the node
<doc_num> – the number of the document in the merged set
<node_no_of_docs> – the number of document in each node
<node name=”name” node_level=”level”> – the name of the node
<doc_num> – the number of the document in the merged set
Example:
<?xml version = "1.0" encoding = "UTF-8"?> <x_server_response metalib_version="4.00 (20)"> <cluster_facet_response> <cluster_facet name="Topic"> <node_no_of_docs>000000008</node_no_of_docs> <node name="Vegetables" node_level="1"> <node_no_of_docs>10</node_no_of_docs> <doc_num>002989763</doc_num> <doc_num>002985348</doc_num> <doc_num>002989755</doc_num> <doc_num>002989758</doc_num> <doc_num>002989767</doc_num> <doc_num>002989769</doc_num> <doc_num>002989768</doc_num> <doc_num>002985358</doc_num> <doc_num>002985347</doc_num> <doc_num>002985354</doc_num> </node> <node name="Vegetables, And Tomatoes" node_level="2"> <node_no_of_docs>3</node_no_of_docs> <doc_num>002989763</doc_num> <doc_num>002989767</doc_num> <doc_num>002989768</doc_num> </node> <node name="Lutein And Beta-Carotene" node_level="2"> <node_no_of_docs>2</node_no_of_docs> <doc_num>002985348</doc_num> <doc_num>002985354</doc_num> </node> <node name="Propagated" node_level="2"> <node_no_of_docs>2</node_no_of_docs> <doc_num>002989769</doc_num> <doc_num>002985358</doc_num> </node> <node name="Other" node_level="2"> <node_no_of_docs>3</node_no_of_docs> <doc_num>002989755</doc_num> <doc_num>002989758</doc_num> <doc_num>002985347</doc_num> </node> <node name="Tomato fruit" node_level="1"> <node_no_of_docs>3</node_no_of_docs> <doc_num>002985360</doc_num> <doc_num>002985368</doc_num> <doc_num>002985365</doc_num> </node> <node name="Growth" node_level="1"> <node_no_of_docs>2</node_no_of_docs> <doc_num>002985367</doc_num> <doc_num>002985371</doc_num> </node> <node name="Other" node_level="1"> <node_no_of_docs>9</node_no_of_docs> <doc_num>002989764</doc_num> <doc_num>002985352</doc_num> <doc_num>002989761</doc_num> <doc_num>002985357</doc_num> <doc_num>002989751</doc_num> <doc_num>002985372</doc_num> <doc_num>002989760</doc_num> <doc_num>002989750</doc_num> <doc_num>002985350</doc_num> </node> </cluster_facet> <cluster_facet name="Date"> <node_no_of_docs>000000005</node_no_of_docs> <node name="2005" node_level="1"> <node_no_of_docs>6</node_no_of_docs> <doc_num>002989755</doc_num> <doc_num>002989758</doc_num> <doc_num>002989760</doc_num> <doc_num>002989750</doc_num> <doc_num>002989759</doc_num> <doc_num>002989756</doc_num> </node> <node name="2004" node_level="1"> <node_no_of_docs>5</node_no_of_docs> <doc_num>002989757</doc_num> <doc_num>002989762</doc_num> <doc_num>002989763</doc_num> <doc_num>002989766</doc_num> <doc_num>002989765</doc_num> </node> <node name="2003" node_level="1"> <node_no_of_docs>3</node_no_of_docs> <doc_num>002989761</doc_num> <doc_num>002989767</doc_num> <doc_num>002989768</doc_num> </node> <node name="2002" node_level="1"> <node_no_of_docs>3</node_no_of_docs> <doc_num>002989764</doc_num> <doc_num>002989769</doc_num> <doc_num>002989770</doc_num> </node> <node name="Other" node_level="1"> <node_no_of_docs>1</node_no_of_docs> <doc_num>002985351</doc_num> </node> </cluster_facet> <cluster_facet name="Author"> <node_no_of_docs>000000004</node_no_of_docs> <node name="O'Kennedy, Niamh" node_level="1"> <node_no_of_docs>2</node_no_of_docs> <doc_num>002985363</doc_num> <doc_num>002985364</doc_num> </node> <node name="Ghorbel, Mohamed Habib" node_level="1"> <node_no_of_docs>2</node_no_of_docs> <doc_num>002985359</doc_num> <doc_num>002985370</doc_num> </node> <node name="Mezzetti, Bruno" node_level="1"> <node_no_of_docs>2</node_no_of_docs> <doc_num>002989757</doc_num> <doc_num>002989769</doc_num> </node> <node name="Other" node_level="1"> <node_no_of_docs>10</node_no_of_docs> <doc_num>002985345</doc_num> <doc_num>002985371</doc_num> <doc_num>002989764</doc_num> <doc_num>002985352</doc_num> <doc_num>002985354</doc_num> <doc_num>002985351</doc_num> <doc_num>002985353</doc_num> <doc_num>002989761</doc_num> <doc_num>002985358</doc_num> <doc_num>002985357</doc_num> </node> </cluster_facet> <cluster_facet name="Journal Title"> <node_no_of_docs>000000005</node_no_of_docs> <node name="Nutrition Journal" node_level="1"> <node_no_of_docs>9</node_no_of_docs> <doc_num>002989762</doc_num> <doc_num>002989755</doc_num> <doc_num>002989763</doc_num> <doc_num>002989754</doc_num> <doc_num>002989758</doc_num> <doc_num>002989767</doc_num> <doc_num>002989768</doc_num> <doc_num>002989750</doc_num> <doc_num>002989756</doc_num> </node> <node name="BMC Biotechnology" node_level="1"> <node_no_of_docs>4</node_no_of_docs> <doc_num>002989764</doc_num> <doc_num>002989757</doc_num> <doc_num>002989769</doc_num> <doc_num>002989770</doc_num> </node> <node name="BMC Plant Biology" node_level="1"> <node_no_of_docs>2</node_no_of_docs> <doc_num>002989761</doc_num> <doc_num>002989760</doc_num> </node> <node name="Malaria Journal" node_level="1"> <node_no_of_docs>2</node_no_of_docs> <doc_num>002989766</doc_num> <doc_num>002989765</doc_num> </node> <node name="Other" node_level="1"> <node_no_of_docs>14</node_no_of_docs> <doc_num>002985345</doc_num> <doc_num>002985371</doc_num> <doc_num>002985363</doc_num> <doc_num>002985352</doc_num> <doc_num>002985364</doc_num> <doc_num>002985354</doc_num> <doc_num>002985351</doc_num> <doc_num>002985353</doc_num> <doc_num>002985358</doc_num> <doc_num>002985357</doc_num> <doc_num>002985346</doc_num> <doc_num>002985373</doc_num> <doc_num>002985369</doc_num> <doc_num>002989751</doc_num> </node> </cluster_facet> <session_id new_session="N">KU9HFLBK3CLLVXYM4JNUQT4YBTJ3TVU65DSS9T23VG98U9QAIC</session_id> </cluster_facet_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 set number is missing:
<error_code>3102</error_code> <error_text>Set ID is mandatory</error_text>
4. If the institution does not exist:
<error_code>6025</error_code> <error_text>Institution does not exist</error_text>
5. If the merged set is invalid:
<error_code>6063</error_code> <error_text>Set 001234 is not a merged set</error_text>