Guide to eLMS Web Services

eLMS Courseware Web Services

Guide for Flash, Javascript, and Java Developers

VaNTH ERC for Bioengineering Educational Technologies

Institute for Software Integrated Systems

Vanderbilt University

The eLMS delivery platform supports interoperability for interactive content embedded within eLMS courseware by means of web services. The purpose of this guide is to describe the available web services and how they can be used from Flash (MX or MX 2004), Javascript, and Java. It also discusses the obligations for embedded interactive content to coordinate with the platform's courseware delivery services and delivery interface.

eLMS web services are currently invoked using the XML-RPC protocol. To support the use of the web services, eLMS developers have created a set of scripts (Actionscript and Javascript) and wrapper classes (Java applets and servlets). The purpose of these facilities is to hide as much implementation detail as possible so that the web services can be used more conveniently from these technologies.

1. Overview

All eLMS courseware is created using the Courseware Authoring and Packaging Environment (CAPE). A CAPE-authored courseware can define arbitrary sets of data and functions called ConditionSets that can be accessed at delivery time via web services. Data within ConditionSets can be read and written and CAPE-authored functions can be executed. CAPE ConditionSets provide access control specifications that grant or deny web services the ability to read or write data or execute the functions they contain. Additionally, individual conditions can specify more restrictive access control than their containing ConditionSet.

ConditionSets are a very general facility that can be used for a number of purposes. Some example uses of ConditionSets are to

provide initial conditions for an embedded interactive content
represent a bi-directional interface, as a contract between an embedded interactive content and CAPE-authored content
create a set of server-side content-specific services that are sensitive to the current state of the courseware delivery
share information between multiple invocations of the same interactive content, say in some iterative activity
save the user's state so that an activity can be continued during a future session
interchange information among a sequence of interactive content elements.

Not surprisingly, the kinds of conditions in ConditionSets map directly to the kinds of data that can be marshaled with XML-RPC. Developers should understand the mapping of XML-RPC data types to programming language objects and types:

XML-RPC	Programming Languages			CAPE ConditionSets
XML-RPC	Java	ECMAscript (Actionscript and Javascript)	Python	CAPE ConditionSets
<i4> or <int>	java.lang.Integer	Number	int	Integer
<boolean>	java.lang.Boolean	Boolean	bool	Boolean
<string>	java.lang.String	String	str	String
<double>	java.lang.Double	Number	float	Float
<dateTime.iso8601>	java.util.Date	Date	datetime.datetime	DateTime
<struct>	java.util.Hashtable	Object	dict	Struct
<array>	java.util.Vector	Array	list	Array
<base64>	byte[ ]	String	xmlrpclib.Binary	Base64

1.1 Outcomes and Review

In addition to support for accessing ConditionSets, eLMS web services are used to persist outcomes from a learner's use of embedded interactive content. Outcomes are indelible state; that is, they can only be written once. It is an obligation for an embedded interactive content to set one or more outcomes prior to completing its operation.

The eLMS delivery interface supports review functionality. It is an obligation for embedded interactive content to implement a review mode. When content is being reviewed, the learner should be able to examine what was done earlier, but recognize that s/he is not able to alter what was done. (Note that CAPE sequencing models can be used to allow the learner to return to an interactive content element and to continue some activity that it supports. This can be done by persisting the earlier state of the activity in a ConditionSet and loading that state at subsequent invocations of the interactive content. However, each delivery of an embedded interactive content has its own unique outcomes.)

An embedded interactive content can detect that it is being reviewed by attempting to retrieve its outcomes. If there are outcomes, then the interactive content is being reviewed. eLMS could have implemented a web service specifically for checking the review state. But the normal action if the content is being reviewed is to retrieve its outcomes, so it made sense to make retrieving the outcomes the check. For Flash, Javascript, and Java applets, this check is automatically made during initialization and the attributes isReviewing and outcomes of the interface object are set accordingly. However, this approach is inappropriate for Java servlets, since their operation is typically stateless, or else how they choose to manage state is an application-specific concern. Servlets might check the review state during their initial request from a particular client, and then use a cookie or some other approach to manage this state on subsequent requests from the client. Since eLMS developers saw no general strategy that would fit all cases for servlets, the eLMSservlet wrapper class leaves the issue of how to satisfy the "review mode" obligation up to the application designer.

1.2 Modeling Embedded Interactive Content in CAPE

Elements of CAPE courseware models that can be delivered to learners use Resources to define what is delivered to the browser. In the case of embedded interactive content, the containing element will most likely be a Granule—a sequence-able CAPE modeling element used to deliver content (passive or interactive) to the learner. Granules have one resource that is marked as the top-level resource. This resource is delivered to the browser when the granule is selected for delivery, and any other resources defined by the granule are used to support this top-level resource. Note that CAPE provides extremely flexible means of sharing resources among granules and with other modeling elements that utilize resources. When the top-level resource of a granule is interactive, the Interactive attribute of the granule should be set to True. This cues the eLMS delivery interface to suspend until the interactive content is completed. It is an obligation for embedded interactive content to signal completion by calling the 'completeInteraction' method provided by the scripts and wrapper classes.

1.3 Considerations for the eLMS Delivery Interface

When embedded interactive content is delivered to the browser it is delivered within the eLMS delivery interface. Specifically, it is delivered into a frame that is a part of the eLMS delivery interface. Interactive content shares the an obligation with all other content employed in CAPE learning designs not to break out of the frame element into which it is loaded. To do so would disrupt the delivery interface. Flash content should use the windowless rendering mode; i.e., wmode = 'transparent'.

