ARCHIVED: In Sakai, how can I set up the help tool to check for the latest versions of help documents?

You can configure the Sakai help tool in Sakai to query the Indiana University Knowledge Base to make sure you have the latest version of your help documentation. Using this system, the help tool checks how long it has been since a requested document was retrieved from the IU Knowledge Base. If it has been more than two hours the tool re-caches a fresh version of the doc before displaying it.

In order to configure your help tool to do this, you first need to request a Knowledge Base web services account by sending email to kbmisc@indiana.edu. State that you are running Sakai and want to begin refreshing your documentation from the KB. You will receive a username and password that will allow the Sakai help tool to connect to the Knowledge Base web services interface.

Configuring the Sakai help tool to contact the IU Knowledge Base

1. You will need to provide a special help registration file called help.xml. This file needs to be network accessible from the Sakai installation. The file will tell the help tool how to build the table of contents pane and what Knowledge Base documents correspond to each resource. Here is an example of the structure of the help.xml file:

     <!-- Announcements -->
     <category name="Announcements">
       <resource name="Announcements Overview" docId="apkh" defaultForTool="sakai.announcements"/>
       <resource name="Post Announcement" docId="arbw"/>
     </category>       

   Each resource element names a help document. The name attribute provides the title that will be displayed for the document and the docId attribute gives the corresponding Knowledge Base document id. The optional defaultForTool attribute is used to indicate documents that should be opened when clicking the ? button in a tool.

2. You can access an example of a help.xml file the Indiana University Knowledge Base team created to work with the IU installation of Sakai here:

     https://oncoursehelp.iu.edu/help.xml

3. You need to put some configuration lines in a file called sakai.properties in the /tomcat5.x/sakai directory of your Sakai installation. If this file doesn't exist, you will need to create it. The lines you need to add are as follows:

     help.location=http://url.pointing.to/help.xml
     organization@org.sakaiproject.api.app.help.RestConfiguration=REST
     restCredentials@org.sakaiproject.api.app.help.RestConfiguration=user:pass
     restUrl@org.sakaiproject.api.app.help.RestConfiguration=http://remote.kb.iu.edu/REST/v0.2
     restDomain@org.sakaiproject.api.app.help.RestConfiguration=sakai21

   • On the help.location line, replace http://url.pointing.to/help.xml with the url at which the help.xml file can be retrieved.
   • On the restCredentials line, replace user and pass with the username and password you received from the KB team.