Task Player API Methods

Methods are called by sending a "request message" via the postMessage mechanism to the task player. For methods that return a result the task player responds with a "result message".

Each method has its own eventType that is included as attribute in the request message. See the tables below for detailed descriptions of the available methods and their request and response message structures.

To match a request to its result message you may add a string attribute requestId to the request message. The task player will include this attribute in the corresponding result message.

Initialization

RequestDescriptionavailable in states
task player sends: { eventType: 'taskPlayerReady' }The task player sends this event when it switches from the Initial state to the NotLoggedIn state. After this point in time it is ready to receive messages.Initial

Configuration Control

Request sent by controllerResponse sent by task playerDescriptionavailable in states
{ eventType: 'setWaitMessages', primary: <String>, secondary: <String> }./.Set the messages to display in the page that is shown while the task player is waiting for configuration data to arrive.NotLoggedIn NoTaskRunning
{ eventType: 'addItem', itemConfig: {...}, resourcePath: <String>, externalResourcePath: <String>, libraryPathsMap: {...} }./.Add an item configuration to the catalog of available items. See the detail table below for an explanation of the parameters. Providing resource paths as parameters here facilitates specific resource directories for each item on the server or in the file system accessed by a ServiceWorker etc.NotLoggedIn NoTaskRunning
{ eventType: 'clearItems' }./.Drop all item configurations.NotLoggedIn NoTaskRunning
{ eventType: 'setScalingConfiguration', scalingMode: <String>, alignmentHorizontal: <String>, alignmentVertical: <String> }./.Configure the auto-scaling behavior for items that do not match the available view port size. The scaling mode should be one of 'no-scaling', 'scale-up', 'scale-down', 'scale-up-down'. The horizontal alignment should be one of 'left', 'right', 'center'.The horizontal alignment should be one of 'top', 'bottom' or 'center'.NotLoggedIn NoTaskRunning
{ eventType: 'setPreload', requestId: <String>, itemName: <String> }{ eventType: 'setPreloadReturn', requestId: <String>, isSuccess: <Boolean>, message: {...} }Activate the preloading mechanism for an item in the catalog of available items. Once the preloading is done the task player will respond with a result event: In case of a success the message contains meta data about the preloaded resources, for a failure it contains an error explanation as simple string. See the detail table below for an explanation of the attributes.NotLoggedIn NoTaskRunning

Parameters of addItem

ParameterStructureDescription
itemConfig{...}The item description as provided by the CBAItemBuilder in the config.json file. The structure contained therein is 'private API'.
resourcePath<String>The root path for downloading image, audio and video resources. The task player will prepend this path to the resource path given in the item configuration when specifying the src attribute in the tag downloading the resource (e.g. in <img src=...> or <audio src=...> or <video src=...>)
externalResourcePath<String>The root path for the ExternalPageFrame content that is embedded in the item. The task player will prepend this path to the ExternaPageFrame source path given in the item configuration when specifying the src url for the IFrame.
libraryPathsMap{MathJax : <String>}The URL that the task player will use to download the MathJax libraries. You may use a CDN URL or a local installation on your server. This setting is ignored for items that don't use MathJax. (Further common code libraries may be added in the future in this parameter structure.)

Parameters of setPreloadReturn

ParameterStructureDescription
requestId<String>
isSuccess<Boolean>Preload command was successful (true) or failed (false).
message (for failure)<String>In case of a total failure the message attribute contains an error explanation as simple string.
message (for success){images : [{name : <String>, size : <Integer>, type : <String>, path : <String>, isExternal : <Boolean>, hadErrors : <Boolean>}], audios : [{name : <String>, size : <Integer>, type : <String>, path : <String>, isExternal : <Boolean>, hadErrors : <Boolean>}], videos : [{name : <String>, size : <Integer>, type : <String>, path : <String>, isExternal : <Boolean>, hadErrors : <Boolean>}]}After successful execution the message attribute contains a detailed listing of the preloaded resources grouped by resource types. (Note: Some browsers (e.g. Firefox) set the hadErrors flag just because the preloaded resource was not used a couple of seconds after the preload. This is not really an error in our context. You could look at the warnings in the browser console to check your scenario.)

