IMS Portable Custom Interactions Specification

IMS Candidate Final Release
Version 1.0

IPR and Distribution Notices

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

IMS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on IMS's procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Copyright © 2017 IMS Global Learning Consortium. All Rights Reserved.

Use of this specification to develop products or services is governed by the license with IMS found on the IMS website: http://www.imsglobal.org/speclicense.html.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

The limited permissions granted above are perpetual and will not be revoked by IMS or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

Public contributions, comments and questions can be posted here: https://www.imsglobal.org/forums/ims-glc-public-forums-and-resources/question-test-interoperability-public-forum.

© 2017 IMS Global Learning Consortium, Inc.
All Rights Reserved.

Trademark information: http://www.imsglobal.org/copyright.html

The IMS Logo is a trademark of the IMS Global Learning Consortium, Inc. in the United States and/or other countries.
Document Name: IMS Portable Custom Interactions
Revision: 1 June 2017

Table of Contents

1. Introduction

1.1 Scope and Context

1.2 Terminology

1.3 References

2. Portable Custom Interactions Solution

2.1 Interaction Rendering

2.2 Delivery Engine Support

2.3 Custom Interaction Support

2.4 Item XML Definition

2.5 Configuration

2.6 Lifecycle

2.7 Accessibility

2.8 Packaging

Appendix A - Base Types

Appendix B - Module Resolution Configuration Format

About this Document

List of Contributors

Revision History

1 Introduction

The IMS Global Question and Test Interoperability (QTI) specification [QTI, 16] describes an interoperable format for assessment content and results. The focus of the standard is to provide interoperability between components in an assessment system. The standard supports a myriad of item interaction types. Technology Enhanced Items (TEI) that extend beyond the defined interaction types can still be supported by the QTI specification and in the related Accessible Portable Item Protocol (APIP) specification [APIP, 12] by making use of the custom interactions feature. Interoperability between different components and platforms rendering TEIs provides a unique challenge, because the shape and functionality of these custom interactions are unknown outside of the system that originated it.

This best practice outlines a method that allows an author to define an almost unlimited variety of custom interaction types, while still keeping the item portable between different systems. This is achieved by making use of common web technologies combined with an agreement about how to communicate the results of a learner's interaction to a QTI/APIP delivery engine. By following the best practice documented here, most TEIs and assessment components can increase their value by supporting interoperability.

1.1    Scope and Context

Custom interactions are an extension point in the QTI specification, but do not provide guidelines on implementation, causing an issue of interoperability between different assessment components and platforms.

Over time and through the use of the guidance described in this document, certain interactions or TEIs will very likely be established and become standard through the IMS assessment community. Details about sharing custom interactions are provided here: http://www.imsglobal.org/assessment/interactions.html.

1.2    Terminology

1.3    References

[APIP, 12]    G.Driscoll, T.Hoffmann, W.Ostler, M.Russell, M.McKell and C.Smythe, Accessible Portable Item Protocol (APIP) v1.0 Best Practices and Implementation Guide Candidate Final Release, IMS Global, Inc., March 2012. http://www.imsglobal.org/apip/index.html

[RFC 2119]    S.Bradner, Network Working Group, Request for Comments: 2119, March 1997. http://www.ietf.org/rfc/rfc2119.txt

[QTI, 16]        C.Smythe, M.McKell, W.Kraan, IMS Question & Test Interoperability Overview v2.2.1 Final Release, IMS Global, Inc., August 2016. http://www.imsglobal.org/question/index.html

[STRICT]         © Ecma International 2016 http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf (see section 4.2.2)

2     Portable Custom Interactions Solution

The solution outlines minor adjustments to item development and delivery system to support the rendering and runtime management of custom interactions. Depending on the intended use of the solution any XML may be used, but HTML5 is preferred. This standard requires a delivery system capable of rendering HTML and executing JavaScript. In order to provide maximum accessibility of custom interactions, delivery systems are expected to support HTML5 and WAI-ARIA. At the time of this writing, HTML5 lacks a formal XML specification. Unexpected results may occur in systems not fully supporting HTML5 additions. The use of Adobe Flash, Silverlight, or other plug-in technologies may be incorporated into this solution, but are highly discouraged in order to keep interactions portable and accessible.

Portable custom interactions are a special type of QTI custom interaction. However, unlike items with conventional QTI custom interactions, items with portable custom interactions include the code that is required to run those portable custom interactions. That means that where conventional custom interactions assume tools that have been specially modified for each custom interaction type, tools that support portable custom interactions only need to implement the additional standardized interfaces outlined in this document in order to support an essentially unlimited number of interaction types.

