retrieve_cluster_facet

NAVIGATE CONTENT
Ex Libris Developer Network MetaLib Documentation MetaLib APIs X-Services 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

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>