Trace Control

Request sent by controllerDescriptionavailable in states
{ eventType: 'insertMessageInTrace', message: <String> }Insert the given message into the trace log.NoTaskRunning TaskRunning
{ eventType: 'logStateToTrace' }Trigger a dump of the current state (a so called ‘snapshot’) into the trace log.NoTaskRunning TaskRunning
{ eventType: 'flushTrace' }Transmit all pending trace log entries immediately to the controller layer (by triggering a call of the trace receiver callback).NoTaskRunning TaskRunning
{ eventType: 'setTraceLogTransmissionChannel', channel: 'http', transmitUrl: <String>, interval: <Integer>, httpTimeout: <Integer> }Set the trace log to be sent to the given URL using HTTP POST requests. The 'httpTimeout' parameter specifies the maximum time we will wait for a response at each HTTP request. The ‘interval’ parameter specifies the time in milliseconds to collect log entries before sending the next bunch. A value of 0 will trigger a call immediately as soon as a log entry is available. This method will override settings done by the other setXXXTraceTransmission methods.NotLoggedIn
{ eventType: 'setTraceLogTransmissionChannel', channel: 'console', interval: <Integer> }Set the trace log to be sent to console. The ‘interval’ parameter specifies the time in milliseconds to collect log entries before sending the next bunch. A value of 0 will trigger a call immediately as soon as a log entry is available. This method will override settings done by the other setXXXTraceTransmission methods.NotLoggedIn
{ eventType: 'setTraceLogTransmissionChannel', channel: 'postMessage', targetWindowType: <String>, targetOrigin: <String>, interval: <Integer> }Set the trace log to be sent via post message events using the given target window type ('self', 'parent', 'opener') and the given target windows's origin. The ‘interval’ parameter specifies the time in milliseconds to collect log entries before sending the next bunch. A value of 0 will trigger a call immediately as soon as a log entry is available. This method will override settings done by the other setXXXTraceTransmission methods.NotLoggedIn
{ eventType: 'setTraceContextId', contextId: <String> }Set the ‘contextId’. The task player will include this context ID as 'sessionId' in the meta data for each trace log transmission chunk. The ID might identify a kind of session even before the user has logged in or in case one user runs multiple sessions.NotLoggedIn NoTaskRunning
{ eventType: 'setTraceContentFilter', replaySupport: <Boolean>, withExtendedMetaData: <Boolean>, withoutItemConfiguration: <Boolean>, withoutSnapshot: <Boolean>, withoutScoring: <Boolean> }(Experimental) Set filters that extend or reduce the verbosity of the trace log. Currently we support these filters: replaySupport activates additional log entries that are required for the trace-log based replay, withExtendedMetaData activates additional meta data fields on all trace log entries (item, task, scope, sessionId), withoutItemConfiguration drops the item configuration from the ItemSwitch log entries, withoutSnapshot drops all Snapshot log entries, withoutScoring drops the taskResult (i.e. scoring) from the TaskSwitch log entries. This feature is experimental and may change in the next release.NotLoggedIn NoTaskRunning

Recordings Control

Request sent by controllerDescriptionavailable in states
{ eventType: 'setRecordingTransmissionChannel', channel: 'http', transmitUrl: <String>, httpTimeout: <Integer> }Set the recordings to be sent to the given URL using HTTP POST requests. The 'httpTimeout' parameter specifies the maximum time the task player will wait for a response at each HTTP request.NotLoggedIn
{ eventType: 'setRecordingTransmissionChannel', channel: 'console' }Set the recordings to be sent to console.NotLoggedIn
{ eventType: 'setRecordingTransmissionChannel', channel: 'postMessage', targetWindowType: <String>, targetOrigin: <String> }Set the recordings to be sent via post message events using the given target window type ('self', 'parent', 'opener') and the given target windows's origin.NotLoggedIn
{ eventType: 'setRecordingContextId', contextId: <String> }Set the ‘contextId’. The task player will include this context ID in the meta data structure for each recording transmission.NotLoggedIn NoTaskRunning

