retrieve_eshelf_folder_records

Ex Libris Developer Network MetaLib Documentation MetaLib APIs X-Services retrieve_eshelf_folder_records

General Purpose

This X-Service enables you to retrieve a single record or multiple records (documents) included an eShelf folder defined for a logged-in user.

The calling application sends the eShelf identifier (eShelf folder name + User ID), and the record number or a range of numbers from the required folder. The input parameters are taken from the retrieve_my_eshelf_folders X-Service.

This service supports OpenURL 1.0 standard and retrieves it when requested. The document can be retrieved in three view options: Full view , Brief view or Customize view according to the <view> input parameter. The document can be displayed in two formats:

Original – The original record from the search target as loaded into MetaLib’s temporary database in MARC exchange format (ISO 2709). In this X-Service, the original record type is specified as ‘original-marc’ format.
Converted – The original record as converted by MetaLib for display in MARC21 format. In this X-Service, the converted record type is specified as ‘marc’ format, and is the default value.

Both record types are returned in the X-Service response in OAI-MARC-XML format.

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

or bor_info (optional)

retrieve_my_eshelf_folders* – Retrieves a list of eShelf folders defined for a logged-in user
retrieve_eshelf_folder_records

Input Parameters

Mandatory

1. SESSION_ID – X(50)

2. USER ID OPTIONS:

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).
  3. FOLDER_NAME – X(20).
  4. FOLDER_ENTRY – X(1000).

Optional

1. FORMAT – X(20).

Explanation of the mandatory and optional parameters:

session_id: The session ID is the unique identifier of the login.
user id – One of the following:
- source_id – Source_ID of user requesting eShelf folders.
  - institute – User’s institution.
  - verification – User’s password
- bor_id – User_ID of the user requesting eShelf folders.
  - verification – User’s password
- pds_handle – User’s unique token returned by the remote authentication system
folder_name – Identifier of the folder(+ User ID). Retrieved in retrieve_my_eshelf_folders service. Is case sensitive.
folder_entry – One or more numbers that represent search results. These numbers should be within the specific folder’s results range.

Note: There are two options for retrieving multiple records by entering the folder_entry field:

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

Each entry value must be a 9-digit string, with leading zeros if necessary.

format – Document display format.
Valid values:
- marc – default
- original-marc
view – Valid values:
- full – retrieves all the document fields – default.
- brief – retrieves specific fields according to dat01/ /tab/www_tab_present_brief table
- customize – retrieves specific fields according to input parameters below (in the <field> and <sub_field> fields)
field – enter one of the document field codes.
The field code format is five characters in the following combination:
- The first three characters represent the document tags, for instance: “245”, “SID”, “LDR” (for leader).
- The last two characters represent the tag indicators. “#” is a wildcard for any character.
- Character #4 represents tag-ind1 and character #5 represent tag-ind2.
- Exceptions are the “YR” (Year) field, which has two characters for the tag and two characters for the tag indicator, and OPURL (for OpenURL).
- The whole combination should match the Marc21 format.
  For URL syntax, use “%23” instead of “#”.

sub_field – valid values :
- empty – retrieves all the subfields
- letters – retrieves the specified subfields

Input XML Format

Examples:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <retrieve_eshelf_folder_records_request>
    <session_id>3N175V44EL8HQI46U9K1QY4BXU488UF215P2R2XAMD4DQX6CCM</session_id>
      <source_id>metalib1</source_id>
      <verification>metalib1</verification>
      <institute>METALIB</institute>
      <folder_name>Basket</folder_name>
      <folder_entry>000000001</folder_entry>
      <format>marc</format>
  </retrieve_eshelf_folder_records_request>
</x_server_request>

Customize Option:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <retrieve_eshelf_folder_records_request>
    <session_id>3N175V44EL8HQI46U9K1QY4BXU488UF215P2R2XAMD4DQX6CCM</session_id>
    <source_id>metalib1</source_id>
    <verification>metalib1</verification>
    <institute>METALIB</institute>
    <folder_name>Basket</folder_name>
    <folder_entry>000000001</folder_entry>
    <format>marc</format>
    <view>customize</view>
    <field>LDR##</field>
    <field>700##</field>
    <sub_field>ab</sub_field>
    <field>SID  </field>
    <sub_field>aij</sub_field>
    <field>YR###</field>
    <field>RAN##</field>
    <field>OPURL</field>
  </retrieve_eshelf_folder_records_request>
