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:

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

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.

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:

• adminSiteName@org.sakaiproject.citation.api.ConfigurationService=citationsAdmin
• configFolder@org.sakaiproject.citation.api.ConfigurationService=config

You'll also need to specify one or two configuration files:

• configXmlCache@org.sakaiproject.citation.api.ConfigurationService=config.xml
• databaseXmlCache@org.sakaiproject.citation.api.ConfigurationService=categories.xml

Notes:

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

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.

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

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

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:

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:

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

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:

• 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:

    http://metasearch.university.edu/web2/servlet/MuseWeb2

• 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:

    http://metasearch.university.edu/X

• For 360 Search, the XML gateway URL is your Serials Solutions ID, followed by the Serials Solutions gateway domain and path. For example:

    http://YOUR-ID.cs.xml.serialssolutions.com/sru

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:

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

• 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

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

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.

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:

• 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:

    <category_database recommended="recommended">

• 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:

     <database_group>all</database_group>

• For Ex Libris Metalib sites: Metalib supports three types of databases, shown below.

  Type	Description
  "Search and Retrieve"	Returns search results
  "Search and Link"	Returns a count of hits available and a vendor link
  "Link To"	Returns a link to the database (cannot be searched)

  Only "Search and Retrieve" databases work well with the Citations Helper; typically, only these are added to the XML configuration file.