User Control

Request sent by controllerResponse sent by task playerDescriptionavailable in states
{ eventType: 'setUserId', id: <String> }./.Set the ID of the currently logged in user and switch to NoTaskRunning. The point in time of this call is used as login time in the trace log. The task player will include this userId in the meta data structure for each trace log transmission.NotLoggedIn
{ eventType: 'logout' }./.Transmit all pending trace log entries, drop the currently logged in user, clear the tasks state and switch to NotLoggedIn.NoTaskRunning
{ eventType: 'getUserId', requestId: <String> }{ eventType: 'getUserIdReturn', requestId: <String>, id: <String> }Get the ID of the currently logged in user. The method returns ‘undefined’ if the task player is in state ‘NotLoggedIn’NotLoggedIn NoTaskRunning TaskRunning
{ eventType: 'showLogin', requestId: <String>, titleLabel: <String>, fieldLabel: <String>, buttonLabel: <String> }{ eventType: 'loginDialogClosed', requestId: <String>, fieldValue: <String> }Show a login dialog with the given title containing an input field using the given field label and a confirm button with the given label. As soon as the user hits the button in the dialog the task player sends the return event with the text values of the input field.NotLoggedIn NoTaskRunning

Task Control

RequestResponse sent by task playerDescriptionavailable in states
controller sends: { eventType: 'startTask', scope: <String>, item: <String>, task: <String> }./.Start running the task specified by ‘item’ and ‘task’. Use the component state specified by ‘scope’, ‘item’ and ‘task’. With the ‘scope’ parameter one can initiate a new task run (by using a new ‘scope’ value) or resume a former task run (by specifying the old ‘scope’ value). If the start task command fails, the task player will switch to state TaskRunning, but no task is actually running. You may use the getTask command to verify, that the task was actually started.NoTaskRunning
controller sends: { eventType: 'stopTask' }./.Stop the currently running task.TaskRunning
controller sends: { eventType: 'pauseTask' }./.Pause the currently running task. Does nothing if task is already paused. While the task is paused the state machine timer events and the elapsed execution time do not propagate.TaskRunning
controller sends: { eventType: 'resumeTask' }./.Resume the currently paused task. Does nothing if task is not paused.TaskRunning
controller sends: { eventType: 'getTask', requestId: <String> }{ eventType: 'getTaskReturn', requestId: <String>, scope: <String>, item: <String>, task: <String> }Return the specification of the currently running task. The method returns ‘undefined’ if the task player is not in TaskRunning state currently. If a previous start task command failed, the task player is in state TaskRunning, but no task is actually running. In this case the returned structure contains no task name but might contain an item name and a scope name.NotLoggedIn NoTaskRunning TaskRunning
controller sends: { eventType: 'setTaskSequencer', targetWindowType: <String>, targetOrigin: <String> }./.Set the target window type (‘self’, ‘parent’, ‘opener’) and the target window’s origin that the task player should use to send postMessage events when the running task requests a task switch.NoTaskRunning
controller sends: { eventType: 'setSwitchAvailability', request: <String>, scope: <String> }./.The controller should signal the availability of task switches by sending events with type ‘setSwitchAvailability’. Valid values for request are 'nextTask' or 'previousTask'. The task player assumes ‘not available’ as default. The setting has no effect until a task sequencer is configured. The setting applies to commands in MenuItem components only. Other task switch requests are not affected.NotLoggedIn NoTaskRunning TaskRunning
task player sends: { eventType: 'taskSwitchRequest', request: <String>, scope: <String>, item: <String>, task: <String> }./.The task player requests a task switch to the specified task.The controller has to issue the necessary stopTask/startTask calls to fulfill the request. The task player layer will never switch the task by itself. Valid values for request are 'nextTask', 'previousTask', 'cancelTask' or 'goToTask'. In case of ‘goToTask’ the request also specifies a scope, an optional item and a task. If no item is given the first matching task in the scope should be chosen.NoTaskRunning

