Sakai 2.4.0 is not the most current release Sakai 2.4.1 has been released with primarily additional security fixes. The Sakai 2.4.x maintenance branch also has these security fixes as well as other minor bug fixes. We recommend using the post-2.4 Citations Helper branch along with either Sakai 2.4.1 or Sakai 2.4.x. For post-2.4 Citations Helper configuration instructions, please see the post-2.4 Configuration Instructions page. (The post-2.4 Citations Helper will work with Sakai 2.4.0, but we do not recommend it.)

Table of Contents 1 Setting Citations Helper Properties 2 Enabling the Citations Helper 3 Enabling Citations Helper Features 3.1 Create Custom Citations 3.2 Configure your OpenURL Resolver 3.3 Import Citations from Google Scholar 3.4 Search Library Resources 4 Starting Sakai & Verifying

1 Setting Citations Helper Properties

All referenced Sakai properties are defined in the sakai-citations-pack components.xml file (<sakai_src>/citations/citations-impl/pack/src/webapp/WEB-INF/components.xml). You can modify this file to change property values, but it is recommended to use sakai.properties instead.

Sakai properties can be set anywhere in your sakai.properties file. You do not need to set properties if you will use their default value. For a listing of all Citations Helper configuration properties and their default values, please see the Configuration Properties page.

If you do not have a sakai.properties file, you can create one in a folder named "sakai" in your Tomcat instance's root directory (i.e. /opt/apache-tomcat-5.5.23/sakai/sakai.properties).

2 Enabling the Citations Helper

In Sakai 2.4, the Citations Helper is disabled by default. There are two Sakai properties that can be used to control whether or not the Citations Helper is enabled and how visible it is throughout your Sakai instance:

• citationsEnabledByDefault@org.sakaiproject.citation.api.ConfigurationService=
  • true - enables the Citations Helper across your entire Sakai instance by default. This means all users, with the proper permissions, will be able to add, revise and remove Citation Lists within the Resources of all sites. Each site's Resources tool will, however, have the option to disable Citation Lists for that particular site. This can be done by any user with administrative rights in the 'Options' section of the Resources tool.
  • false - disables the Citations Helper across your entire Sakai instance by default. This is the default value for this property. It is still possible to enable the Citations Helper on a site by site basis - please see the following allowSiteBySiteOverride property.
• allowSiteBySiteOverride@org.sakaiproject.citation.api.ConfigurationService=
  • true - allows individual sites to turn on the ability to work with Citation Lists within their Resources tool. Enabling Citation Lists can be done by any user with administrative rights in the 'Options' section of the Resources tool. This functionality is really only useful if citationsEnabledByDefault is set to false.
  • false - has no effect. This is the default value for this property.

3 Enabling Citations Helper Features

3.1 Create Custom Citations

The ability to create custom citations by entering form data comes with the Citations Helper. If the Citations Helper is enabled within a site, users will always have at least the ability to create custom citations.

3.2 Configure your OpenURL Resolver

If you use an OpenURL resolver at your institution, you can configure the Citations Helper to use it by setting one Sakai property:

• openUrlResolverAddress@org.sakaiproject.citation.api.ConfigurationService=<base URL of OpenURL resolver>
  • The default value for this property is:

    http://worldcatlibraries.org/registry/gateway

    This is a freely available service offered by WorldCat that determines if the user has access to any registered OpenURL resolvers based on the user's IP address.

3.3 Import Citations from Google Scholar

Enabling the Google Scholar import feature is controlled by the following Sakai property:

• googleSearchEnabled@org.sakaiproject.citation.api.ConfigurationService=
  • true - enables the ability to import citations from Google Scholar.
  • false - disables the ability to import citations from Google Scholar. This is the default value for this property.

There is a simple registration process that you need to go through in addition to setting the above property to true. Google Scholar presents a link within its search results labeled, "Import into <your Sakai instance name>." Your Sakai instance name needs to be registered along with a unique id, your Sakai server key, to identify your Sakai instance (usually, the Sakai server key is your Sakai instance's base URL - i.e. coursemanagement.university.edu).

For Sakai 2.4, this registration process is not yet automated. Please contact the Sakaibrary admin group to register your Sakai instance for use with Google Scholar. If you would like to experiment with the Google Scholar import feature before registering, please see the note below.

After registering, you will need to set your Sakai server key using the following Sakai property:

• sakaiServerKey@org.sakaiproject.citation.api.ConfigurationService=<your Sakai server key>
  • there is no default value for this property (the property is null by default).

Note: Default Google Scholar Import Label If you would like to experiment with Google Scholar import before registering, you can do so by setting the sakaiServerKey property to default. This will allow Google Scholar import to work properly, though the link within Google Scholar search results will be labeled "Import into Sakai" instead of "Import into <your Sakai instance name>".

3.4 Search Library Resources

For Sakai 2.4, the Citations Helper supports the SIRSI SingleSearch and Ex Libris MetaLib metasearch engines.

Note: If you do not use a metasearch engine, you can still enable the Citations Helper and take advantage of the Custom Citations and Google Scholar Import features.

Enabling the Search Library Resources feature is controlled by the following Sakai property:

• librarySearchEnabled@org.sakaiproject.citation.api.ConfigurationService=
  • true - enables the ability to search library resources.
  • false - disables the ability to search library resources. This is the default value for this property.

Searching library resources means configuring the Citations Helper to work with one or more metasearch engines. Metasearch engine XML gateway access information, search categories and databases, and user authorization cover the major configuration areas.

There are two ways to set configuration values in the Citations Helper: statically or dynamically. Static configuration is easier, but less flexible, than dynamic configuration.

For both static and dynamic configurations, an implementation of the org.sakaiproject.citation.api.SiteOsidConfiguration API is required for Citations Helper to work properly. A complete (if simple) implementation is available for your use. Please see org.sakaiproject.citation.impl.SampleSiteOsidConfiguration. This implementation is used by default.

Depending on your needs, you may be able to define all configuration statically and use the default SiteOsidConfiguration API implementation.

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, please continue with static configuration.

If you need finer-grained control over which groups of users have access to which search categories and databases, or, if you need to use multiple metasearch engines, please continue with dynamic configuration.

4 Starting Sakai & Verifying

Once the required Sakai properties are set in your sakai.properties file and necessary XML files are created and placed in the proper location, you should be able to start Tomcat normally.

Once Sakai is started and you navigate to a worksite with the Citations Helper enabled, you should see the following (your skin may vary):

Screenshot 1: Ability to add a Citation List in the Resources Tool

Screenshot 2: Depending on which features you have enabled, you should see all or a subset of these options when choosing to add a Citation List