This document applies to Sakai 2.6.0 and subsequent releases.

Information for previous Sakai releases is still available: Sakai 2.4 and the post-2.4 and 2.5 releases.

 

Overview

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:

And, if necessary, individual features (or the Citations Helper itself) can be selectively disabled.

Configuration is accomplished through a combination of elements:

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:

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.

Sakai Properties

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:

Notes:

XML Configuration

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.

Initial Setup

To initially set up the Citations Helper:

  1. Login as admin
  2. Go to the Resources area in your "Citations Admin" site
  3. Create a folder to hold your configuration files (config in our case)
  4. Go to "config" and upload your config.xml and categories.xml files.
  5. Allow other users to administer your Citations configuration files (give them "maintain" access to the "Citations Admin" site) [optional]

For more information, see the sample configuration file, the sample categories file and Sakaibrary's Search Categories & Databases XML page.

Maintenance (updating your configuration)

A typical update sequence looks something like this:

  1. Login as admin (or another user that has suitable access to "Citations Admin").
  2. Save a local copy of the configuration file you wish to edit.
  3. Make your changes locally.
  4. 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.

These core features are always available when the Citations Helper is enabled.

Enabling Citations

The Citations Helper can be enabled Sakai-wide or on a site-by-site basis. To enable Citations for your entire Sakai instance:

  <citations-enabled-by-default>true|false</citations-enabled-by-default>

  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:

  <citations-enabled-site-by-site>true|false</citations-enabled-site-by-site>

  true - turns on the per-site ability to work with Citation Lists.
  false - disables the site-by-site setup mechanism.

When 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

OpenURL Resolver

If you use an OpenURL resolver at your institution, you can provide the URL with this configuration element:

  <openurl-resolveraddress>http://your-resolver-url</openurl-resolveraddress>

The default value is:

  http://worldcatlibraries.org/registry/gateway

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:

  <google-scholar-enabled>true|false</google-scholar-enabled>

  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. coursemanagement.university.edu.

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:

  <sakai-serverkey>your-sakai-server-key</sakai-serverkey>

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:

Metasearch Engine

Sakai Release

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)

2.6

The "library search" feature is enabled (or disabled) with the following configuration element:

  <library-search-enabled>true|false</library-search-enabled>

  true - enables the feature. This is the default behavior.
  false - disables the feature.

Notes:

XML Gateway

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:

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.

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:

  <osid-impl>org.sakaibrary.osid.repository.xserver</osid-impl>

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:

Value

Description

title-link

use the direct URL (if any) as the title link (the OpenURL becomes a supplemental link)

related-link

use the direct URL (if any) as a supplemental link (the OpenURL is the title link)

false

do not use direct URLs at all (the OpenURL is the title link - this is the default behavior)

An example:

  <provide-direct-url>related-link</provide-direct-url>

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:

  <direct-url-prefix>http://example.com/cgi-bin/proxy.pl?url=</direct-url-prefix>

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).

Search Categories and Databases

You'll need to set up a search categories file to describe:

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

There are two type of Citations Helper configuration: static and dynamic configuration.

Configuration details are the same for each user, and are provided using:

  • sakai.properties values
  • config.xml and categories.xml configuration files
  • The default SiteOsidConfiguration implementation provided with Sakai

Configuration details can vary, based on user characteristics. Details are provided using:

  • sakai.properties values
  • One or more XML configuration files
  • A custom implementation of the SiteOsidConfiguration API

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 SiteOsidConfiguration API is required for Citations Helper to work properly. A default implementation, suitable for use in a static configuration, is provided with Sakai. Please see SampleSiteOsidConfiguration for details.

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:

Sample 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)

#
# Citation Helper configuration
#
# Citations administrative site ID, configuration file directory
#
adminSiteName@org.sakaiproject.citation.api.ConfigurationService=citationsAdmin
configFolder@org.sakaiproject.citation.api.ConfigurationService=config
#
# Cached configuration files (these are the default names)
#
configXmlCache@org.sakaiproject.citation.api.ConfigurationService=config.xml
databaseXmlCache@org.sakaiproject.citation.api.ConfigurationService=categories.xml