2.1    Interaction Rendering

The rendering of custom interactions requires a communication bridge between the interaction and the delivery engine. The communication bridge provides state information, configuration, and results to be exchanged. Portable custom interactions are based on the following assumptions:

• The delivery engine supports client-side JavaScript
• The delivery engine supports HTML
• A JavaScript context object implementing the communication bridge contract is made available to the interaction through an AMD dependency.
• Any Javascript loaded as part of or to support a PCI MUST be written to run inside a strict Javascript execution context (e.g. it must expect that the delivery engine has called “use strict” before any of it’s modules are loaded) [STRICT]. It is recommended that all PCI modules also call “use strict”.

2.2 Delivery Engine Support

The delivery engine supports portable custom interactions by injecting, via AMD, an object which supports the following contract which will allow interactions to register themselves and exchange state and configuration settings with the delivery engine. It will provide this via a standard AMD definition of 'qtiCustomInteractionContext' which the portable custom interaction can require in its AMD module.

As an alternate discovery method the qtiCustomInteractionContext MUST be assigned to the window object before the PCI is loaded. If a delivery engine support composite interactions the qtiCustomInteractionContext register method may be called more than once for different PCI types and it’s getInstance method may be called multiple times to construct more than one PCI interaction in the assessmentItem.

2.3 Custom Interaction Support

Custom interactions support the delivery engine by registering a hook with the AMD injected qtiCustomInteractionContext object. The hook allows the delivery engine to construct a custom interaction instance which can return result and state information for the custom item. The following methods are required:

2.4 Item XML Definition

To enable portability and to align with the QTI specification, a child element is used to define the portable custom interaction. This child element provides type identification, template variable bindings, interaction configuration settings and the initial HTML5 markup to add to the DOM and pass to the portable custom interaction on initialization.

<?xml version="1.0" encoding="UTF-8"?>
<assessmentItem
   xmlns="http://www.imsglobal.org/xsd/imsqti_v2p2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.imsglobal.org/xsd/imsqti_v2p2 http://www.imsglobal.org/xsd/imsqti_v2p2.xsd"
   identifier="SimpleExample" title="Example" adaptive="false" timeDependent="false">
 <stylesheet href="css/graph.css" type="text/css"/>
 <responseDeclaration baseType="point" cardinality="single" identifier="RESPONSE" />
 <templateDeclaration baseType="integer" cardinality="single" identifier="X" defaultValue="1"/>
 <templateDeclaration baseType="integer" cardinality="single" identifier="Y" defaultValue="1"/>
 <itemBody>
 <customInteraction responseIdentifier="RESPONSE" id="graph1" xmlns="http://www.imsglobal.org/xsd/portableCustomInteraction_v1">
   <portableCustomInteraction customInteractionTypeIdentifier="vnd.Example.Graph" >
        <templateVariable templateIdentifier="X" />
        <templateVariable templateIdentifier="Y" />
     <properties>
       <property key="literal">0</property>
       <property key="scale">5</property>
       <property key="labelX">Average precipitation</property>
       <property key="labelY">Month</property>
     </properties>
     <modules primaryConfiguration="https://imsglobal.org/pci/1.0.15.modules.js" fallbackConfiguration="modules/config.js">
       <module id="chart"/>
       <module id="graph" primaryPath="https://example.com/content/modules/1.5/graph" fallbackPath="modules/graph"/>
      </modules>
    <markup xmlns="http://www.w3.org/1999/xhtml">
           <div id="graph1_box" class="graph" style="width:500px; height:500px;"></div>
      </markup>
    </portableCustomInteraction>
   </customInteraction>
 </itemBody>
</assessmentItem>

2.5 Configuration

Configuration of portable custom interactions may leverage QTI templateDeclaration elements and/or properties defined in the portableCustomInteraction's property elements. The configuration data is set during system initialization and passed to the PCI module via a call to getInstance.

QTI template variables may be leveraged to provide configuration data to custom interactions by template variable binding. The delivery system must read the mapping and provide configuration data before interaction initialization. QTI template variables are transcribed into JSON data by the delivery system.

The JSON data is passed into the custom interaction object on creation via the getInstance method. Refer to the “Appendix” for the JSON representation of template variables. This example item in Section 2.4 above binds two template variables (X and Y) to this interaction, so that the value of these two variables will be passed by the delivery engine into the configuration in the templateVariables property when the custom interaction object is created.

