Ready to Learn?Ex Libris products all provide open APIs

Institutional Holdings Data

General Purpose

The institutional holdings data API allows an external application to check the date and file size of the latest Google Scholar holdings file. This API is used by Primo Central to make sure that the SFX institutional holdings file in Google Export format is only retrieved if a new file is available.

The Google Scholar institutional holdings file is harvested by Google once every week and is used by Google to indicate in the Google Scholar search results when electronic full text is available from the end-user’s institutional library. Additionally, the file is used by Primo Central to retrieve holdings information from SFX.
More information on the Google Scholar export format and a list of export options can be found in the Export Tool section of the SFX General User’s Guide.

 

Setup

No setup required - this option is available in SFX V3 and SFX V4 from the following revision/ServicePack onwards:

  • SFX V3: 20100901
  • SFX V4: 4.0.2

 

Input Parameters

Send requests to the following address/program:

<SFX_server>:<port>/<sfx_instance>/cgi/public/get_file_metadata.cgi

Send the request using GET, using the parameter ‘file’.

The parameter ‘file’ includes the type of file – from a list: only the value 'institutional_holding' is currently supported.

URL to use:

<SFX_server>:<port>/<sfx_instance>/cgi/public/get_file_metadata.cgi?file=institutional_holding

 

Input Example

http://sfx.university.org:3210/sfxlcl3/cgi/public/get_file_metadata.cgi?file=institutional_holding

 

Output Parameters

The returned data is in XML format.
The following are institutional holdings data API output parameters: 

ElementDescriptionValueDefaultStructure
File_metadata_APIThis is the main element of the requestNo value root element 
File  No value Sub-element of file_metadata_API
StatusContains the status of the file checking – values can be either “success” or “fail”string Sub-element of File
File_nameContains the full path of the file in URL encoded formatstring Sub-element of File
File_sizeContains the size of the file according to the size scaledigits Sub-element of File
Size_scaleContains the size scale. Value can be “Bytes” onlystring Sub-element of File
Creation_dateContains creation date of the file  in YYYYMMDD formatYYYYMMDD Sub-element of File
Error_messageContains an error message. included only if status is “Failed”string Sub-element of File

 

Error Handling

In case of failure to operate the API, a detailed message is produced:
  • Wrong argument name – an incorrect argument name has been used. For example, instead of file?= the following was used: fil?= (missing “e”):
    The output XML is similar to the following:
<file_metadata_API>
      <file>
                  <status>failed</status>
                  <error_message>wrong argument name: 'fil' instead of 'file'</error_message>
      </file>
</file_metadata_API>
 
  • Wrong file name –- an incorrect the file name has been used, for example, institutional_hold instead
    of institutional_holding. 
    The output XML is similar to the following:
<file_metadata_API>
<file>
<status>failed</status>
<error_message>wrong file name: institutional_hold</error_message>
</file>
</file_metadata_API>
 
  • File does not exist – the file does not exist in its expected location
    The output XML is similar to the following:
<file_metadata_API>
<file>
<status>failed</status>
<error_message>file {full file path} does not exist</error_message>
</file>
</file_metadata_API>
 
Note: The Google export file includes only the valid metadata.
 

Output Example

The following is an example of an output XML:

<file_metadata_API>
<file>
<status>success</status>
<file_name>%2Fexlibris%2Fsfx_ver%2Fsfx4_2%2Fsfxlcl42%2Fexport%2Finstitutional_holding.xml</file_name>
<file_size>1064</file_size>
<size_scale>Byte</size_scale>
<creation_date>20100901</creation_date>
</file>
</file_metadata_API>