Citations Configuration (config.xml)

The following file illustrates all available Citations configuration elements.

<config>
  <!-- Sample Citations configuration -->

  <!-- Enable Citations system wide and site-by-site -->

  <citations-enabled-by-default>true</citations-enabled-by-default>
  <citations-enabled-site-by-site>true</citations-enabled-site-by-site>

  <!-- Library Search (enabled) and Metasearch configuration -->
  <!--    Replace "example.com" with the URL for your metasearch -->
  <!--    server and supply the apporpriate username and password -->

  <library-search-enabled>true</library-search-enabled>

  <metasearch-baseurl>http://example.com</metasearch-baseurl>
  <metasearch-username>none</metasearch-username>
  <metasearch-password>none</metasearch-password>

  <!-- Repository OSID implementation to use -->
  <!--    edu.indiana.lib.osid.base.repository.http (Sirsi SingleSearch, 360 Search) -->
  <!--    org.sakaibrary.osid.repository.xserver    (Ex Libris MetaLib)  -->

  <osid-impl>edu.indiana.lib.osid.base.repository.http</osid-impl>

  <!-- Extended Repository ID -->
  <!--    360 Search Repository    (Serials Solutions 360 Search) -->
  <!--    Web2 Repository          (Sirsi SingleSearch - Web2 Bridge) -->

  <extended-repository-id>360 Search Repository</extended-repository-id>

  <!-- Maximum number of databases a user can search at one time.  This -->
  <!-- defaults to eight (the maximum for Ex Libris and SingleSearch) -->

  <searchable-databases>8</searchable-databases>

  <!-- Google Scholar (enabled) -->
  <!--    Replace "sakai-instance-name" with the name of your Sakai instance -->

  <google-scholar-enabled>true</google-scholar-enabled>

  <google-baseurl>http://scholar.google.com/schhp</google-baseurl>
  <sakai-serverkey>"sakai-instance-name"</sakai-serverkey>

  <!-- OpenUrl Resolver to use, OpenURL link label -->
  <!--    Use your local resolver URL (if you're running a resolver) -->
  <!--    http://worldcatlibraries.org/registry/gateway (if you've registered) -->

  <openurl-resolveraddress>http://worldcatlibraries.org/registry/gateway</openurl-resolveraddress>
  <openurl-label>Get It</openurl-label>

  <!-- Direct URL handling -->
  <!--    title-link   (use the direct URL (if any) as the title link) -->
  <!--    related-link (use the direct URL (if any) as a related link) -->
  <!--    false        (do not use direct URLs) -->

  <provide-direct-url>related-link</provide-direct-url>

  <!-- Direct URL prefix text (for proxy access) -->

  <direct-url-prefix>http://example.com/cgi-bin/proxy.pl?url=</direct-url-prefix>

</config>

Note: The <metasearch-username> and <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.

<?xml version="1.0" encoding="UTF-8"?>
<!-- -->
<!-- Example database categories file -->
<!-- -->
<config>
  <categories>
    <!-- -->
    <!-- -->
    <!-- Search categories follow. -->
    <!-- -->
    <!-- "id" specifies a unique value used internally by the Citations -->
    <!-- Helper to identify the category.  "name" provides the text shown -->
    <!-- in the search categories pull-down menu. -->
    <!-- -->
    <!-- Databases marked as "recommended" are pre-selected at search --->
    <!-- time.  Each category needs at least one "recommended" database. -->
    <!-- -->
    <!-- General interest -->
    <!-- -->
    <category id="4" name="General">
      <category_databases>
        <category_database recommended="recommended">
          <id>EAP</id>
        </category_database>
        <category_database>
          <id>FWQ</id>
        </category_database>
        <category_database recommended="recommended">
          <id>JST</id>
        </category_database>
      </category_databases>
    </category>
    <!-- -->
    <!-- History -->
    <!-- -->
    <category id="3" name="History">
      <category_databases>
        <category_database recommended="recommended">
          <id>BIW</id>
        </category_database>
        <category_database>
          <id>CBE</id>
        </category_database>
      </category_databases>
    </category>
    <!-- -->
    <!-- Language and Literature -->
    <!-- -->
    <category id="2" name="Language and Literature">
      <category_databases>
        <category_database recommended="recommended">
          <id>CBS</id>
        </category_database>
        <category_database>
          <id>ILR</id>
        </category_database>
      </category_databases>
    </category>
    <!-- -->
    <!-- Quick Search -->
    <!-- -->
    <!-- This is the default search category; it is pre-selected at search -->
    <!-- time.  Note that one search category must be marked as "default". -->
    <!-- -->
    <category default="default" id="1" name="Quick Search">
      <category_databases>
        <category_database recommended="recommended">
          <id>EAP</id>
        </category_database>
        <category_database recommended="recommended">
          <id>JST</id>
        </category_database>
      </category_databases>
    </category>
    <!-- -->
    <!-- Science -->
    <!-- -->
    <category id="6" name="Science">
      <category_databases>
        <category_database recommended="recommended">
          <id>DOI</id>
        </category_database>
        <category_database recommended="recommended">
          <id>FDB</id>
        </category_database>
      </category_databases>
    </category>
  </categories>
  <!-- -->
  <!-- Individual database definitions follow. -->
  <!-- -->
  <!-- "id" is the database name used internally by your metasearch -->
  <!-- engine. Each database referenced in a search category (above) must -->
  <!-- be defined here. -->
  <!-- -->
  <!-- "name" provides the database name shown to the user at runtime. -->
  <!-- -->
  <databases>
    <database id="DOI" name="PsycINFO">
      <database_description>PsycINFO descriptive text</database_description>
      <database_group>all</database_group>
    </database>
    <database id="JST" name="JSTOR">
      <database_description>JSTOR descriptive text</database_description>
      <database_group>all</database_group>
    </database>
    <database id="EGQ" name="Web of Science">
      <database_description>Web of Science descriptive text</database_description>
      <database_group>all</database_group>
    </database>
    <database id="ILR" name="Literature Resource Center">
      <database_description>Literature Resource Center descriptive text</database_description>
      <database_group>all</database_group>
    </database>
    <database id="PAG" name="ABI/INFORM Global">
      <database_description>ABI/INFORM Global descriptive text</database_description>
      <database_group>all</database_group>
    </database>
    <database id="BIW" name="British and Irish Women's Letters and Diaries">
      <database_description>British and Irish Women's Letters and Diaries descriptive text</database_description>
      <database_group>all</database_group>
    </database>
    <database id="LXU" name="LexisNexis Academic">
      <database_description>LexisNexis Academic descriptive text</database_description>
      <database_group>all</database_group>
    </database>
    <database id="EAP" name="Academic Search Premier">
      <database_description>Academic Search Premier descriptive text</database_description>
      <database_group>all</database_group>
    </database>
    <database id="CBS" name="Annual Bibliography of English Language and Literature">
      <database_description>Annual Bibliography of English Language and Literature descriptive text</database_description>
      <database_group>all</database_group>
    </database>
    <database id="FDB" name="ScienceDirect Journals">
      <database_description>ScienceDirect Journals descriptive text</database_description>
      <database_group>all</database_group>
    </database>
    <database id="IVP" name="Investext Plus">
      <database_description>Investext Plus descriptive text</database_description>
      <database_group>all</database_group>
    </database>
    <database id="RCI" name="Columbia International Affairs Online">
      <database_description>Columbia International Affairs Online descriptive text</database_description>
      <database_group>all</database_group>
    </database>
    <database id="CBE" name="Historical Abstracts">
      <database_description>Historical Abstracts descriptive text</database_description>
      <database_group>all</database_group>
    </database>
  </databases>
</config>


Notes:

     <category default="default" id="100" name="My Default Search Category">

    <category_database recommended="recommended">

     <database_group>all</database_group>