</x_server_request>

Input URL Syntax

In order to retrieve folder record(s), the session_id, User_id, folder_name, folder_entry and format attributes must be embedded within the URL syntax:

MetalibPath:port/X?op=retrieve_eshelf_folder_records_request&bor_id=patron num&verification=David&institute=metalib&folder_name=folder name&folder_entry=one of the results set range&format=marc&session_id=Login session id

Example URL Syntax

Example 1: Full View

http://10.1.235.60:8334/X?op=retrieve_eshelf_folder_records_request&source_id=David&verification=David&institute=metalib&folder_name=frog&folder_entry=000000001&session_id=Pb3AK5YHFB3AIN2T12FXX267SPABSADKJ8SYEN3CYJMR6A5TLL

Example 2: Customize View

http://10.1.235.60:8334/X?op=retrieve_eshelf_folder_records_request&source_id=David&verification=David&institute=metalib&folder_name=frog&folder_entry=000000001&view=customize&field=022%23%23&field=245%23%23&session_id=PB3AK5YHFB3AIN2T12FXX267SPABSADKJ8SYEN3CYJMR6A5TLL

Output XML Format

If the record and the folder exist, the document will be retrieved in MARC format, and will include Metalib internal information such as SID and RAN.

SID – This field is created automatically by the system. It includes the name of the resource, the access method and the ID of the record in the target.
RAN – The ranked value of the document. Valid values: 0-99, where 99 means an excellent ranking grade.
SAV – Date the record was saved to the folder. Corresponds to date format system parameter aleph_date_time and has two possible values:
- EUROPEAN
- US
openURL – Retrieves the openURL of the document (search result) for the customize view option, according to request

Examples:

Option 1: Full View

<x_server_response metalib_version="4.00 (20)">
  <retrieve_eshelf_folder_records_response>
    <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"
      <datafield tag="035" ind1=" " ind2=" ">
        <subfield code="a">15612591</subfield>
      </datafield>
      <datafield tag="245" ind1=" " ind2=" ">
        <subfield code="a">[Part of mRNA upstream the E site bound codon is close to protein S26 On the human
80S ribosome]</subfield>
      </datafield>
      <datafield tag="500" ind1=" " ind2=" ">
        <subfield code="a">ppublish</subfield>
      </datafield>
      <datafield tag="513" ind1=" " ind2=" ">
        <subfield code="a">Journal Article</subfield>
      </datafield>
      <datafield tag="546" ind1=" " ind2=" ">
        <subfield code="a">rus</subfield>
      </datafield>
      <datafield tag="520" ind1=" " ind2=" ">
        <subfield code="a">Positioning of mRNA on the