2. The Web Services

eLMS provides seven web services to embedded interactive content: four for reading and writing data from ConditionSets, one for executing functions from ConditionSets, and two for reading and writing Outcomes.

2.1 ConditionSet Services

getCondition

Description:

Retrieves the value of a single readable condition from a ConditionSet.

Parameters:

Set        (<string>) Name of the ConditionSet that contains the condition to retrieve

Name    (<string>) Name of the condition to retrieve

Return: (any XML-RPC data type) Value of the condition.

Exceptions: ConditionSet or condition not found. Access violations.

Java (eLMSApplet) example:

String resp;
try {
    resp = getCondition("Conds", "Input");
} catch (eLMSException el) {/* handle me */}

getConditions

Description:

Retrieves the values of all readable conditions from a ConditionSet.

Parameters:

Set        (<string>) Name of the ConditionSet

Return: (<struct>) Dictionary of key, value pairs.

Exceptions: ConditionSet not found. Access violations.

Java (eLMSApplet) example:

Hashtable resp;
try {
    resp = getConditions("Conds");
} catch (eLMSException el) {/* handle me */}

Flash MX 2004 example:

var eLMSws:eLMS.CoursewareWebServices = new eLMS.CoursewareWebServices();

...

function myCallback(data) {

    var someCond:String = data["someCond"];

}

eLMS.getConditions("Conds", myCallback, errCallback);

setCondition

Description:

Sets the value of a single writable condition in a ConditionSet.

Parameters:

Set        (<string>) Name of the ConditionSet that contains the condition to retrieve

Name    (<string>) Name of the condition to retrieve

Value    (any XML-RPC data type) New value of the condition

Return: <boolean> True.

Exceptions:

ConditionSet or condition not found. Access violations.

Name not valid CAPE identifier. ([A-Za-z]*[A-Za-z0-9_]*)

Java (eLMSApplet) example:

try {
    setCondition("Conds", "Output", "Some new value");
} catch (eLMSException el) {/* handle me */}

setConditions

Description:

Set the value of multiple writable conditions in a ConditionSet.

Parameters:

Set        (<string>) Name of the ConditionSet

Values   (<struct>) Dictionary providing values for the conditions named by keys

Return: <boolean> True.

Exceptions:

ConditionSet not found. Access violations. Values not <struct>.

Keys not valid CAPE identifier. ([A-Za-z]*[A-Za-z0-9_]*)

Java (eLMSApplet) example:

Hashtable values = new Hashtable();

values.put("C1", "My new value");

values.put('C2', new Integer(1));
try {
    setConditions("Conds", values);
} catch (eLMSException el) {/* handle me */}

Flash MX example:

var eLMS = new eLMS_WebServicesClass();

...

function myErrorCallback(fault) {

    var code = fault.Code;

    var desc = fault.Description;

    // handle failure

}

eLMS.setConditions("Conds", {C1 : "My new value", C2 : 1}, undefined, myErrorCallback);

executeFunction

Description:

Execute a function in a ConditionSet.

Parameters:

Set        (<string>) Name of the ConditionSet

Name    (<string>) Name of the function

Args      (<array>) Argument list

Return: (any XML-RPC data type) Value returned by function.

Exceptions: ConditionSet or function not found. Access violations.

Java (eLMSApplet) example:

Hashtable resp = null;

Vector args = new Vector();

args.add("Arg1");

args.add("Arg2");
try {
    resp = executeFunction("Conds", "myFunc", args);
} catch (eLMSException el) {/* handle me */}

Flash MX example:

var eLMS = new eLMS_WebServicesClass();

...

eLMS.executeFunction("Conds", "myFunc", ["Arg1", "Arg2"], myCallback);

2.2 Outcomes Services

getOutcomes

Description:

Retrieves the outcomes set when the embedded interactive content was originally delivered.

Notes: It is unnecessary to call this service directly for applets, Flash, and Javascript. This is done as part of the interface object's constructor. The member variables (attributes) isReviewing and outcomes indicate whether outcomes were retrieved and contain them, respectively.
When the web service interface is operating asynchronously, then the initialization callback is the first available time at which these members can be reliably checked.

Parameters:

None

Return: (<struct>) Dictionary of key, value pairs.

Exceptions: None

setOutcomes

Description:

Sets the outcomes from a learner's use of the embedded interactive content.

Parameters:

Values (<struct>) Dictionary providing values for the outcomes named by keys

Return: <boolean> True.

Exceptions: Values not <struct>. Keys not valid CAPE identifier. ([A-Za-z]*[A-Za-z0-9_]*)

Java eLMSApplet Example:

Hashtable values = new Hashtable();

values.put("C1", "My new value",

values.put('C2', new Integer(1));
try {
setOutcomes(values);
} catch (eLMSException el) {/* handle me */}

completeInteraction();

Javascript Example:

var eLMS = new eLMS_WebServicesClass();

...

eLMS.setOutcomes({C1 : "My new value", C2 : 1});

eLMS.completeInteraction();

3. Language-Specific Support

Beginning with CAPE 2.3, the language-specific support packages are moved into the CAPE Repository. The documentation for these packages is included in the "eLMS Web Services" MiniProject in the repository. See the Description of the MiniProject for details.