2.6 Lifecycle

The diagram here illustrates the basic lifecycle of a PCI.

Figure 2.1: PCI Lifecycle sequence diagram.

If we take the example in Section 2.4 above a typical set of lifecycle events would be:

1. The delivery engine parses the assessmentItem
2. At some point the item is launched and the delivery engine begins to render the item in a web browser
3. The delivery engine identifies that there are one or more portableCustomInteractions in the assessmentItem
4. e.g. one portableCustomInteraction element with a customInteractionTypeIdentifier of vnd.Example.Graph
5. The delivery engine process each portableCustomInteraction
6. It identifies if there is a pci:modules element and if so begins the process of ensuring any Javascript AMD modules referenced there are loaded, by:
1. ​If the modules element has a primaryConfiguration attribute it downloads the JSON configuration file from the given URL which can provide fine grained control over the resolution of the AMD modules to be loaded. The format of this configuration file is defined in Appendix B.
2. e.g. it reads the following configuration JSON:
   

{   "waitSeconds": 60,
              "paths": {
                  "jquery": "https://code.jquery.com/jquery-1.10.2",
                  "mobile": "https://code.jquery.com/mobile/1.3.0/jquery.mobile-1.3.0",
                  "chart": "https://cdnjs.com/libraries/chart.js"   }
         }

3. If it cannot download that config file it should attempt to load the config file from the URL in the fallbackConfiguration attribute, if set
4. It then processes each module element in turn. If a module resolution configuration has been set this is applied.
5. If primaryPath has been set for this module this can be used to provide the url to use when loading the module and will override the general module resolution configuration for this module. If the primaryPath location is not accessible then the fallbackPath location should be tried.
6. e.g. for the second module a primaryPath has been set so the module will be resolved as https://example.com/content/modules/1.5/chart/chart.js
7. The delivery engine should perform an AMD require operation for the module identified by the id attribute, injecting the qtiCustomInteractionContext object
8. e.g. the first module has an id of "chart" and the JSON config file has a paths config for "chart" so it will load the module from https://cdnjs.com/libraries/chart.js
9. The second module has an id of "graph" and a primaryPath override of https://example.com/content/modules/1.5/graph so it will load this module from https://example.com/content/modules/1.5/graph/graph.js
10. When loaded the custom interaction module should call register(customInteractionHook) on the injected qtiCustomInteractionContext object to set the custom interaction hook for this custom interaction
7. ​Once all of the required Javascript AMD modules have completed loading the delivery engine should copy the contents of the pci:markup element to the DOM in the browser
8. e.g. <div id="graph1_box" class="graph" style="width:500px; height:500px"></div>
9. The delivery engine extracts the pci:property keys and values and builds a Javascript object with all these values:

e.g. { "literal": "0",
       "scale": "5",
       "labelX": "Average precipitation",
       "labelY": "Month"
     }

10. The delivery engine identifies any templateVariable elements in the item and if there are any looks up the current value of those template variables and builds a Javascript object with the current values of those template variables
11. e.g. assuming the template variables have their default values: { "X": "1", "Y": "1" }
12. The delivery engine then identifies the customInteraction element parent of the portableCustomInteraction, reads the responseIdentifier attribute and looks up the current value of that response variable which it will provide via the boundTo property.
    e.g. RESPONSE=null
13. It then builds a configuration object containing the properties from step 7, the templateVariables from step 8 and the responseVariable value from step 9, the lifecycle callback functions, and the status of the interaction

	e.g. { "properties": { "literal": "0",
	       "scale": "5",
	       "labelX": "Average precipitation",
	       "labelY": "Month"  },
	       "templateVariables": { "X": { "base": { "integer": 1} },
	                              "Y", { "base": { "integer": 1} } },
	       "boundTo": { "RESPONSE": { "base": { "point": null } } },
	       "onready": this.onPCIReady.bind(this),
	       "ondone": this.onPCICompleted(this),
	       "status": "interacting"   }
	

14. It then calls getInstance on the custom interaction hook object registered  in step 5.6 above and passes the customInteractionTypeIdentifier attribute of the pci:portableCustomInteraction element and then the root element of the markup added to the DOM in step 6 and passes that along with the configuration and optionally the state in the case where the delivery engine wants to restore the interaction to a previous state (e.g. if the use is returning to an item they have previously navigated away from before finishing their work then the saved state captured before navigating away is also passed to the call).

