Sakai IMS Tool Interoperability Implementation (IMSTI)

Version 1.0

 

Anthony Whyte

Sakai Foundation

University of Michigan

arwhyte@sakaifoundation.org

 

DRAFT

 

 

I. INTRODUCTION

 

The Sakai IMSTI project is an implementation of the IMS Tools Interoperability (TI) Guidelines, version 1.0 (February 2006) [1] .  TI provides a framework for extending learning management systems to include third-party tools via web services.  Sakai IMSTI comprises a collection of published APIs, component services, data definition language (DDL) files and a JavaServer Faces (JSF) tool implementation.  IMSTI also includes a set of sample proxy tool XML deployment descriptors that can be used to test IMSTI proxy capabilities with an external application called Concept Tutor developed and maintained at the University of Wisconsin, Madison.  IMSTI leverages common Sakai services as well as the Apache AXIS web services project to define proxy tools, construct SOAP messages and make web service calls across the Internet. [2]

 

IMSTI proxy tool instances serve as facades for web applications external to the Sakai CLE.  External applications are required to implement at a minimum the TI launch service and make available a deployment package comprising an XML deployment descriptor that provides basic tool configuration information that IMSTI utilizes to communicate with target tools.  Web service description language (WSDL) files that describe both the TI launch and outcome services together with a deployment protocol XSD file are available from IMS for developers interested implementing the TI guidelines [3] .

 

This guide compliments existing documentation on installing and running the Sakai Collaboration and Learning Environment (CLE).  It assumes familiarity with downloading, building and deploying Sakai source code.  It also assumes that you have both Tomcat and your database of choice (MySQL or Oracle) properly configured.  Finally, it assumes familiarity with Sakai worksite creation/administration and roles and permissions.  If you are unfamiliar with any of these procedures please review the Sakai installation guide available at http://source.sakaiproject.org/release/ and the worksite help files included in the application before proceeding further.

 

 

II. ACQUIRING AND INSTALLING IMSTI

 

IMSTI is available from Sakai’s Subversion (SVN) code repository located at https://source.sakaiproject.org/svn/ . [4]   The latest development work and least stable code is located in /imsti/trunk; stable releases can be retrieved from the /imsti/tags folder organized by release version (e.g., /sakai_2-4-0).  Maintenance branches may be created in the /imsti/branches folder for additional work on current or previous tagged releases (e.g., /sakai_2-4-x).

 

Trunk: https://source.sakaiproject.org/svn/imsti/trunk/

 

Tags: https://source.sakaiproject.org/svn/imsti/tags/

 

Branches: https://source.sakaiproject.org/svn/imsti/branches/

 

With an SVN client installed you can check out IMSTI trunk code by issuing the following command from a terminal window:

 

svn co https://source.sakaiproject.org/svn/imsti/trunk

 

IMSTI will soon be added to the Sakai development trunk and made available as part of regular tagged Sakai Collaboration and Learning Environment (CLE) releases. [5]   Once this occurs you will no longer need to download IMSTI independently of the Sakai CLE in order to acquire it.

 

As with other Sakai projects, building and deploying IMSTI requires installation of Maven 1.0.2. [6]   Assuming that you have downloaded IMSTI to the same directory as that of the Sakai enterprise bundle (e.g. /sakai-src ), you can build and deploy it along with the rest of Sakai.  From /sakai-src issue the following maven goals from the terminal:

 

maven bld dpl

 

Subsequent builds should add a “clean” phase by issuing the command:

 

maven cln bld dpl or the shortcut maven sakai

 

Maven will build and deploy the following IMSTI artifacts to your Tomcat servlet container:

 

IMSTI APIs:

$CATALINA_HOME/shared/sakai-imsti-api.war

 

IMSTI component services:

$CATALINA_HOME/components/sakai-imsti-pack/WEB-INF/components.xml

$CATALINA_HOME/components/sakai-imsti-pack/WEB-INF/lib/sakai-imsti-impl.jar

 

IMSTI tool:

$CATALINA_HOME/webapps/sakai-imsti-tool.war

 

If Maven completes with the message BUILD SUCCESSFUL you can start Tomcat.  If the Maven build fails please review the accompanying error message before you commence troubleshooting.

 

In environments where local network policy or firewalls require use of an upstream http proxy/cache, your JVM must be configured appropriately. Otherwise, IMSTI will not be able to retrieve data from target URLs.  Make sure your JAVA_OPTS arguments include the following:

 