80S ribosome upstream the E site bound codon was studied
using derivatives of nona- and dodecaribonucleotides containing
the triplet UUU coding for Phe at the 3'-terminus, and a perfluorophenylazide
cross-linker on either the first or the third nucleotide. Two sets of the
mRNA analogues were used, with the photoactivatable groups on
either the C5 atom of the uridine or the N7 atom of the guanosine. The
modified nucleotides were directed to positions from -4 to -9 with respect
to the first nucleotide of the P site bound codon by tRNA(Phe) cognate
to the triplet UUU targeted to the P site. Mild UV-irradiation of
ribosomecomplexes with tRNA(Phe) and mRNA analogues resulted in the
cross-linking to the 40S subunits preferentially, mainly to the
proteins. The principal target for the cross-linking was protein S26 in all
cases. Location of the photoactivatable group on the nucleotide at position
-4 lead also to the minor cross-linking to protein S3, and at position -6 to
protein S14. In the absence of tRNA, all mRNA analogues cross-linked to
protein S3.</subfield>
      </datafield>
      <datafield tag="024" ind1=" " ind2=" ">
        <subfield code="a">101859546</subfield>
      </datafield>
      <datafield tag="VOL" ind1=" " ind2=" ">
        <subfield code="a">38</subfield>
      </datafield>
      <datafield tag="YR " ind1=" " ind2=" ">
        <subfield code="a">2004</subfield>
      </datafield>
        <datafield tag="022" ind1=" " ind2=" ">
        <subfield code="a">0026-8984</subfield>
      </datafield>
      <datafield tag="PAG" ind1="E" ind2=" ">
        <subfield code="a">1033-40</subfield>
      </datafield>
      <datafield tag="ISS" ind1="U" ind2=" ">
        <subfield code="a">6</subfield>
      </datafield>
      <datafield tag="SID" ind1=" " ind2=" ">
        <subfield code="a">EXTERNAL</subfield>
        <subfield code="b">PUBMED</subfield>
        <subfield code="d">CKB00158</subfield>
        <subfield code="i">000000</subfield>
        <subfield code="j">000001</subfield>
      </datafield>
      <controlfield tag="RAN">016</controlfield>
        <datafield tag="773" ind1=" " ind2=" ">
          <subfield code="b">38</subfield>
          <subfield code="t">2004 Nov-Dec</subfield>
          <subfield code="a">Mol Biol (Mosk)</subfield>
          <subfield code="g">1033-40</subfield>
          <subfield code="d">6</subfield>
        </datafield>
     <controlfield tag="SAV">07/08/2005</controlfield>
    </record>
    <session_id new_session="N">KSUXXUJ7N4N9STUV7VSHE1MR7IS1S966EQ8AJG5UNFB7BRUB8Q</session_id>
  </retrieve_eshelf_folder_records_response>
</x_server_response>

Option 2: Brief View

<x_server_response metalib_version="4.00 (20)">
    <retrieve_eshelf_folder_records_response>
    <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"
      <datafield tag="SID" ind1=" " ind2=" ">
        <subfield code="a">EXTERNAL</subfield>
        <subfield code="b">PUBMED</subfield>
        <subfield code="d">CKB00158</subfield>
      </datafield>
      <datafield tag="245" ind1=" " ind2=" ">
        <subfield code="a">A tax to prevent the epidemic of lung cancer.</subfield>
      </datafield>
      <datafield tag="YR " ind1=" " ind2=" ">
        <subfield code="a">2005</subfield>
      </datafield>
     </record>
 
    <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"
      <datafield tag="SID" ind1=" " ind2=" ">
        <subfield code="a">EXTERNAL</subfield>
        <subfield code="b">PUBMED</subfield>
        <subfield code="d">CKB00158</subfield>
      </datafield>
      <datafield tag="245" ind1=" " ind2=" ">
        <subfield code="a">The relationship between time since registration and
measured incidence rates in the General Practice Research Database.</subfield>
      </datafield>
      <datafield tag="YR " ind1=" " ind2=" ">
        <subfield code="a">2005</subfield>
      </datafield>
    </record>
 
    <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"
    <datafield tag="SID" ind1=" " ind2=" ">
        <subfield code="a">EXTERNAL</subfield>
        <subfield code="b">PUBMED</subfield>
        <subfield code="d">CKB00158</subfield>
      </datafield>
      <datafield tag="245" ind1=" " ind2=" ">
        <subfield code="a">Study of tumour cell invasion by Fourier transform infrared microspectroscopy.</subfield>
      </datafield>
      <datafield tag="YR " ind1=" " ind2=" ">
        <subfield code="a">2005</subfield>
      </datafield>
      </record>
      <session_id new_session="N">GYMF5TT51PPEIIK9CKG7B4LFGKAM7JXHN7IVI4MJUB5KBRINJJ</session_id>
    </retrieve_eshelf_folder_records_response>
  </x_server_response>

Option 3: Customize View

