The Citations Helper is bundled with Sakai and can be tailored to meet the requirements of your institution in a varity of ways. For example, you can provide:
- Your OpenURL resolver and OpenURL link label.
- The name of your Sakai instance, for use with the Google Scholar import feature.
- Your metasearch server, licensed databases, and local search hierarchy, all for use with the "Search Library Resources" feature.
And, if necessary, individual features (or the Citations Helper itself) can be selectively disabled.
Configuration is accomplished through a combination of elements:
- Property values established in your sakai.properties file.
- One or more XML configuration files.
XML configuration files reside in the Resources area of a dedicated "Citations Admin" site, and are the preferred way to set most Citations values. They provide several benefits:
- You can update the Citations configuration on-the-fly, without restarting Tomcat.
- If you're running in a cluster, the updated configuration is available cluster-wide.
- Configuration content is cached, and the cache is updated only when new configuration files become available.
- Sites with complex configuration requirements can use dynamic configuration to select the proper XML configuration files at run time.
- The Sakai administrator can delegate responsibility for maintaining the Citations configuration.
The Citations Helper relies on a few values set in sakai.properties, but the great bulk of the configuration information is provided in XML configuration files. The XML filenames used throughout this text (config.xml and categories.xml) are commonly used in a static configuration.
- config.xml - configures most aspects of the Citations Tool.
- categories.xml - describes databases used with the "Search Library Resources" feature.
A few configuration values should be set in sakai.properties before you first start Sakai.
You'll specify a "citations administration" site ID and a folder to house your configuration files:
You'll also need to specify one or two configuration files:
- The site ID shown above (
citationsAdmin) is the default ID used when none is provided in sakai.properties.
- Once set, the site ID should remain constant across Sakai upgrades and the like. Should the value change, a new, empty "Citations Admin" site will be created, which can lead to some confusion.
- The example above reflects the default, out-of-the-box names for the configuration and search categories files.
- The search categories file, categories.xml, is required only if you use the "Search Library Resources" feature.
At startup time the Citations administration site will be created (assuming it does not already exist). The administration site has the title "Citations Admin" - you'll need to populate "Citations Admin" with XML configuration files tailored for your site.
To initially set up the Citations Helper:
- Login as admin
- Go to the Resources area in your "Citations Admin" site
- Create a folder to hold your configuration files (config in our case)
- Go to "config" and upload your config.xml and categories.xml files.
- Allow other users to administer your Citations configuration files (give them "maintain" access to the "Citations Admin" site) [optional]
Maintenance (updating your configuration)
A typical update sequence looks something like this:
- Login as admin (or another user that has suitable access to "Citations Admin").
- Save a local copy of the configuration file you wish to edit.
- Make your changes locally.
- Move your updated configuration file back to "Citations Admin" using "Upload New Version" in the "Actions" pulldown menu.
Core Feature Configuration
The Citations Helper has several core features to allow you to manipulate citations online.
- Custom Citations - Manually enter form data to create a citation.
- RIS import and export - Move Citations (in RIS format) into and out of Sakai.
These core features are always available when the Citations Helper is enabled.
The Citations Helper can be enabled Sakai-wide or on a site-by-site basis. To enable Citations for your entire Sakai instance:
true - globally enables the Citations Helper. This is the default behaviour.
false - disables Citations.
When the Citations Helper is enabled, all users with the proper permissions can add, revise and remove Citation Lists within the Resources area of any site. Note that each site has the option to disable Citation Lists – this can be done by any user with administrative rights, using the "Options" section of the Resources tool.
Even when Citations support is disabled globally, it's still possible to enable the Citations Helper on a site-by-site basis:
true - turns on the per-site ability to work with Citation Lists.
false - disables the site-by-site setup mechanism.
true, you can enable or disable use of the Citations Helper within each individual site. This can be done by any user with administrative rights to the site, using the "Options" section of the Resources tool. This functionality is useful when Citations support is disabled globally.
Note: Although XML configuration is recommended, the Citations Helper can also be disabled using sakai.properties.
Additional Feature Configuration
If you use an OpenURL resolver at your institution, you can provide the URL with this configuration element:
The default value is:
The registry is a freely available service offered by WorldCat. Based on a user's IP address, the gateway service will locate any registered OpenURL resolvers available to that user.
Google Scholar import
Although the Google Scholar import feature can be used out-of-the-box, registration and some configuration is required to achive the best results.
The Google Scholar import feature is enabled or disabled using the configuration element:
true - enables the ability to import citations from Google Scholar. This is the default.
false - disables the ability to import citations from Google Scholar.
Register your Sakai Instance
If you plan to use the Google Scholar import feature, there is a simple registration process that you need to go through to allow Google to display the name of your Sakai instance.
The details: Google Scholar displays a link within its search results labeled, "Import into your-sakai-instance-name."
For this to work, your Sakai instance name needs to be registered along with a unique id, known as the Sakai server key, that identifies your instance. Usually, the Sakai server key is the base URL of your Sakai instance: i.e.
The registration process is not automated. Please contact the Sakaibrary admin group to register your Sakai instance for use with Google Scholar.
After registering, you will need to add your Sakai server key to your configuration file. Use the following configuration element:
If you have not registered, Google Scholar will display the Citation import link with the default text, "Import into Sakai".
Note: Though XML configuration is recommended, Google Scholar can also be configured using sakai.properties.
Search Library Resources
The Citations Helper can search licensed library databases using any of the following metasearch engines:
Ex Libris Metalib (via the X-Server)
2.4, 2.5, 2.6
SingleSearch (via the Web2 Bridge)
2.4, 2.5, 2.6
360 Search (via their XML API)
The "library search" feature is enabled (or disabled) with the following configuration element:
true - enables the feature. This is the default behavior.
false - disables the feature.
- Although XML configuration is recommended, this feature can also be disabled from sakai.properties.
- Even if you don't use a metasearch engine, you can still enable the Citations Helper to take advantage of the Custom Citation, RIS import and export, and Google Scholar import features.
To support "library search", you'll need to configure the Citations Helper to work with one or more metasearch engines. You'll need to know:
- Which metasearch products are in use at your institution.
- The base URL of the XML gateway used to access each metasearch engine.
- Any user authorization information required to access your XML gateway(s).
Each supported metasearch product provides an XML gateway that provides remote, programmatic access to the metasearch engine. The base URL for this gateway is always required when configuring the "library search" feature.
- For SingleSearch, the XML gateway is the Web2 Bridge. The Web2 base URL is often the base address of your SingleSearch instance followed by
/web2/servlet/MuseWeb2. For example:
- For Ex Libris MetaLib, the XML gateway is called the X-Server. The URL to access the X-Server is usually the base address of your MetaLib instance followed by a
/X. For example:
- For 360 Search, the XML gateway URL is your Serials Solutions ID, followed by the Serials Solutions gateway domain and path. For example:
Some products also require a username and passsword to access the XML gateway. The username provided needs to be able to simultaneously start searches and retrieve records.
See the sample XML configuration for details on specifying XML gateway parameters.
Repository OSID Selection
Each XML gateway has a corresponding Repository OSID implementation. The Repository OSID allows the Citations Helper to communicate with the XML gateway of a particular product. The following configuration snippet selects the Repository OSID for MetaLib:
Depending on the OSID selected, some additional configuration may be required. The sample XML configuration file illustrates this.
Direct URLs and Proxy Prefix Handling
When adding Citations, it may be desirable to save any direct (vendor) URLs returned by the metasearch engine – they can be used to augment the OpenURLs always supplied with Citation Lists. There are several configuration settings:
use the direct URL (if any) as the title link (the OpenURL becomes a supplemental link)
use the direct URL (if any) as a supplemental link (the OpenURL is the title link)
do not use direct URLs at all (the OpenURL is the title link - this is the default behavior)
When direct URLs are in use, you may want to force them to go through your proxy server. To do this, provide a proxy prefix URL:
The text provided will be "prepended" to the direct URLs in your Citation Lists. The prefix is applied only to direct URLs returned by the metasearch engine.
See the sample XML configuration for direct URL and prefix examples.
Note: the utility of the "direct URL" feature depends on the metasearch product in use. A key issue: direct URLs need to be durable (i.e. they should continue to point to the correct content over time).
- Direct URLs have been used successfully with 360 Search.
- Normally, the Repository OSID for SingleSearch does not return direct URLs.
Search Categories and Databases
You'll need to set up a search categories file to describe:
- The search categories you want to use (Science, History, General Studies, etc.).
- The individual databases available at your institution.
To learn more on creating a search categories file, refer to the Search Categories & Databases XML document and the example categories file. You may also want to review the editing overview for Citations configuration files.
Static and Dynamic Configuration
A static configuration is easier to set up, but does not provide the flexibility available with dynamic configuration. For both static and dynamic configurations, an implementation of the
SiteOsidConfigurationAPI is required for Citations Helper to work properly. A default implementation, suitable for use in a static configuration, is provided with Sakai. Please see
Note: The Java code referenced above is in Sakai trunk. If you intend to make changes, be sure to review the code included with your Sakai release.
Here are some tips to consider as you decide which type of configuration will be required at your institution:
- If you plan to use only one metasearch engine, and plan to give all Citations Helper users access to the same set of search categories and databases, static configuration is probably best suited to your needs.
- If you need to control which groups of users can access different search categories and databases, or if you need to use multiple metasearch engines, consider a dynamic configuration.
A small but complete, static configuration is illustrated here: sakai.properties values are shown, as are complete categories.xml and config.xml files.
Both the "Google Scholar import" and the "Search Library Resources" features are enabled. This set of examples assume you're using the 360 Search product.
Definitions in sakai.properties are kept to a minimum. Most configuration elements are better provided in config.xml, where they can be updated without restarting Sakai.
If you plan on using the "Search Library Resources" feature, you'll also need to provide an XML description of your database hierarchy (categories.xml).
Property Values (sakai.properties)
Citations Configuration (config.xml)
The following file illustrates all available Citations configuration elements.
<metasearch-password> elements are required if your site uses Ex Libris Metalib or the SingleSearch metasearch product. These values are not required for Serials Solutions 360 Search; you can omit the elements or provide dummy values.
Database Configuration (categories.xml)
This file is required only if you intend to use the "Search Library Resources" metasearch feature of the Citations Tool. Search categories and individual databases are defined here; this small example reflects the 360 Search product.
- Exactly one default search category must be specified:
<category default="default" id="100" name="My Default Search Category">
- At least one database should be recommended (pre-selected) for each database category:
- The categories file should contain at least two separate database categories. See SAK-10937.
- For a static configuration, every database is placed in the all database group:
- For Ex Libris Metalib sites: Metalib supports three types of databases, shown below.
Only "Search and Retrieve" databases work well with the Citations Helper; typically, only these are added to the XML configuration file.
"Search and Retrieve"
Returns search results
"Search and Link"
Returns a count of hits available and a vendor link
Returns a link to the database (cannot be searched)