-DproxySet=true -DproxyHost=cache.some.domain -DproxyPort=8080

 

While testing IMSTI behind a proxy server at the University of Cape Town I found that I had to amend the above arguments slightly by adding an http prefix in order to interact with the proxy server successfully:

 

-Dhttp.proxySet=true –Dhttp.proxyHost=cache.some.domain –Dhttp.proxyPort=8080

 

 

III. CONFIGURATION PROPERTIES

 

IMSTI implements the TI outcome service and one should considering defining a set of common imsti.outcome.service properties in sakai.properties ( the main Sakai configuration file ) to simplify tool deployment and administration.  Three properties are specific to the IMSTI outcome service while a fourth, webservices.allowLogin is a general property that must be set to true in order to permit web service logins to Sakai.  The imsti.outcome.service properties include the local name of the service, the endpoint location and the name of the outcomeProfile to be received and processed (this latter value should always be set to SimpleOutcomeProfile).  A typical example of property settings is provided below.

 

# Web Services

webservices.allowlogin=true

 

# IMSTI

imsti.outcome.service.name=IMSTI Outcome Service

imsti.outcome.service.location=http://ctools.umich.edu/sakai-imsti-tool/services/TIROutcomeServiceSyncSoapPort

imsti.outcome.service.profileName=SimpleOutcomeProfile

 

 

IV.  PROXY TOOL CREATION AND ADMINISTRATION

 

IMSTI includes a set of data definition language (DDL) files that are used to create and alter the database objects it requires (e.g., tables, primary key, foreign key and other constraints).  Assuming you have set the property auto.ddl=true in your sakai.properties file IMSTI’s database objects will be generated automatically on Tomcat startup for MySQL, Oracle or HSQLDB database instances.

 

Use the worksite setup tool to add IMSTI to a new or existing worksite.  Once you have added IMSTI use the site tool to change its menu display name and/or position, if desired.  In the example below IMSTI has been added to a project site named “IMSTI Test Site” and its menu display name has been changed to “Concept Tutor” (see View I). Click the “New” link to define a new proxy tool.


View I.  Adding a New Proxy Tool

 

Creating a new proxy tool requires uploading and reading an XML document called a deployment descriptor that includes information on the following tool settings and profiles:

 

Core Settings : provides meta-data describing the external tool including name, description, version, service location, etc.

 

Contextual Settings : provides meta-data specific to the launch/delivery context including instructions describing whether or not submission of delivery context and/or user profiles are required by the external tool during the launch sequence.

 

Tool Settings : meta-data describing tool-specific settings to be provided to the external tool during the launch sequence.  Provision of a target pointer to a specific resource to be returned to the LMS in the guise or a redirect URL would be included here.

 

Security Profile : meta-data describing the security requirements, if any, required by the external tool to establish a trust relationship with the CLE/LMS during the launch sequence.  The security profile will be inserted into the SOAP message header for the launch request and outcome messages.

 

Outcome Profile : meta-data describing the type of outcome profile to be returned, if any.

 

A set of sample deployment descriptors can be found in the IMSTI tool project’s webapp/docs/deployment_descriptor directory (see also appendix I below).  Click the “Browse . . .” button and select a deployment descriptor for processing.  Then click the “Upload” button to upload the file (see View II).


View II.  Deployment Descriptor Upload

 

IMSTI’s deployment service will attempt to read the deployment descriptor, passing the meta-data to IMSTI’s data service to persist the data to the database before ceding control to IMSTI’s configuration service so that it can create and configure the proxy tool.

 

After the proxy tool deployment and configuration process is initiated IMSTI’s message service will provide on screen alerts indicating whether or not the operation was successful.  IMSTI also logs errors and other events to Tomcat’s catalina.out as well as submits user actions to Sakai’s event service.  If successful the proxy tool list page will be reloaded with edit and launch links displayed.  Assuming success, click the “Continue” button to review/edit the proxy tool configuration before initiating a launch request (see View III).


View III.  IMSTI Messaging

 

The next screen provides an opportunity to edit the proxy tool’s configuration settings (see View IV).  The IMS TI guidelines specify a number of ancillary fields that permit arbitrary information to be added to the ACCLIP, delivery context and user profiles [7] .  In the case of the delivery context ancillary the IMSTI configuration service inserts a chunk of XML that includes Sakai context, sessionId, tool placementId, IMSTI toolId, and the target resourceId.  Please do not modify this information as IMSTI utilizes it when processing any outcome messages that are returned by the external tool.

 

