Child pages
  • 2.4 Dynamic Configuration
Skip to end of metadata
Go to start of metadata

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

< back to Configuration Instructions

Dynamic Configuration allows you to provide various authorization rules for different groups of Citations Helper users. This configuration method requires modifications to the default SiteOsidConfiguration API implementation, org.sakaiproject.citation.impl.SampleSiteOsidConfiguration.

Table of Contents

1 SiteOsidConfiguration API Interface

The org.sakaiproject.citation.api.SiteOsidConfiguration interface defines several methods that allow the Citations Helper to use different sets of configuration information, based on the current user's context - campus and course affiliations, guest status, etc.

For example, at my institution users affiliated with West Campus use Sirsi SingleSearch, and users affiliated with East Campus use Ex Libris MetaLib. To handle this there will need to be two sets of configuration information, one for SingleSearch and one for MetaLib, as well as a mechanism to determine which configuration to use for a given user. That mechanism is a site-specific implementation of the SiteOsidConfiguration API interface. Different sets of configuration information are maintained in separate XML files, and the SiteOsidConfiguration implementation selects the appropriate configuration files dynamically, when the Citations Helper is invoked.

1.1 SampleSiteOsidConfiguration Default Implementation

The org.sakaiproject.citation.impl.SampleSiteOsidConfiguration class is the default SiteOsidConfiguration API implementation used by the Citations Helper.

This class makes three decisions:

  1. Which Sakai properties need to be overridden for this user?
    • The Java code returns a path to an XML file that describes the parameter values to override. Return null to use the file specified by the following property:
      • siteConfigXml@org.sakaiproject.citation.api.ConfigurationService=<XML file location>
        • The default value for this property is <sakai.home>/org.sakaiproject.citation/configuration.xml
    • XML configuration files are discussed below.
    • See getConfigurationXml() in SampleSiteOsidConfiguration.
  2. Which databases are available to this user?
    • The Java code returns the path to an XML file that describes the database hierarchy to the Citations Helper. The Search Categories & Databases XML page has documentation on how to build this XML file. Return null to use the file specified by the following property:
      • databaseXml@org.sakaiproject.citation.api.ConfigurationService=<XML file location>
        • The default value for this property is <sakai.home>/org.sakaiproject.citation/categories.xml
    • See getDatabaseHierarchyXml() in SampleSiteOsidConfiguration.
  3. What groups (if any) does this user belong to?
    • Groups can come into play when the Citation Helper decides which portions of the database hierarchy are available to the current user. In the Search Categories & Databases XML documentation, you will see that each defined database can have associated database-groups.
    • See getGroupIds() in SampleSiteOsidConfiguration.

It is probably easiest to update SampleSiteOsidConfiguration with any changes necessary to address the needs at your site. Your updated code can be compiled and deployed using the citations tree build procedure.

If you prefer to build a separate class in another location, you can configure the Citations Helper to use this new class by setting the following Sakai property:

  • osidConfig@org.sakaiproject.citation.api.ConfigurationService=<full class name>
    • The default value for this property is org.sakaiproject.citation.impl.SampleSiteOsidConfiguration

1.2 XML Configuration Files

XML configuration files allow you to provide configuration information for different groups of users. The format of this XML file is very straightforward, simply setting the values of various properties. All of the properties are also Sakai properties that can be set through the file and that you may have already seen elsewhere in the documentation. Properties set in XML configuration files override those that are set through If you want to use certain values from and override others, only include the properties you would like to override in the XML configuration file.

The following is a fully populated XML configuration document:

<?xml version="1.0" encoding="utf-8"?>


  <!-- Metasearch engine parameters (URL, username and password) -->


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


  <!-- Google Scholar URL and Sakai server -->


  <!-- OpenUrl Resolver -->
  <!--    Use your local resolver URL (if you're running a resolver) -->
  <!-- (if you've registered) -->



Note: Property names in the XML above are not syntactically the same as the property names used for See the Configuration Properties page for a listing of all properties used in You will find the property names to be the same, just not written in the same way, as the XML document above.

Note: If there is a conflict between a static and a dynamically set configuration parameter, the dynamic value takes precedence.

< back to Configuration Instructions

  • No labels