Task State Control

Request sent by controllerResponse sent by task playerDescriptionavailable in states
{ eventType: 'getTasksState', requestId: <String> }{ eventType: 'getTasksStateReturn', requestId: <String>, userId: <String>, state: {...} }Get the complete state of all tasks. The structure of the returned state object is 'private API'. You should use this 'as is' as parameter value for the preloadTasksState command.NoTaskRunning TaskRunning
{ eventType: 'clearTasksState' }./.Drop the complete state of all tasks.NoTaskRunning
{ eventType: 'preloadTasksState', state: {...} }./.Load the given state as complete state of all tasks. Use a state object returned by the getTasksState command. The structure of the state object is 'private API'.NoTaskRunning
{ eventType: 'replay', story: [{entryId : <String>, timestamp : <String>, type : <String>, replayTick : <Integer>, details : {...}}] }./.(Experimental) Replay the given list of trace log events. The objects in the array should be trace log event entries from a trace log file. You might add an additional attribute replayTick to control the replay timing. This is an experimental feature and might change in the next release.NoTaskRunning

Scoring Control

Request sent by controllerResponse sent by task playerDescriptionavailable in states
{ eventType: 'getScoringResult', requestId: <String> }{ eventType: 'getScoringResultReturn', requestId: <String>, result: {...} }Start a scoring evaluation and get the result.The result object contains name-value pairs represented as JSON object with attributes. For a detailed description see the 'Scoring Result' chapter.TaskRunning
{ eventType: 'getOldScoringResult', requestId: <String>, scope: <String>, item: <String>, task: <String> }{ eventType: 'getOldScoringResultReturn', requestId: <String>, result: {...} }Get the scoring result of a task that was stopped earlier.The result object contains name-value pairs represented as JSON object with attributes. For a detailed description see the 'Scoring Result' chapter.NoTaskRunning

State Machine Control

Request sent by controllerDescriptionavailable in states
{ eventType: 'sendStatemachineEvent', event: <String> }Trigger the given event in the state machine of the currently running task.TaskRunning

Header Control

Request sent by controllerDescriptionavailable in states
{ eventType: 'setHeaderButtons', headerButtons: [{...}] }Configure the header buttons menu. For each button include an object with attributes image, text, event (as Strings) and height, width (as Integer). See the section down below for a detailed object description.NotLoggedIn NoTaskRunning
{ eventType: 'setMenuCarousels', course: [<String>], scopes: [{...}] }Configure the menu carousels in the header.For each scope group add a name to the course array. For each scope add an object to the scopes array. The object should have attributes name (as String) and tasks (as array of objects with attributes item and task as String). See the section down below for a detailed object description.NotLoggedIn NoTaskRunning

Parameters of setHeaderButtons

ParameterStructureDescription
header button list entry{image : <String>, text : <String>, event : <String>, height : <Integer>, width : <Integer>}Each entry describes one header button: The image (optional), the label, the triggered state machine event and the size.

Parameters of setMenuCarousels

ParameterStructureDescription
scopes list entry{name : <String>, tasks : [{item : <String>, task : <String>}]}Each entry describes one scope button in the navigation header: The name of the scope and the array of pairs of item and task to specify the tasks in the scope.

Developer Mode Control

Request sent by controllerDescriptionavailable in states
{ eventType: 'activateDebuggingWindows', scoreHotKey: <String>, traceHotKey: <String>, statemachineHotKey: <String> }Configure the hot keys that open the debugging windows. Specify hot keys in a format like ctrl+shift+A or ctrl+B. Use an empty string as hot key to deactivate a debugging window.NotLoggedIn NoTaskRunning