e.g. var pciElement = this.createPCIMarkup(...);
	   var customInteractionHook = this.getPCIHook(customInteractionTypeIdentifier);
	   customInteractionHook.getInstance(customInteractionTypeIdentifier, pciElement, {
	      "properties": { 
	           "literal": "0",
	           "scale": "5",
	           "labelX": "Average precipitation",
	           "labelY": "Month"
	      },
          "templateVariables": { 
	           "X": { "base": { "integer": 1} }, 
	           "Y", { "base": { "integer": 1} }
	     },
	     "boundTo": { 
	           "RESPONSE": { "base": { "point": null } }
	     },
	    "onready": this.onPCIReady.bind(this),
	    "ondone": this.onPCICompleted(this),
	    "status": "interacting"
	 }); // No saved state being passed as this is an initial construction
	

15. The custom interaction hook object then creates a custom interaction instance object by calling getInstance in turn on the PCI instance passing the configuration details described above
16. The custom interaction instance then modifies the DOM containing the HTML copied from the pci:markup element, if required (e.g. to support customization triggered by the supplied template variables). The delivery engine may have passed a status property in the configuration which the custom interaction may also choose to use to customize the rendering of the custom interaction to suit the use case. For example the status may be "solution" where the delivery engine is requesting the custom interaction display it's model solution and the custom interaction may choose in that case to render in a readonly mode.
17. e.g. the custom interaction object will use the chart module to add a canvas element as a child of the div with id "graph1_box", render labelled axes using the labels in the configuration properties and add an initial point at the X, Y position given by the two templateVariables values
18. The custom interaction object then reads the configuration.onready callback property and calls that method, passing a representation of its current state as the argument
19. e.g. this.configuration.onready(this, this.getState());
20. The delivery engine should retain a reference to the custom interaction object
21. The user interacts with the custom interaction and the custom interaction object updates its view of the response value of the interaction.
22. e.g. user clicks on a position on the graph and the internal response variable is set to that X, Y position:
23. this.response = { "base": { "point": [ x, y ] } };
24. If the user performs an action which tells the interaction that the student's interaction is complete (e.g. requests a hint or model solution to be displayed) the custom interaction object will call the ondone callback method if set in the configuration, passing it's current view of the interaction response in the format specified in Appendix A, a representation of it's current state and can optionally pass the status (typically if the user's interaction has changed that state, e.g. by ending the interaction)
25. e.g. this.ondone(this, this.getResponse(), this.getState(), this.getStatus());
26. where this.getResponse() returns { "base": { "point": [ 23, 19 ] }}
27. this.getState() returns an object which only the custom interaction object itself needs to understand,
28. this.getStatus returns "closed"
29. When the delivery engine identifies that the custom interaction is to be removed from display it should first call the method set in the oncompleted callback property of the custom interaction object

    e.g. destroyItem: function () {
	     for (var i = 0; i < this.pciInteractions.length; i++) {
	          this.pciInteractions[i].oncompleted(); }
	   }

30. If the the custom interaction object has set an oncompleted callback method it can do whatever cleanup it requires before the interaction is unloaded
31. At any point after the custom interaction object has fired the onready callback (e.g. if the student has indicated that they wish to navigate away from the item) the delivery engine can call getResponse() on the custom interaction object to get the current value of the response to set on the response variable named in the responseIdentifier attribute of the customInteraction element.

    e.g. var responseValue = this.pciInteractions[currentInteraction].getResponse();
	     this.setResponseValue(currentInteraction, responseValue);

	     where responseValue = { "base": { "point": [ 23, 19 ] }}

32. At any point  after the custom interaction object has fired the onready callback the delivery engine can call getState to capture the current state of the interaction. It can use this to reconstruct the custom interaction in this same state so the user can continue to interact with it. It would do this by recreating the custom interaction and passing the result of getState as the final optional parameter to getInstance.
33. If a delivery engine wants to persist this state on a server rather than in the browser it may be useful to call JSON.stringify to serialize the state and then call JSON.parse to recreate the object before passing it to getInstance()

2.7 Accessibility

It is possible to make portable custom interactions accessible. However, ensuring accessibility of custom interactions may require additional practices beyond those required for defined (i.e., non-custom) interactions. Best practices for accessibility of custom interactions are in the process of being developed and should become available in later versions of this and other documents.