Click the “Save” button to update any of the Contextual setting properties (the IMSTI Message service will confirm the update with an onscreen message).  Once the contextual settings are set, click the “Continue” button to move to the next screen.


View IV.  Edit Contextual Settings


The Core Settings edit screen permits one to edit the tool profile, tool settings, launch and outcome services (see View V).  In most cases only the Sakai outcome service location URL will need to be modified in order to replace the placeholder domain with a domain name of your choosing (e.g., https://www.myschool.ac.za/ sakai-imsti-tool/services/TIROutcomeServiceSyncSoapPort ).  The service endpoints can be tested by clicking on the “Test Me” links.  Click the “Save” button to update your changes.  Then click the “Continue” button to proceed to the final screen.

 

View V.  Edit Core Settings

 

The launch screen includes a listing of required launch profiles and settings (see View VI).  If any value is incorrect click the “Back” button to return to the appropriate edit screen and correct the launch properties before returning to the launch page.  When the proxy tool is configured properly click the “Launch” button to initiate the web services launch request.

 

View VI.  Launch

 

The launch request is handled by IMSTI’s launch service.  If the launch request is successful, the external tool will issue a SOAP Message containing a launch directive comprising a redirect URL or response text string.  IMSTI’s launch service will than issue a launch response SOAP message informing the external tool of the success or failure of the launch request.

 

In the case of Concept Tutor, a redirect URL is supplied to the proxy tool and the requested Concept Tutor is loaded into an HTML <iframe>.  From this point onwards the end user interacts directly with the external application.  Concept Tutor presents the user with a tabbed interface providing study material and a quiz covering a particular concept in the biological sciences.  Review the material then click the “Check” tab and take the quiz (see Views VII-VIII).  After selecting the appropriate options, click the “Check” button to score the quiz, and then, click the “Report” button to submit the score to Sakai via a web service call from Concept Tutor to IMSTI’s outcome service.

 

View VII.  Concept Tutor “Active Site”


View VIII.  Concept Tutor “Active Site” Quiz

 

The incoming SOAP message is processed by IMSTI’s outcome service and its contents, including a score in the example above, are passed to IMSTI’s data service for insertion into the database.  IMSTI’s outcome service than issues an outcome response SOAP message to inform the external tool regarding the success or failure of the outcome reporting operation.

 

Click the “Tool List” link to return to the proxy tool list page.  Links for editing, inactivating/reactivating and launching proxy tools are provided for each deployed proxy tool (see View IX).


View IX. IMSTI Edit, Status and Launch links

 

 

V. IMSTI PERMISSIONS AND ROLES

 

IMSTI includes a set of fine-grained permissions that allow administrators to define a variety of roles based on permission aggregations. Use the realms editor to edit role permissions associated with sites that include IMSTI.  A typical “student” role for instance, might include in its permission set only imsti.read and imsti.launch and/or the imsti.role.student while a “teaching assistant” role might include both imsti.read, imsti.launch and imsti.update, the latter permitting tool edits.  Such a scenario would grant teaching assistants the right to edit existing proxy tools but deny them the right to create new proxy tools or upload replacement deployment descriptors for existing tool facades (see Views X-XI).

 

IMSTI Permissions

 

imsti.create

imsti.launch

imsti.read

imsti.update

imsti.upload

 

imsti.role.admin (create, read, launch, update and upload)

imsti.role.instructor (read, launch and update)

imsti.role.student (read, launch)


View X.  TA Role assigned imsti.read, imsti.launch and imsti.update permissions

 

View XI.  Student Role assigned imsti.read and imsti.launch permissions


Appendix I.  Sample Deployment Descriptor XML Document

 

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

<ProxyToolDeployment xmlns=http://www.imsglobal.org/xsd/imsti_ptdd_v1p0 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<DeploymentProfile>

<CoreSettings>

<ProxyTool>

<ProxyToolName>ConceptTutor</ProxyToolName>

<ProxyToolVersion>

<major>1</major>

<minor>0</minor>

</ProxyToolVersion>

<IMSTIVersion>

<major>1</major>

<minor>0</minor>

</IMSTIVersion>

<ProxyToolDescription>ConceptTutor provides just in time, just enough information for basic comprehension of a concept.

</ProxyToolDescription>

</ProxyTool>

 

<TIR>

<LaunchService>

<ServiceName>ConcepTutor launch service</ServiceName>

<ServiceLocation>http://atsosxprod.doit.wisc.edu:8080/concepttutor/services/TIRLaunchServiceSyncSoapPort</ServiceLocation>

<ServiceProfileName>MinimalOutcomeProfile</ServiceProfileName>

</LaunchService>

</TIR>

</CoreSettings>

<SupportedLaunchRoles>

<Role>Student</Role>

<Role>Instructor</Role>

</SupportedLaunchRoles>

<ContextualProfile Required="true" ContextualProfileType="SimpleUserProfile"/>

<ContextualProfile Required="true" ContextualProfileType="AcclipContextProfile"/>

<ContextualProfile Required="true”

ContextualProfileType="DeliveryContextProfile"/>

<SecurityProfile Required="true" Preference="0" SecurityProfileType="SharedSecretProfile" xmlns:dd="http://www.imsglobal.org/xsd/imsti_ptdd_v1p0" xsi:type="dd:SharedSecretSecurityProfile.Type">

<SharedSecret>D/utj51IkvfmY05yD/W6pzCCLFNqITliVbs5+X9rtqxwW4N9OXXA2IrVlbaJ/iYhwBvqRBQhtSEZ81dd0LWdlg==</SharedSecret>

<DigestedMessageElement>syncRequestHeaderInfoDType/messageIdentifier</DigestedMessageElement>

</SecurityProfile>

<OutcomeProfile Required="true" Preference="0" OutcomeProfileType="MinimalOutcomeProfile"/>

<OutcomeProfile Required="true" Preference="0" OutcomeProfileType="SimpleOutcomeProfile"/>

<ToolSettings>

<SettingsDefinition>

<documentation><p xmlns="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

A ConceptTutor requires that the launch a tool settings instance that

satisfies the schema listed in-line below.  In particular, a launch will succeed only if the resourceIdentifier resolves to a resource known to the ConceptTutor instance.  The instance contains a sample resourceIdentifier that would be overridden in any particular proxy tool instance.

</documentation>

<schema>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns="http://engage.doit.wisc.edu/schemas/ConceptTutor_v1p0"

targetNamespace="http://engage.doit.wisc.edu/schemas/ConceptTutor_v1p0">

<xsd:complexType name="resourceIdentifierType">

<xsd:sequence>

<xsd:element name="id">

<xsd:simpleType>

<xsd:restriction base="xsd:string">

<xsd:minLength value="1"/>

<xsd:maxLength value="256"/>

</xsd:restriction>

</xsd:simpleType>

</xsd:element>

<xsd:element name="instance">

<xsd:annotation>

<xsd:documentation>Setting instance to base will retrieve the resource from the Fedora repository.  Setting instance to test will by-pass the Fedora repository and deliver a test page.

</xsd:documentation>

</xsd:annotation>

<xsd:simpleType>

<xsd:restriction base="xsd:string">

<xsd:enumeration value="base"/>

<xsd:enumeration value="test"/>

</xsd:restriction>

</xsd:simpleType>

</xsd:element>

</xsd:sequence>

</xsd:complexType>

<xsd:element name="resourceIdentifier" type="resourceIdentifierType"/>

</xsd:schema>

</schema>

<instance>

<resourceIdentifier xmlns="http://engage.doit.wisc.edu/schemas/ConceptTutor_v1p0"><id>active/tutor.html</id><instance>base</instance></resourceIdentifier>

</instance>

</SettingsDefinition>

</ToolSettings>

</DeploymentProfile>

</ProxyToolDeployment>

 


[1] IMS Tools Interoperability Guidelines, version 1.0 (February 2006), http://www.imsglobal.org/ti/tiv1p0/imsti_guidev1p0.html .

[2] For more information on Apache AXIS, see http://ws.apache.org/axis/ .

[4] For more information on Subversion, see http://subversion.tigris.org/ .

[5] Sakai developer trunk is located at https://source.sakaiproject.org/svn/sakai/trunk/ .

[6] For more information on Maven, see http://maven.apache.org/ .

[7] The ACCLIP profile permits inclusion of a user’s IMS Accessibility Learner Information Package. See http://www.imsglobal.org/accessibility/acclipv1p0/imsacclip_infov1p0.html .