<x_server_response metalib_version="4.00 (20)">
  <retrieve_eshelf_folder_records_response>
    <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"
    <datafield tag="SID" ind1=" " ind2=" ">
      <subfield code="a">EXTERNAL</subfield>
      <subfield code="b">PUBMED</subfield>
      <subfield code="j">000003</subfield>
      </datafield>
    <controlfield tag="RAN">062</controlfield>
    <openURL>
    <?xml version="1.0" encoding="UTF-8"?>
    <ctx:context-objects xmlns:ctx="info:ofi/fmt:xml:xsd:ctx"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation= "info:ofi/fmt:xml:xsd:ctx http://www.openurl.info/registry/docs/info:ofi/fmt:xml:xsd:ctx">
    <ctx:context-object timestamp="2004-01-16T12:13:00Z" version="Z39.88-2004" identifier="123">
    <ctx:referent>
    <ctx:metadata-by-val>
    <ctx:format>  info:ofi/fmt:xml:xsd</ctx:format>
    <ctx:metadata>
    <rft:journal xmlns:rft="info:ofi/fmt:xml:xsd:journal" xsi:schemaLocation="info:ofi/fmt:xml:xsd:journal               http://www.openurl.info/registry/docs/info:ofi/fmt:xml:xsd:journal">
    <rft:author rank="1">
    <rft:aulast>Fujita</rft:aulast>
    <rft:aufirst> Hirmasa  Hirmasa</rft:aufirst>
    <rft:auinit></rft:auinit>
    </rft:author>
    <rft:atitle>Prospective non-randomized trial comparing
esophagectomy-followed-by-chemoradiotherapy versus
chemoradiotherapy-followed-by-esophagectomy for T4 esophageal cancers.</rft:atitle>
    <rft:date></rft:date>
    <rft:volume>90</rft:volume>
    <rft:issue>4</rft:issue>
    <rft:spage>209</rft:spage>
    <rft:epage>219</rft:epage>
    <rft:genre></rft:genre>
    <rft:issn>0022-4790</rft:issn>
    </rft:journal>
    </ctx:metadata>
    </ctx:metadata-by-val>
    <ctx:metadata-by-ref>
    <ctx:format></ctx:format>
    <ctx:location></ctx:location>
    </ctx:metadata-by-ref>
    </ctx:referent>
    <ctx:referring-entity>
    <ctx:identifier></ctx:identifier>
    </ctx:referring-entity>
    <ctx:requester>
    <ctx:metadata-by-ref>
    <ctx:format></ctx:format>
    <ctx:location></ctx:location>
    </ctx:metadata-by-ref>
    </ctx:requester>
    <ctx:service-type>
    </openURL>
    </record>
    <session_id new_session="N">9PD92EE857RGG98YEL4QCRH3E7KKRPK3HNXTYBB16UHJ9JCAKB</session_id>
  </retrieve_eshelf_folder_records_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 folder name is missing:

<error_code>6008</error_code>
<error_text>Folder name is mandatory</error_text>

4. If the folder does not exist:

<error_code>6007</error_code>
<error_text>Folder $1 does not exist</error_text>

5. If the User ID is missing:

<error_code>6004</error_code>
<error_text>User Id is mandatory</error_text>

6. If the requested folder entry is higher than the number of the documents in the folder:

<error_code>2032</error_code>
<error_text>The entry number is higher than the number of the documents</error_text>

7. If the requested folder has no records:

<error_code>2036</error_code>
<error_text>Folder has no records</error_text>

8. If the User does not exist:

<error_code>6001</error_code>
<error_text>User does not exist</error_text>

9. If the folder entry is invalid (Invalid range):

<error_code>6000</error_code>
<error_text>Invalid folder entry number/s</error_text>

10. If an invalid view is requested:

<error_code>6028</error_code>
<error_text>Invalid view</error_text>

11. If the format of the pds_handle is incorrect:

<error_code>6062</error_code>
<error_text>Invalid pds_handle format</error_text>

12. If the pds_handle is not valid:

<error_code>6061</error_code>
<error_text>Invalid pds_handle</error_text>

Note:
If 11 or 12 above are returned, the request will not terminate in error. The onus is on the calling application as to how to proceed.