Page Comparison

Citations Dynamic Configuration Overview

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

Example Scenario

An A simple scenario that suggests the use of 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.

API Interface

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:

    org.sakaiproject.citation.api.SiteOsidConfigurationTypically, a

Implementation

The SiteOsidConfiguration implementation will select a set of selects appropriate XML configuration files for the current user. The selction is typically based on a user's context – various user attributes: campus and course affiliations, guest status, etc. To handle our example scenario, we'll need two sets of configuration information, one for SingleSearch and one for MetaLib, as well as a site-specific implementation of the SiteOsidConfiguration API interface. The SiteOsidConfiguration implementation selects the appropriate configuration files at runtime, when the Citations Helper is invoked– basically, whatever attributes make sense for your institution.

Default Implementation

The default SiteOsidConfiguration API implementation provided with the Citations Helper is available here:

    org.sakaiproject.citation.impl.SampleSiteOsidConfiguration

1. Which Sakai properties need to be overridden XML configuration file is appropriate for this user?
   
   The Java code returns a path to an the name of XML file that describes the parameter values to override. Return null to use the file specified by the following property:
   • configXmlCache@org.sakaiproject.citation.api.ConfigurationService=<XML file>
     • The default value for this property is config.xml
2. XML configuration files are discussed below.
proper configuration. See getConfigurationXml() in SampleSiteOsidConfiguration.


3. Which databases are available to this user?
   
   The Java code returns the path to name of an XML file that describes the database hierarchy to the Citations Helper. Return null to use the file specified by the following property:
   • databaseXmlCache@org.sakaiproject.citation.api.ConfigurationService=<XML file>
     • The default value for this property is categories.xml
4. The Search Categories & Databases XML page has documentation on how to build this XML file.
See getDatabaseHierarchyXml() in SampleSiteOsidConfiguration.


5. What groups (if any) does this user belong to?
   
   Groups can come into play when allow the Citation Helper decides 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.
   
   See getGroupIds() in SampleSiteOsidConfiguration for a simple implementation.

Custom Implementation

Your custom implementation of the SiteOsidConfiguration API needs to make the same three decisions outlined above.

It is probably may be easiest to update SampleSiteOsidConfiguration modify the default implementation, SampleSiteOsidConfiguration.java, with any changes necessary required to address the needs at your site. Your updated code can be compiled and deployed using the citations tree 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:

...

  osidConfig@org.sakaiproject.citation.api.ConfigurationService=<full-class-name>

The default value for this property is org.sakaiproject.citation.impl.SampleSiteOsidConfiguration

...

Anchorxmlxml

...

Configuration

...

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 sakai.properties file and that you may have already seen elsewhere in the documentation. Properties set in XML configuration files override those that are set through sakai.properties. If you want to use certain values from sakai.properties and override others, only include the properties you would like to override in the XML configuration file.

The following is sample XML configuration file:

...

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

<config>

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

  <metasearch-baseurl>http://my-institution.edu/web2/servlet/MuseWeb2</metasearch-baseurl>
  <metasearch-username>my-username</metasearch-username>
  <metasearch-password>my-password</metasearch-password>

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

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

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

  <google-baseurl>http://scholar.google.com/schhp</google-baseurl>
  <sakai-serverkey>my-institution.sakai-instance.edu</sakai-serverkey>

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

  <openurl-resolveraddress>http://my-institution.edu/openurl-resolver</openurl-resolveraddress>

</config>

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

...

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.

Anchor
sakaiproperties sakaiproperties

Property Values

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.

 
# 
# Cached configuration files (one for each campus) 
# 
configXmlCache@org.sakaiproject.citation.api.ConfigurationService=EAST-config.xml,WEST-config.xml 
databaseXmlCache@org.sakaiproject.citation.api.ConfigurationService=EAST-categories.xml,WEST-categories.xml 

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.

To learn more on creating a search category file, refer to the Search Categories & Databases XML document and the example XML configuration file.

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.