General Purpose

This X-Service saves citation information for retrieved records. The service returns the name and location of the output file which can then be loaded into the appropriate Citation Manager.
The records can be obtained either from a search or from records that were saved to an e-Shelf folder by an authenticated user.


  • 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
  • There are two possible flows for selecting records to be saved in citation format:
    • From the full view of the record after a search:
      • source_locate (optional) – locates database(s) by criteria
      • 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 (mandatory for asynchronic searches) – returns the status of the search process
      • retrieve_cluster_facet (optional) – retrieves cluster and facet data for the search results
    • From records in saved to an e-Shelf folder:
      • Authentication (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 or bor_info
      • retrieve_eshelf_folders – retrieves a list of e-Shelf folders defined for a logged-in user
  • save_citation

Input Parameters

1. SESSION_ID – X(50)
2. FORMAT – X(8)

  • SET_NUMBER – X(6) (used only when saving records from a search)
  • FOLDER_NAME – X(20) (used only when saving records from an e-Shelf folder)

4. SET_ENTRY – X(1000)
5. USER ID OPTIONS (used only when saving records from an e-Shelf folder):

  • Option 1
    • SOURCE_ID – X(40)
    • INSTITUTE – X(30)
    • VERIFICATION – X(20)
  • Option 2
    • BOR_ID – X(12)
    • VERIFICATION – X(20)
  • Option 3
    • PDS_HANDLE – X(50)

1. ENCODING – X(20)

Explanation of the mandatory and optional parameters:

  • session_id – The session ID is the unique identifier of the login.
  • format – The relevant Citation Manager for which the records will be saved, either REFWORKS, ISI (for Endnote/ProCite/Reference Manager) or ENDNOTEWEB (available from version 4.3.0).
  • set_number – The set number retrieved by the find_group_info service
  • folder_name – The folder name retrieved by the retrieve_eshelf_folders service.
  • user id – One of the following:
    • source_id – source_ID of user requesting e-Shelf folders/records.
      • institute – User’s institution.
      • verification – User’s password.
    • bor_id – User_ID of teh user requesting e-Shelf folders/records.
      • verification – User’s password
    • pds_handle – User’s unique token returned by the remote authentication system.
  • encoding – The encoding in which the citation will be saved (UTF-8, ISO 8859-1 or ASCII). Default is UTF-8.
  • set_entry – One or more numbers that represent search results or e-Shelf folder items.
    These numbers should be within the range of the specific set.
    Note: There are two options for retrieving muliple records by entering the set_entry field:

    • 000000001-000000010 – Save all documents in the range
    • 000000001,000000010,000000005 – Save specific documents

Input XML Format

Example 1: By set entry using Endnote

<?xml version = "1.0" encoding = "UTF-8"?>

Example 2: Full record view using Refworks

<?xml version = "1.0" encoding = "UTF-8"?>

Input URL Syntax

In order to save citation information, the input parameters must be embedded within the appropriate URL syntax:

MetalibPath:port/X?op=save_citation_request&bor_id=patron num&verification=***&format=format&folder_name=folder_name&set_entry=set_entry&session_id=session_id

Example URL Syntax


Output XML Format

The location of the RIS formatted file holding the citation information:

  • citation_manager_file_location – Path to the RIS formatted file.

Example 1: When the format ‘ISI’ is used (Endnote/ProCite/Reference Manager)

<?xml version="1.0" encoding="UTF-8" ?>
  <x_server_response metalib_version="4.01 (42)">

Example 2: When the format ‘REFWORKS’ is used (Refworks)

<?xml version="1.0" encoding="UTF-8" ?>
  <x_server_response metalib_version="4.01 (42)">

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_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 the present X-Service was activated after the session had timed out:

<error_text>Session timeout</error_text>

3. If the source_id, is provided as an input parameter without an Institution, the following error message appears in the XML output:

<error_text>INSTITUTE must be given along with the source_id</error_text>

4. If the user-id cannot be found:

<error_text>User does not exist</error_text>

5. If the institution does not exist:

<error_text>Institution does not exist</error_text>

6. If the user id can’t be authorized:

<error_text>User cannot be authenticated locally</error_text>

7. If the password and verification don’t match:

<error_text>Your password pincode is not equal to the verification pincode - enter these fields again</error_text>

8. If the password and verification don’t match:

<error_text>Missing mandatory element from XML request .</error_text>

9. If the set_entry is not valid:

<error_text>Invalid set_entry number.</error_text>

10. If the set_number given doesn’t exist:

<error_text>Invalid set number .</error_text>

11. If the search results for the given set_number don’t exist:

<error_text>Search results are missing.</error_text>

12. If the set_entry number is not valid:

<error_text>The entry number is higher then the number of the documents.</error_text>

13. If the folder_name doesn’t exist:

<error_text>Folder does not exist</error_text>

14. If the folder_name given has no records:

<error_text>Folder has no records</error_text>

15. If an error occured while creating the RIS formatted file:

<error_text>Mail/Print action failed. Try again.</error_text>

16. If the format given is invalid:

<error_text>One of the input parameters is not correct.</error_text>