Custom interactions should rely, to the extent possible, on existing standards, including two specifications of the World Wide Web Consortium (W3C) -- the Web Content Accessibility Guidelines version 2 (WCAG) (a W3C recommendation) and WAI-ARIA accessibility guidelines (a W3C candidate recommendation).

The WAI-ARIA guidelines describe semantics to identify user interface controls, dynamically changing content regions, and events. Reviewing http://www.w3.org/WAI/intro/aria provides the reader with the published guidelines and best practices to follow. Below is also a list of JavaScript libraries working to align with the WAI-ARIA guidelines:

• The Dojo Toolkit (http://dojotoolkit.org/
• YUI (http://yuilibrary.com/
• jQueryUI (http://www.jqueryui.com

In order to increase the consistency of how these standards are applied and interpreted across vendors, interested vendors are encouraged to share their accessibility practices and approaches around custom interactions with others through the APMG.

When the custom interaction part of the item content involves XHTML-like elements with clear identifying attributes, it is suggested to provide APIP accessibility information linked to that content by id.  More information on APIP’s standard approach to connecting content and accessibility metadata can be found in the linked portion of the APIP Best Practices document [APIP, 12].

It should also be noted that the APIP standard is focused on ensuring the proper exchange of accessibility information but does not specify all significant aspects of assessment delivery. This is true for both custom and defined (non-custom) interactions. Implementers may find, for example, that while the APIP specification defines the basic information needed for accessible drag-and-drop assessment items, it does not define all important issues that would be needed to make drag-and-drop assessment items usable by some people with disabilities. For example, implementers need to determine how to address the needs of individuals who cannot use a mouse (e.g., who are blind or have fine motor disabilities) or who may prefer other input modalities (e.g., keyboard).

2.8 Packaging

Packaging of portable custom interactions does not require any adjustments to IMS Global packaging specifications. The resource element defined by the specifications will suffice for linking artifacts. This is an excerpt from a manifest describing the packaging of a portable custom interaction:

<resources>
  <resource identifier="GI" type="imsqti_apipitem_xmlv2p2" href="items/graphItem.xml">
    <lom xmlns="http://ltsc.ieee.org/xsd/apipv1p0/LOM/resource">
      <general>
        <identifier>
          <entry>GraphItem</entry>
        </identifier>
        <title />
      </general>
     <lifeCycle>
       <contribute />
       <version>
         <string>Final 1.89</string>
       </version>
     </lifeCycle>
     <educational>
       <description>
         <string>Graphing Question.</string>
       </description>
     </educational>
     <qtiMetadata xmlns="http://www.imsglobal.org/xsd/apip/apipv1p0/qtimetadata/imsqti_v2p2">
       <interactionType>customInteraction</interactionType>
       <feedbackType>none</feedbackType>
       <solutionAvailable>false</solutionAvailable>
     </qtiMetadata>
   </lom>
   <file href="items/graphItem.xml" />
   <file href="items/graph.js" />
   <file href="items/graph.css" />
 </resource>
</resources>

Appendix A – Base Types

The following is a list of examples showing QTI base types and cardinality represented by a JSON example. The representations are the expected format when dealing with response data.

Table A.1 QTI Base Types to JSON Representation

Duration expresses the value using ISO 8601 durations to comply with JSON schema

Table A.2 QTI Multiple and Ordered Cardinality to JSON Representation

Table A.3 QTI Record Cardinality to JSON Representation

				{"record": [
				   {
				       "name": "rock",
				       "base": {
				           "boolean": true
				       }
				   },
				   {
				       "name": "paper",
				       "list": {
				           "string": ["p","a","p","e","r"]
				       }
				   },
				   {
				       "name": "scissors",
				       "list": {
				           "integer": [1, 2, 3, 4]
				      }
				   },
				   {
				       "name": null
				   }
					]
				}
				

Appendix B – Module Resolution Configuration Format

This config file is a JSON document like the following example
{ "waitSeconds": 15, 
	  "paths": {
	        "graph": "https://example.com/js/modules/graph1.01/graph.js",
	        "foo": "https://foobar.com/foo/bar1.2/foo.js"
	  }
	} 

The waitSeconds property sets the timeout to use when attempting to download AMD Javascript modules. If not set the delivery engine may select the timeout to use.

The paths property provides a simple mapping between module ids (e.g. "graph" and "foo") and the URL to use to download the module.

About this Document

List of Contributors

Please contact IMS Global through our website at http://www.imsglobal.org

Please refer to Document Name: IMS Portable Custom Interactions Specification v1.0

Date: 1 June 2017