ContextObject
Overview of the ContextObject
The ContextObject is used in the following ways in SFX:
- As a metadata container
- To support the evaluation of thresholds that are set in the SFX database
- To support the computation of link-to URLs via target parsers
The ContextObject is an instance of a Perl module named ContextObject::Generic. This instance is created by the sfxmenu.cgi CGI program when it parses the OpenURL.
Metadata from the OpenURL and from additional source parsing is stored in the ContextObject::Generic instance. As such, the ContextObject::Generic instance is a container of metadata of the object for which services have been requested.
The ContextObject::Generic instance is also used to evaluate thresholds when computing the bundle of services that are available for the object. Thresholds set in the SFX database using KBManager are conditions on the content of a ContextObject::Generic instance.
For instance, if the following threshold is set for the Highwire target:
|
$obj->need("year",">",1999) |
The Highwire services can be displayed only if the ContextObject::Generic instance $obj contains a year attribute with a value greater than 1999.
The login.cgi program uses the ContextObject::Generic instance to launch a TargetParser module. This module will use the attributes of the ContextObject::Generic instance to create a URL that links to a target resource.
When the SFX menu is presented to the user, the ContextObject information is printed in the HTML source for debugging purposes. More information about using the ContextObject to debug SFX problems can be found in Troubleshooting and Debugging.
Transporting Metadata: OpenURL Syntax Description
More information about the OpenURL standard can be found at: http://www.niso.org/ (standard Z39.88).
Hybrid OpenURLs
In SFX, if an OpenURL contains both 1.0 and 0.1 elements, the 0.1 elements will be ignored (1.0 being the preferred format).
A URL is treated as 1.0 if either url_ver=Z39.88-2004& or ctx_ver=Z39.88-2004 elements exist.
OpenURL v1.0: SFX Specific Elements
The following section describes OpenURL v1.0: SFX specific elements.
SFX KB Object ID
It is possible to include an SFX object ID from the SFX KB in an OpenURL. Including this element will result in an SFX menu for the specific object from the SFX KB. This is useful in cases where no other unique identifiers (such as ISSN) are available, to reduce the occurrence of multi-object menus.
Element to include: rft.object_id
For example:
http://demo.exlibrisgroup.com:3210/demo?url_ver=Z39.88-2004&url_ctx_fmt=infofi%2Ffmt%3Akev%3Amtx%3Actx;ctx_ver=Z39.88-2004;ctx_enc=info%3Aofi%2Fenc%3AUTF-8;rfr_id=info%3Asid%2Fsfxit.com%3Akbmanager&sfx.ignore_date_threshold=1&rft.object_id=954925388218
- This element is used by SFX sources such as the SFX A-Z List and the Test SFX button in KBManager.
- When used in combination with DirectLinking set to yes and a serviceType restriction, this parameter ensures that a particular OpenURL links directly to one service (example: FullText) provider, without displaying an SFX menu. This occurs because only one service appears in the SFX menu, triggering DirectLinking.
For example:
http://demo.exlibrisgroup.com:3210/demo?url_ver=Z39.88-2004;url_ctx_fmt=infofi/fmt:kev:mtx:ctx;ctx_enc=info:ofi/enc:UTF-8;rfr_id=info:sid/sfxit.com:azlist;sfx.ignore_date_threshold=1;rft.object_id=954925388218;svc.fulltext=yes
SFX Object Portfolio ID
It is possible to include an SFX object portfolio ID in an OpenURL. This restricts the SFX menu to display only one service: the service associated with the object portfolio ID specified in the OpenURL.
Element to include: rft.object_portfolio_id
For example:
http://demo.exlibrisgroup.com:3210/demo?url_ver=Z39.88-2004&url_ctx_fmt=infofi%2Ffmt%3Akev%3Amtx%3Actx;ctx_ver=Z39.88-2004;ctx_enc=info%3Aofi%2Fenc%3AUTF-8;rfr_id=info%3Asid%2Fsfxit.com%3Akbmanager&sfx.ignore_date_threshold=1&rft.object_id=954925388218&rft.object_portfolio_id=110981564625337
When used in combination with DirectLinking set to yes, this parameter ensures that a particular OpenURL links directly to one provider, without displaying an SFX menu. This occurs because only one service appears in the SFX menu, triggering DirectLinking.
Ignore SFX KB Date Thresholds
The SFX server, when calculating which services to include in the SFX menu, takes into account any thresholds defined in the SFX KB.
For certain sources, this may not be appropriate—for example, if these sources are known not to include date information. This is the case, for example, for OPAC systems, where the records for journals may be related to the print version and not the electronic one.
To make sure services are not excluded from the SFX menu when coming from these sources, it is possible to include an element that triggers SFX not to take into account date thresholds in the SFX KB.
Element to include: sfx.ignore_date_threshold=1
For example:
http://demo.exlibrisgroup.com:3210/demo?url_ver=Z39.88-2004&url_ctx_fmt=infofi%2Ffmt%3Akev%3Amtx%3Actx;ctx_ver=Z39.88-2004;ctx_enc=info%3Aofi%2Fenc%3AUTF-8;rfr_id=info%3Asid%2Fsfxit.com%3Akbmanager&sfx.ignore_date_threshold=1&rft.object_id=954925388218&rft.object_portfolio_id=110981564625337
Type of Response
This element can be used only for XML 1.0 OpenURLs (SFX API).
Element to include: sfx.response_type
Possible Values: html/sfx_api_0_1_xml/simplexml/multi_obj_xml/service_exist
- html – SFX presents the SFX menu.
- sfx_api_0_1_xml – SFX responds in the OpenURL 0.1 XML response. (This format was the format available in SFX version 2.0 API and is intended for backward compatibility.)
- simplexml – SFX responds in the OpenURL 1.0 XML response, presenting in XML format a list of targets with target URLs for all services that should appear in the SFX menu. simplexml format supports XML files that contain only one ContextObject.
- multi_obj_xml – The multi_obj_xml format is the same as the simplexml format, except that it supports XML files containing one or more ContextObjects.
- service_exist – SFX responds by indicating whether services exist for a particular ContextObject. This format supports XML files that contain one or more ContextObjects. No target URLs or details about services are provided, which makes this format lightweight and fast. It can be used in combination with the ServiceType restriction (for instance FullText) to include full-text indicator buttons for records with full-text in SFX.
The following is an example of a response:
|
<?xml version="1.0" encoding="UTF-8" ?> <ctx_obj_set> <ctx_obj index="02" id="954925373792"> <service_exist> <services>no</services> </service_exist> </ctx_obj> <ctx_obj index="01" id="954925469303"> <service_exist> <services>yes</services> </service_exist> </ctx_obj> </ctx_obj_set> |
ContextObject Attributes
The current implementation of the Generic::Request instance includes all tags that are defined in the OpenURL 1.0 standard (SAP1 and SAP2). Additionally, the ContextObject contains OpenURL 0.1 tags (to ensure backward compatibility) and a number of SFX-specific attributes.
A list of all currently supported attributes can be found in the /exlibris/sfx_ver/sfx4_1/<instance>/config/ctx_attribute.config_ file. This file lists all attributes that can be set by a ContextObject::Generic instance. The first column specifies the name of the attribute. The second column is a regular expression giving the boundary conditions on the attribute. If the values stored in the ContextObject::Generic do not match the regular expression, these values are ignored.
The suffix config_ is important. The underscore at the end indicates that the files will not be copied to the local instances. Instead, a symbolic link is used from the sfxlcl41 to the sfxglb41 instance. The attributes mentioned above should not be edited.
Some attribute names start with a @ sign. This is a reminder for the programmer that the value of these attributes is not a string but an array reference.
Support for additional local attributes can be added by editing the following configuration file on the server:
/exlibris/sfx_ver/sfx4_1/<sfx_instance>/config/ctx_attrib_local.config
Resolution of OpenURLs containing Object Portfolio IDs
SFX is able to resolve OpenURLs that contain an object portfolio ID in addition to an ISSN or object ID. SFX restricts the menu services to the provider (target) connected to the portfolio. If direct linking is turned on (see the Direct Link section of the SFX General User’s Guide), SFX forwards the user directly to the URL built by the target parser for that provider.
Example OpenURL including Object Portfolio ID
http://sfx.university.edu:3210/sfxlcl41?url_ver=Z39.88-2004&url_ctx_fmt=infofi/fmt:kev:mtx:ctx&ctx_enc=info:ofi/enc:UTF-8&ctx_ver=Z39.88-2004&rfr_id=info:sid/sfxit.com:azlist&rft.issn=0000-0019&rft.object_portfolio_id=111030372947000&svc.fulltext=yes&sfx.ignore_date_threshold=1
Components
Retrieving Object Portfolio IDs for Use in OpenURLs
SFX object portfolio IDs are available via export from the SFX KnowledgeBase. More information about export tools in general can be found in the Export Tool section of the SFX General User’s Guide.
Recommended exports that contain object portfolio IDs along with ISSNs and target information are:
- Advanced exports in text-tab-delimited
- XML formats
Exports can be run via the SFX Admin Center Web interface in the Export Tool GUI or via the UNIX command line with the export.pl script (described in Command-Line Export Tool).
In the text export, the following columns are relevant:
- Column 4: ISSN
- Column 12: Object Portfolio ID
In the XML export, the relevant data is organized as follows:
| ISSN | <datafield tag="022" ind1="" ind2=""> <subfield code="a">0009-2347</subfield> |
| Object ID | <datafield tag="090" ind1="" ind2=""> <subfield code="a">954925376877</subfield> |
| Object Portfolio ID | <datafield tag="866" ind1="" ind2=""> <subfield code="z">110996846962000</subfield> |
If relevant ISSNs and object portfolio IDs are placed in the OpenURL template below, actionable OpenURLs are formed.
|
<BASE_URL>?url_ver=Z39.88-2004&url_ctx_fmt=infofi/fmt:kev:mtx:ctx&ctx_enc=info:ofi/enc:UTF-8&ctx_ver=Z39.88-2004&rfr_id=info:sid/sfxit.com:azlist&rft.issn=<ISSN>&rft.object_portfolio_id=<OBJECT_PORTFOLIO_ID>&svc.fulltext=yes&sfx.ignore_date_threshold=1 |
It is also possible to create a link with object ID, using the following OpenURL template:
|
<BASE_URL>?url_ver=Z39.88-2004&url_ctx_fmt=infofi/fmt:kev:mtx:ctx&ctx_enc=info:ofi/enc:UTF-8&ctx_ver=Z39.88-2004&rfr_id=info:sid/sfxit.com:azlist&rft.object_id=<Object_ID>&rft.object_portfolio_id=<OBJECT_PORTFOLIO_ID>&svc.fulltext=yes&sfx.ignore_date_threshold=1 |
Image-Based Linking
When SFX receives an OpenURL with a proprietary parameter, SFX returns a .gif instead of an SFX menu. This .gif differs, depending on whether or not a particular type of service is present.
For example, SFX returns:
- a transparent .gif, if no full-text services are available (a transparent .gif is invisible to the end user, so it looks as if no image is returned)
- a full-text indicator button if full-text is available – Behind the full-text indicator button is a standard OpenURL with a service type, so direct linking to full-text can occur.
The proprietary parameter can be:
- For OpenURL 0.1: either _response_type=image-large or _response_type=image-small
- For OpenURL 1.0: either sfx.response_type=image-large or sfx.response_type=image-small
When used as a means to present full-text indicator buttons, the _response_type=image parameter is always used in conjunction with the _service_type parameter.
Configuration of the “look and feel” of the images is defined in each SFX instance, in the config/response_type_img.config_ file.
The only source currently using image-based linking is Elsevier Scopus. This feature can be used for sources other than Elsevier Scopus, but should be used only for individual records, not for result lists. Using this feature for more than one record at a time may result in slowness or even downtime of the SFX server, as this may drastically increase the number of SFX requests received by SFX.
Image-Based Linking for Each Search Result in the Scopus Brief
Result Display
- OpenURL returns a (large, Scopus-specific) button if at least one full-text service is available.
For example:
http://demo.exlibrisgroup.com:9003/demo?sid=Elsevier:Scopus&issn=0003-0007&date=2002&__service_type=getFullTxt&__response_type=image-large
Image used: /exlibris/sfx_ver/sfx4_1/<sfx_instance>/templates/img/sfxmenu/service_fulltxt.gif
- OpenURL returns a transparent button if no full-text service is available.
For example:
http://demo.exlibrisgroup.com:9003/demo?sid=Elsevier:Scopus&issn=1520-765X&date=2002&__service_type=getFullTxt&__response_type=image-large
Image used: /exlibris/sfx_ver/sfx4_1/<sfx_instance>/templates/img/sfxmenu/service_not_found.gif
Image-Based Linking in the Journal Title List from Scopus
- OpenURL returns a small blue image if at least one full-text service is available.
For example:
http://demo.exlibrisgroup.com:9003/demo?sid=Elsevier:ScopusBrowse&issn=0003-0007&__service_type=getFullTxt&__response_type=image-small
Image used: /exlibris/sfx_ver/sfx4_1/<sfx_instance>/templates/img/sfxmenu/service_fulltxt_sm.gif
- OpenURL returns a small white image if no full-text is available.
For example:
http://demo.exlibrisgroup.com:9003/demo?sid=Elsevier:ScopusBrowse&issn=1520-765&__service_type=getFullTxt&__response_type=image-small
Image used: /exlibris/sfx_ver/sfx4_1/<sfx_instance>/templates/img/sfxmenu/service_not_found_sm.gif
Image-Based Linking Without a Specified ServiceType
- OpenURL returns Scopus-specific SFX button if at least one SFX service is available.
For example:
http://demo.exlibrisgroup.com:9003/demo?sid=Elsevier:Scopus&issn=1520-765X&date=2002&__response_type=image-large
Image used: /exlibris/sfx_ver/sfx4_1/<sfx_instance>/templates/img/sfxmenu/service_default.gif
- OpenURL returns a transparent button if no SFX service is available.
Image used: /exlibris/sfx_ver/sfx4_1/<sfx_instance>/templates/img/sfxmenu/service_not_found.gif
Additional OpenURL 1.0 Functionality
If OpenURL contains sid/rfr.id information and SFX finds the corresponding source name, it is possible to use a source-specific image during image-based linking. If SFX finds a source-specific image, this image is used. If no source-specific image is found, the default image is shown.
Setup
Configuration file with images: config/response_type_img.config_
For example:
|
<base-url>?url_ver=Z39.88-2004&url_tim=2004-01-09&ctx_ver=Z39.88-2004&ctx_enc=info%3Aofi%2Fenc%3AUTF-8&ctx_tim=2002-03-20T08%3A55%3A12Z&rft_id=info:oai/arXiv.org:hep-th%2F0404069 |
The rft_id is: info:oai/arXiv.org:hep-th%2F0404069
SFX finds the corresponding SOURCE_ID: ARXIV
Add the following line to the section “image”:
|
getFullTxt_large.ARXIV "$ENV{SFXCTRL_HOME}/templates/img/sfxmenu/arxiv_fulltxt.gif" |
The configuration file should look like the following:
|
Section "image"
default_small "$ENV{SFXCTRL_HOME}/templates/img/sfxmenu/service_default_sm.gif" notFound_large "$ENV{SFXCTRL_HOME}/templates/img/sfxmenu/service_not_found.gif" notFound_small "$ENV{SFXCTRL_HOME}/templates/img/sfxmenu/service_not_found_sm.gif"
getFullTxt_large "$ENV{SFXCTRL_HOME}/templates/img/sfxmenu/service_fulltxt.gif"
getFullTxt_large.ARXIV "$ENV{SFXCTRL_HOME}/templates/img/sfxmenu/arxiv_fulltxt.gif" |
As a result, an OpenURL with sfx.response_type=image-large:
|
<base-url>?url_ver=Z39.88-2004&url_tim=2004-01-09&ctx_ver=Z39.88-2004&ctx_enc=info%3Aofi%2Fenc%3AUTF-8&ctx_tim=2002-03-20T08%3A55%3A12Z&rft_id=info:oai/arXiv.org:hep-th%2F0404069&sfx.response_type=image-large |
should result in the source-specific image specified in configuration file:
