Citations Dynamic Configuration Overview
Dynamic Configuration allows you to select an appropriate Citations configuration for each individual user – this is done on-the-fly, at runtime. The configuration is chosen based on user characteristics that reflect the needs of your institution. This might include campus affiliation, guest status, etc.
A custom Java implementation of the
SiteOsidConfiguration API is required to set up a Dynamic Configuration.
A simple scenario that suggests a dynamic configuration would be appropriate:
At my institution, users affiliated with West Campus use Sirsi SingleSearch, and users affiliated with East Campus use Ex Libris MetaLib.
To handle the example scenario, we'll need two sets of XML configuration files, one set for SingleSearch and another set for MetaLib.
We'll also need a site-specific implementation of the
SiteOsidConfiguration API interface. Our custom
SiteOsidConfiguration implementation will select the appropriate configuration files at runtime.
The Citations code provides a Java interface that defines methods used by the Citations Helper to find appropriate configuration information for a given user. See:
SiteOsidConfiguration implementation selects appropriate XML configuration files for the current user. The selction is typically based on various user attributes: campus and course affiliations, guest status, etc. – basically, whatever attributes make sense for your institution.
SiteOsidConfiguration API implementation provided with the Citations Helper is available here:
This class makes three basic decisions:
- Which XML configuration file is appropriate for this user?
The Java code returns the name of XML file that describes the proper configuration. See
- Which databases are available to this user?
The Java code returns the name of an XML file that describes the database hierarchy. See
- What groups (if any) does this user belong to?
Groups allow the Citation Helper to decide 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.
SampleSiteOsidConfigurationfor a simple implementation.
Your custom implementation of the
SiteOsidConfiguration API needs to make the same three decisions outlined above.
It may be easiest to modify the default implementation,
SampleSiteOsidConfiguration.java, with any changes required to address the needs at your site. Your updated code can be compiled and deployed using the normal Citations 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:
The default value for this property is
To establish a dynamic configuration, changes are made to
sakai.properties. In addition, you may need to create multiple sets of XML configuration and search category files.
In our example scenario, we'll need to provide the names of our configuration and search categories files in sakai.properties. One set is for East Campus, the other is for West Campus.
XML Configuration Files
For the example scenario, each campus requires both a configuration file (
EAST-config.xml, WEST-config.xml) and a database categories file (
EAST-categories.xml, WEST-categories.xml). These files should be located in the
Resources area of the
Citations Admin site.
When setting up an XML configuration file, it's probably easiest to copy the sample configuration file, changing values to reflect your requirements.
You may also want to review the editing overview for Citations configuration files.
Note: The Java source code linked to from this page is in Sakai trunk. Be sure to review the code included with your Sakai release when making changes.