Reporting API for External Web Page Integrations...This is a new “form” element that allows the ... information on the format of this new attribute. ... HTML5 IMOs using the new

Copyright 2018, by HR Avatar, Inc. 41101 Haybine Lane, Aldie, VA 20105 (703) 938-1615

Reporting API for External Web Page Integrations

Version: 2.0.52 Date: 19 June, 2019 List of significant changes between versions: (starting with 2.0.18) Version 2.0.52 Modified resultXML attributes to reduce resultXML file size for large IMOs (HTML5 implementations only). The revised XSD is at:

https://sim.hravatar.com/tb/misc/descriptor/imo_reportingxml_latest.xsd

Version 2.0.51 Revised info for IFrame interaction items. Adds a new method name for iframe interaction items to receive information from the page inside the iframe.

Version 2.0.50 Revised info for ClickStream interaction items. Adds initvalue7 which tells the IMO that history from javascript will be loaded asynchronously. Requires the gethistfcn parameter to be defined. If initval7==1 it will assume this is asynchronous and the hosting webpage will call the imoapi.setHist function when the xml is ready. Added imoapi method setHist for setting history in the IMO after it is loaded asynchronously.

Version 2.0.49 Indicates that the packed string method of storing results has been moved from the HTML5 code, so that it only works in Flash versions of the IMO. Also, adds ResultXML info for Interaction Click Stream interaction items.

Version 2.0.48 Added iv2 – iv10 initialization parameters to allow init values to be set at runtime and override hard coded values. HTML5 only.

Version 2.0.47 Enhanced section on file uploads, adding for blob-oriented uploads as well as files. --- END OF FLASH SUPPORT – Enhancements to IMO functionality above this point are performed only on the HTML5 version of IMOs. Flash code is only modified for bug fixes.

Version 2.0.46 Added a new section regarding ADA accessibility and Tab Indexes.

Version 2.0.45 Added a new option for the aud4vidwspec param to the IMO initialization parameters so that the hosting webpage can force the IMO to utilize no Audio or Video (aud4vidwspec=3).



Version 2.0.44 Added reporting format for items with the “pin image” format. This is a new “form” element that allows the user to click on a background image and place a “pin” which is a thumbnail on top of the image in that exact location. The coordinates of the pin, relative to the base image are then reported. A single interaction can have multiple pins. The exact coordinates, relative to the background image, and the exact amount of time it took the user to place the pin are reported in the resultXml.

Version 2.0.43 Added novalidprev parameter to enable skipping all form validation and acceptance rules. This is useful

for preview modes to enable faster clicking through the IMO.

Version 2.0.42 Added reviewmode parameter to enable read-only review-mode navigation of an IMO in a completed

status and with existing result XML. Turns off all changes to responses. Available only in HTML5. Also added the scoredata parameter to provide a source of score information to the IMO if reviewmode is set to the appropriate value.

Version 2.0.41 Added directxmlposturl parameter to set the direct url for reporting response data directly to the server

(vs the hosting web page). This will override the value entered during authortime. Note that the header Access-Control-Allow-Origin must be properly set on the hosting webpage. Note also that the IMO will use this url to request existing response data unless it is provided by the hosting webpage via parameters.

Version 2.0.40 Added reportdelaytime parameter to set the minimum interval between XML result reporting. This value is set in seconds. Default is 3 seconds. This means that, prior to an IMO being 97% complete, the XML reporting interval will never be less than 3 seconds. Also added additional fields to the response XML for item and section tracking (see appendix).

Version 2.0.39 Added the ability for hosting web pages to call specific methods on an IMO. Web pages can call window.imoapi.api_[IMO Number] to request the most current result xml or stop all action. Information is included in the section entitled Communicating Directly to the IMO via Javascript.

Version 2.0.38 Added the aud4vidwspec param to the IMO initialization parameters so that the hosting webpage can force the IMO to utilize the audio and images instead of video when these are available (aud4vidwspec=1 use audio and images instead of video).

Version 2.0.37 Added ordrdo to result xml for clip interactions. This is needed for correct restarts when ordered clip numbers are used and clips are scrambled at runtime.

Version 2.0.36 Added the bwspec param to the IMO initialization parameters so that the hosting webpage can force the IMO to utilize the lowest bandwidth video available (bwspec=1 force low). Version 2.0.35 Added the stopaction member to the object provided by the IMO to statusfcn when there is a status message. 0 means action not stopped. 1 means action has been stopped due to an error. Implementations can use this to recognize when a situation has occurred in which the IMO has been frozen by a software


error of some kind. In most cases, the accompanying message will include a stack trace. Implementations can use this to route to an error screen, for instance, or send an email message. Version 2.0.34 Added deploydate attribute to clicflic element (top element) in result xml. This will help in troubleshooting remote deployments. Version 2.0.33 Changed name from ClicFlic to HR Avatar. Version 2.0.32 Added a number of fields to the result xml to enable better troubleshooting, particularly when IMO reloads occur. (1) Added a field to the event element in the result XML called event.rstrttmstmplst which is a comma-delimited list of all restart (reload) timestamps, in order. This is intended for use in tracing issues in the result XML. (2) Also added the clicflic.ua attribute which shows the most recent user agent code and (3) the event.uahistory which shows all ua codes, in order, start to finish (one for the initial load and one for each reload). This allows you to identify if the user has changed devices during the middle of an event. A full list of ua codes is included in Appendix C. Finally, added the event.minverhistory attribute with is a comma-delimited list of all minor versions (one for initial load and one for each reload). This enables you to detect when a newly compiled version has been loaded during a reload. Version 2.0.31 Added percent complete as attribute pctc for intn and clip element in history and for each itn and clp element in cronhist. This will make it easier to track down issues regarding percent complete calculations. These values are not used by the IMO directly. Also added the src attribute to itn elements in cronhist to provide information regarding what clip was playing when the interaction was clicked. Version 2.0.30 Added a new element dlydintns to the event element to provide a list of all upper layer (not removed when clip is changed) interactions that have been set to appear after the expiration of a timer. This can happen when an interaction is set to appear after the end of a clip. This is needed to ensure that if there is a restart after the timer for the interaction has started and also after the clip that initiated the timer has advanced, that the interaction will appear when the IMO is restarted. Version 2.0.29 Added new attributes swpltfrm and swpltfrmversion to the clicflic element of the result XML which indicates the software platform that the IMO employed during execution when the result xml is generated. Possible values are ‘as3’ for flash as3 platforms, and ‘html5’ for html5. Only available in the IMO-generated XML, which is becoming the primary means of reporting. The version is just the version number (if Flash). Version 2.0.28 Added a new element intnsshown to the event element to provide a list of all interactions that have been displayed at least once during the administration of the IMO. This is needed to ensure that interactions that adjust state variables when they are displayed the first time do


not double-count on restarts. Version 2.0.27 Added a new attribute to all cronhist -> clp called ‘src’ that contains information identifying what caused a clip to be displayed. This change was implemented to enhance the ability to reconstruct the pathway taken by a user from the XML. Please see Appendix A for more information on the format of this new attribute. Version 2.0.26 Added a second parameter to the sethistfcn function so that metadata can be sent to this function along with the result XML that can help implementations avoid parsing the XML on the webpage. The second parameter is an object that has one member value, pctcomplt which has the current percent complete reported by the IMO. Also, added more info regarding the gethistfcn and cleansing the XML before sending back to the IMO from a webpage. Version 2.0.25 Added eventid to log messages sent to statusfcn for better reporting in HR Avatar-hosted situations. Added a section to this document on capturing log messages. Version 2.0.24 Expanded the statusfcn functionality to include messages of different levels (error, warning, and info). Hosting webpages can then control the disposition of these messages. Also, added two new optional parameters: ndsh5id, ndsflshh5id. These parameters are used to override the default messages presented to a user when they do not have a compatible web browser. For HTML5-only deployments, ndsh5id is used, for hybrid Flash or HTML5 deployments, the ndsflshh5id parameter is used. These parameters should be set to the id of a hidden HTML element that contains what should be presented to the user. The system will change the display style value to block (if needed), move the html to where the IMO would have been presented, and then present it to the user. Also, added a new section explaining file uploads. Version 2.0.23 Added frcdeptyp input parameter. For hybrid deployments, this feature allows you to force the IMO to use flash (1) or HTMl5 (2), usually for testing purposes. Also, added the fupldurl parameter so that the hosting webpage can pass the default file upload url to the IMO for HTML5 IMOs using the new File Upload Button interaction item type. Version 2.0.22 Added tmstmp (time stamp) attribute to the result XML for all interaction and clip elements. Additionally, added capability to insert a reference time (milliseconds from midnight January 1, 1970) as an optional parameter (reftime), allowing all timestamps to be synchronized with server time, instead of client system time, which is unpredictable and may not be accurate). Use of reftime also makes it possible to pinpoint server side log entries with IMO actions and events. This value can be useful for reconstruction/tracing of actual events. Also added tmstmp attribute to event element to indicate time of initial IMO load. Version 2.0.21 Added the cronhist element to the result XML. This is a chronological record of all clips &


interactions that is only present when the history recording mode is set to unique interactions. This data is not used on restart, but is useful for reconstruction/debugging of actual test events. Version 2.0.20 Removed the ‘hist’ parameter as an allowed parameter and added notes to the ‘gethistfcn’ parameter to prevent back button/forward button bug that could cause improper reload of result XML. Version 2.0.19 Significant revision to simplify and remove irrelevant or outdated information. Version 2.0.18 Added two fields to the Result XML only:

imonum = the imo number rstrtndseqlst = a comma delimited list of the resnodeseq numbers for clips where the IMO was reloaded and restarted. This is useful for troubleshooting errors caused by restarts.

Purpose To document the standard methods of embedding an HR Avatar IMO into a third-party web-based system, such as a testing system or applicant tracking system, and obtaining all user inputs and item responses for scoring or tracking purposes. Note that this document does not address SCORM integration. LMS integration of SCOs produced by the HR Avatar authoring system is based on the auto import capability of SCORM compatible LMS applications. This document also does not address HR Avatar Online Assessment System (HRAS) and its associated APIs. The HRAS is a full-featured system which administers IMO-based assessments to test takers, captures responses, performs scoring, generates and distributes reports. Additional information about this system is available at: https://www.hravatar.com/ta/catalog/technology-platform.xhtml and the API is located at: http://cfmedia.clicflic.com/web/misc/api/HRAvatarTestIntegrationGuide_latest.pdf Definitions Event – Refers to a unique event during which a specific viewer interacts with an IMO by viewing/listening to media, clicking on interactive icons, and entering data in interactive forms. Clip – A set of clip segments (below) that is treated like a group. When the IMO is instructed to play a Clip, it selects one of the clip segments according to preset rules and presents it to the viewer. Clip Segment – An element of media that can be presented to the viewer. Clip segments can

https://www.hravatar.com/ta/catalog/technology-platform.xhtml

http://cfmedia.clicflic.com/web/misc/api/HRAvatarTestIntegrationGuide_latest.pdf


be a video, an image, an audio, a flash animation, or just text. Clip segments can have zero or more interactions associated with them. When the clip segment is playing, the interactions can be presented to the viewer at preset times during the clip segment. Flash – Adobe Flash Technology. IMO's can be administered using Adobe Flash Player, either standalone or embedded in a web-browser. Clicflic IMOs currently require Adobe Flash Player 9.0.0 or higher, depending on the media included in the IMO. The default requirement is 10.0.0. However, by using FLV video formats, you can set the player to require 9.0.0 or higher. Also, you can set the default requirement for MP4 (h.264) or f4v video to 9.0.115 if you wish. HTML5 – A collection of HTML/Javascript/and CSS capabilities that enables various multimedia and dynamic html concepts needed to produce interactive rich media objects without use of a technology such as Adobe Flash. IMO or Intelligent Media Object – this is the base object that is embedded into a webpage that contains all of the HR Avatar functionality. This document is concerned with how to embed and then communicate with a single IMO. The IMO could be used as an assessment or e-learning simulation, or any other interactive communication program. In physical form, an IMO is a collection of files of different types, including Adobe Flash, Javascript, images, video files, etc. Interaction -- A set of Interaction Items (below) that is presented to the viewer as a group. Interaction Item – A single button, link, image, or other media asset that is presented to the viewer as part of an interaction. Most interaction items are clickable, like a button. However, interaction items can also be non-clickable, like a custom caption or an image presented for show only, or a background audio. Participant -- The person who is interacting with the IMO via their web browser. Could be a candidate, a website visitor, or an employee. Overview Third party systems host and embed IMOs in webpages served by their system and then serve those pages to users as appropriate. The IMO then administers an interactive experience to the participant, typically for assessment or training. The IMO also reports data back to the server or the hosting web page containing all information on all user interactions. The server then receives this information and can store or process it as needed, such as to record completion of a training exercise, or produce an assessment score report. This document addresses options for embedding IMOs into a webpage and communicating with them once they load into a browser.


Browser-Technologies Used - Flash or HTML5 IMOs can operate using either Flash or HTML5 technology. They look almost the same no matter which technology is used. Note 2018: Flash is largely discontinued and poorly supported by web browsers. Additionally, Adobe is no longer supporting Flash. Users should switch their IMOs to use “HTML5 Only” unless there are serious mitigating circumstances. Publishing Modes IMOs can be exported (published) from the authoring system in the following modes:

1. Flash Only 2. HTML5 Only 3. Either Flash or HTML5, default to Flash 4. Either Flash or HTML5, default to HTML5

When an IMO is published, the HR Avatar website produces a .Zip file that can be downloaded and then unzipped into the appropriate directory on a third party server. This Zip file contains all components needed to operate the IMO without any dependence or communication with HR Avatar. Embedding IMOs in Webpages When an object is exported, sample HTML code within the IMO .zip file that demonstrates how to embed the IMO in a webpage for the publishing mode selected. In all cases, there is a mechanism for providing parameters to the IMO as it loads in the web browser to obtain the desired behavior. An example of this sample HTML, for an IMO that operates in both HTML5 and Flash, is: <script id="cf5imoscrip_1501" type="text/javascript" src="http://cfmedia.clicflic.com/web/a/1001/4/reFusqMUJ3Q-/cf_json_imo.js"></script> <script id="cf5_corescrip" type="text/javascript" src="http://cfmedia.clicflic.com/web/misc/hybrid/clicflichybrid_1.js"></script> <script type="text/javascript"> var cf_i1501_prms={optionname:’value’}; // note, all optional parameters are placed within this object. </script> <div id="cf_hybdiv_1501" class="cfh5imo1501" style="position:relative;width:960px;height:568px">

If you place the above HTML in a webpage and load it into your web browser, you should see the ClicFlic 2012 Holiday IMO. Notice the javascript with the variable cf_i1501. This is an object that is used to convey all optional parameters to the IMO.

Initialization Parameters


When it loads, the IMO checks to see what parameters have been loaded. The following parameters can be provided:

Parameter Name (Case Sensitive)

Description Default

statusfcn Name of a javascript function resident on the host HTML document that can be called. This method is called with one parameter, an object that contains various properties: status: complete, exit, msg outpoints: points assigned (only if status=complete) text: content of message (only if status=msg) level: level of message (only if status=msg, 0=error, 1=warning, 2=info) eventid: the eventd (status=msg only). stopaction: 0 means not stopped, 1 means action has been stopped due to the error (status=msg only).

null

autostart True or false – indicates that the IMO should start playing as soon as it's loaded.

TRUE

hpu Host page url – if provided, will be reported to the server during normal reporting for inclusion in analytics reports.

null

rfr Referer URL– if provided, will be reported to the server during normal reporting for inclusion in analytics reports.

null

refid Referal ID – if provided, will be reported to the server during normal reporting for inclusion in analytics reports.

null

eventid Unique Event Identifier – this is the unique identifier (alphanumeric) that should be used to report all information back to the server. If not provided up front, the IMO will request it via an HTTP Transaction from the server. Note that if you want to provide history data (see below) you must provide a value for eventid or the IMO will not look for history data in the host webpage or from the server via HTTP. Also, you can embed the eventid in the host webpage and set the IMO (via main settings->Integration Settings) to verify it with the server via the “Embedded Eventid

null



Description Default

verify URL” so that the IMO will authenticate itself prior to operating when the eventid is provided in the hosting webpage. This prevents unauthorized access to the IMO in standalone deployment cases.

gethistfcn Javascript function to call to obtain the hist string (described in hist below) rather than get it from a flashvar (hist). This is used for long strings and XML docs when putting it in a flashvar is not practical. Either gethistfcn or hist should be provided, but not both. Note that this function is ignored unless the history recording mode is set to Unique Interactions. Important Note: This javascript function should read the XML from the server before sending to the IMO. This is to prevent the case in which the XML is inserted into the webpage dynamically, and the user later clicks the back button after making several new responses, and then clicks the forward button. By loading the XML dynamically, you assure that the latest and greatest XML only is loaded into the IMO at all times. Important Note 2: We have noticed that some implementations, when sending XML back to a flash IMO, hidden characters, like carriage returns and line feeds in the result XML can cause the E4X XML parser to fail. Therefore if you are experiencing this, you clean the XML before sending it back to the server, with something like this javascript function, that removes each carriage return/line feed occurring after the end of an element:

cleanHist = histStr.replace(/>[\n\r]/g, '>');

null

histisxml This is required for all implementations that will pass history data to or receive history data from the IMO. The default is false and must be set to true. Note: This parameter no longer works in HTML5 which now only supports XML.

FALSE

sethistfcn Name of javascript method to be called by IMO every time viewer answers a required item or item that requests special reporting. This method should accept two parameters

null



Description Default

- an XML document (as a string). The second parameter is an object that has the following fields: pctcomplt = percent complete 0.0 – 100.0

directxmlposturl This is the url to which the IMO should sent the response XML or packed string via HTTP POST. This will only be used if the sethistfcn is not set. Should be a fully-qualified URL like http://www.yourdomain.com/report. The body of the request is the response data. Note that the header Access-Control-Allow-Origin must be properly set on the hosting webpage for the destination. Note also that you may need to include the Access-Control-Allow-Methods=POST Access-Control-Allow-Headers=content-type headers in the response.

Null or whatever was entered at author time.

xref Unique Viewer Identifier – this is a unique identifier for the viewer. If a unique event identifier (eventid) is not provided, the IMO will request a unique event identifier from the server, and will include the xref value in this request, so it can be stored and used in reports.

null

altevtref External event identifier – in certain cases, the eventid must be provided by one system, but a unique identifier is also used by a different system and is needed for tracking. When provided, this value is embedded in results xml as altevtref so it can be used by third-party systems.

null

strtseq Start clip id – this is the identifier for the clip that you wish to start at, rather than the first clip designated in the authoring environment. It is a number that must match the id number of a clip in the system (ex: 1) Note: This should not be used for production implementations – it is used by the authoring system.

null

strttm Start clip time - This is the timecode at which to start the first clip. This is useful when you want to enter the first clip at different points depending on the where within a website a person views an object. Note: This should not be used for production implementations – it is used by the authoring system.

0

tmode True or false. Indicates test mode. When FALSE

http://www.yourdomain.com/report



Description Default

test mode is true, the IMO will not perform any reporting back to the server.

frcdeptyp If present, forces hybrid deployments to select either flash (frcdeptyp=1) or html5 (frcdeptyp=2). These are the only allowed values.

0

fupldurl This is the URL for file uploads performed by the IMO (HTML5 Only) using the File Upload Button interaction item.

null

scorpt SCO Reporting On. Indicates that the IMO should perform SCO interaction reporting. When this value is set to true, all interactions that are designated as a scorm mult choice or fill blank or other type are reported to the SCO API as interactions. Additionally, the full history string (packed) is sent to the SCO API in the cmi.launch_data field.

FALSE

medialoc For standalone deployments only. This is the directory of all media assets for this IMO to be used when the IMO is embedded in a web page that is not in the same directory as all media assets. Note that this value can also be set within the authoring system in Main Settings → Deployment Settings. However, having the ability to set it at runtime can sometimes provide more flexibility. This value must be an absolute url – such as /imos/imo_2232

or.http://www.mywebsite.com/imos/imo_2232. Do not use a relative url as this

causes problems with video and sound elements. Note also that if this value is set to an empty string it will still override anything set at author time.

null

ua UserAgent Code. Indicates the user agent in use. If not provide, the IMO will calculate it by itself. iPhone: 1 ipod: 1 android phone: 3 android tablet: 15 ipad: 4 blackberry: 5 symbian phone: 6 windows phone 7: 16 msie 9 or above: 17 msie 8 or below: 9

0

http://www.mywebsite.com/imos/imo_2232

http://www.mywebsite.com/imos/imo_2232



Description Default

chrome: 11 safari: 10 firefox: 12 opera: 13

reftime Reference time, usually provided by the server, which lets you synchronize all time stamps included in result XML with the server time. Presented as a number representing the number of milliseconds since midnight 1/1/1970.

0

reviewmode If greater than 0, this indicates that the IMO should operate in the assigned review mode, which generally allows navigation but does not change any answers. All form validation is disabled.If greater than 0, this indicates that the IMO should operate in the assigned review mode, which generally allows navigation but does not change any answers. All form validation is disabled. 0 = Default 1 = Review with no indication of response scoring. 1 = Review with no indication of response scoring. 2 = Review with indication of response scoring, if scoring data in scoredata parameter is provided. Note that this feature is available in HTML5 only.

0

scoredata This is a JSON Object that includes scoring data for each ‘item’ contained within an IMO. It is used only when reviewmode=2

null

ndsh5id and ndsflshh5id Used to override the default messages presented to a user when they do not have a compatible web browser. For HTML5-only deployments, ndsh5id is used, for hybrid Flash or HTML5 deployments, the ndsflshh5id parameter is used. Each should be set to the id of a hidden HTML element that contains what should be presented to the user. The system will change the display CSS value to block (if needed), move the element to where the IMO would have been presented, and present it to the user.

null

sv1,sv2,sv3, … sv12 State variable initial values null

iv2, iv3, iv4 .. iv10 Init values – 2 throu 100 only. These are 0 for all



Description Default

hard coded values for ‘sim’ type IMOs that are used in clip selection. They are typically hard coded at build time. However, they can be set here by a testing system.

nm Full Name – Can be used in most text as a substitution value. Should be URI Encoded.

null

fn First name – Can be used in most text as a substitution value. Should be URI Encoded.

null

ln Last Name – Can be used in most text as a substitution value. Should be URI Encoded.

null

em Email – Can be used in most text as a substitution value. Should be URI Encoded.

null

cn Company Name – Can be used in most text as a substitution value. Should be URI Encoded.

null

cust1, cust2, … cust50 Custom Fields, 1-50 – Can be used in most text as a substitution value. Should be URI Encoded.

Null

bwspec 0=default, 1=use low bandwidth video from the start,2=Force full video

0

aud4vidwspec 0=default, 1=use audio and pictures in place of video when available.3=No audio or video. Use still pics and text only.

0

reportdelaytime Sets the minimum interval between XML response data reports to a server or the hosting webpage. Specified in seconds (float). Tightly coupled systems may want to set this to a smaller interval.

3 seconds.

novalidprev 0=default 1=IMO should ignore all form validation and acceptance rules. This is used to enable faster click thrus for review purposes.

In 3rd party server implementations, the eventid and histisxml parameters are required. All other parameters are optional. These parameters are typically generated via dynamic webpages on the server. Getting Information into the IMO at Startup The initialization parameters (see section above) are used to provide information to the IMO when it first loads into a participant’s web browser. This includes previous response history when the participant is restarting an IMO that was partially completed. To allow for restarting where the participant left off, you provide the most recent response XML document back to


the IMO when it restarts, either via the ‘hist’ parameter, or via the javascript function referred to by the ‘gethistfcn’ parameter. No changes to the response XML are necessary. Getting Response Information from the IMO There are two kinds of information provided by the IMO. These are status information and response XML. Status information is always provided to the javascript function listed in the ‘statusfcn’ initialization parameter. For example, one status message sent is ‘exit’, which can be used to trigger navigation to a different webpage after the participant clicks an exit button inside the IMO. For response XML, you have several options, as follows: You can configure the IMO to send response XML directly to a server (via an HTTP POST transaction) within the authoring system. This is not the recommended approach, however, since it results in a brittle and inflexible system, and it reduces the efficiency of the single-threaded flash object in the case of flash implementations. Alternatively, you can use the initialization parameter ‘sethistfcn’ to indicate a javascript function on the hosting webpage that will receive the response XML each time it is sent. The javascript function can then handle the XML document as desired, either sending it back to the server, or parsing it in some way. This is the recommended approach. Finally, you can also request the result Xml using javascript as explained in the section below. Communicating Directly to the IMO via Javascript Hosting webpages can communicate directly with the IMO to perform such actions as getting the most recent response XML or stopping (or unstopping) all action. IMOs now expose an api function at window.imoapi.api_XXX where XXX is the IMO Number. This function takes a single object as an argument. The object must have a field ‘methodName’ set to an available method. The response is always an object with o.success= 0 or 1 and o.msg= a message related to the command. Available methods are as follows:

methodName Required Parameters Returns

getResponseXml – gets the most current result xml.

o.methodName=’getResponseXml’ Object with o.msg=responseXml o.success=0 or 1

stopAction o.methodName=’stopAction’ Object with o.msg= a message confirming that action has been stopped. o.success=0 or 1


unstopAction o.methodName= ‘unstopAction’ Object with o.msg= a message confirming that action has been restarted. o.success=0 or 1 Note that this only works if action has already been stopped.

setHist – Used to set the result xml inside an IMO.

o.methodName=’setHist’ o.hist = XML history string.

o.success=0 or 1 o.msg = a message.

doIFrameMsg o.methodName= ‘doIFrameMsg’

o.actn = actionCodeTypeId o.int1, int2, int3 = int 1, 2, or 3 for the action code. o.str1, str2, str3 = string 1, 2, 3 URL-encoded.

o.success=0 or 1 o.msg = a message.

Example: To obtain result XML for IMO 679, you would do something like this: function getResponseXmlFromIMO() { var fcn = window.imoapi.api_679; if( fcn ) { var out = fcn.call( this, {methodName:'getResponseXml'} ); alert( 'Success Code: ‘ + out.success + ‘, ResponseXml: ' + out.msg ); } else alert( 'API fcn not found! ' ); } Note: The IMO exposes the window.imoapi object only if a hybrid or html5-only deployment is used to embed the IMO in a webpage. If you are embedding a flash-only IMO directly into a webpage, you must be sure to create the window.imoapi object yourself in the hosting webpage as follows: // use this as the ID of the <object> tag for the Flash object. var playerId = 'g2Player'; window.imoapi={};


eval( 'window.imoapi.api_IMONUM=function( o ) { return getSwfMovie( \'g2Player\').doApiCall( o ); } ' ); function getSwfMovie( id ) { if (navigator.appName.indexOf("Microsoft") !== -1) { return window[id]; } else { return document[id]; } } IMONUM should be replaced with the IMO number. Allowing for IMO to Server Cross-Domain Communications IMOs can be hosted on one web server and embedded into the HTML on another web server, just like images or other graphics assets. Hence, their originating domain (where the IMO is hosted) can be virtually anything and can be different from the domain of the hosting webserver. In this case, however, the IMO would be sending messages to a non-originating domain. Both Flash and HTML prevent IMOs from communicating to a non-originating domain unless certain actions are taken on the non-originating server. So, in order to enable an IMO to communicate with a server for reporting purposes, the following should be set up on the server if the web server domain is different from the IMO domain:

1. For flash IMOs, a crossdomain.xml file authorizing the IMO must be present in the root directory.

2. For HTML5, the non-originating server must respond with the “Access-Control-Allow-Origin” http response header set to a setting that allows the IMO to access it.

To allow for universal access, both the cross domain and “Access-Control-Allow-Origin” http response headers should be set to “*.” Having the IMO Verify an embedded eventid with a third-party server This feature has been implemented to ensure that the IMO can authenticate itself with a 3rd party server every time it is loaded into a web browser. This feature is used to prevent ‘theft’ or unauthorized use of an IMO. When the IMO is configured for event verification, it will make an HTTP POST Transaction to the 3rd party server as set in the Main Settings “Embedded EventId Verifiy URL” with the following parameters:


eventid The eventid provided to the IMO via javascript from the host webpage

tran Verify

The target server should respond with a the word SUCCESS for valid eventids and DENY for invalid eventids. This way, an event id can be turned off by the server after a certain time or after completion and the IMO will not operate. Note that if the “ Embedded EventId Verifiy URL” is set in the Main Settings for the IMO, and an eventid is NOT passed to the IMO via the web page, and the IMO is operating in a standalone http mode without reporting to a server, the system will automatically disable itself. This also prevents unauthorized use of the IMO. Handling File Uploads from the IMO IMOs can include a ‘File Upload Button’ allowing the user to select a file for upload. Just like an HTML form, the IMO will not upload the file until a ’submit’ button is clicked by the user. Additionally, IMOs can now capture media directly inside the IMO – images, audio, and video can be captured. These binary files are also uploaded to the server. However, the file is uploaded using the XMLHttpRequest object, not directly through an HTTP Request.

• Works only in HTML5 implementations.

• Sends via HTTP Post using Multipart/form-data.

• Can be sent directly from IMO to server, or to JS Page if the fuplodurl starts with javascript:.

• If fupldurl starts with javascript: then the file is sent to a javascript method with the first parameter as an object with members: file (a javascript File object), ndseq, snseq, file, and blob ) the actual binary data is contained in either the file parameters (obtained from the file upload input element.files[0] member, or the blob for media capture-obtained values (ex: javascript:doUserFileUpload)

• The URL for file uploads should be passed at runtime using parameter: fupldurl

• The IMO needs to be configured to allow time for the uploads to complete before it exits. This can be done with a clip that has autoforwards selected to wait until all uploads are completed.

The HTTP Post that sends the file to the server will also contain the following identifying parameters:

• idn - the IMO number

• eventid - the event identifier provided at runtime

• ndseq - the ndseq number for the interaction

• snseq - the snseq number of the file upload


Media capture operations also send the following parameters:

• blobtype – mimetype for blob

• blobsize – in bytes

• blobfile -- the actual bytes. File upload operations include the following parameters:

• fulinput_" + ndseq + '-' + snseq = the ‘name’ of the FileUpload input element used to capture the file.

The XmlHttpRequest that uploads the file is performed by the IMO itself. However, these operations can be passed to the hosting webpage instead by setting the fupldurl IMO parameter to start with javascript:methodName. This method is called with the following parameters: (ndseq,snseq,file,blob). Note that the actual file is either in the file object or the blob object. For more information, see the Critical Upates Blog at http://clicflicupdates.blogspot.com/ Capturing Error and Other Messages from the IMO

A hosting webpage can capture log messages from the IMO via the runtime statusfcn parameter. This function receives an Object parameter with the status field set to ‘msg.’

All ‘msg’ type status objects have the following fields:

eventid - the eventid provided at runtime for this imo. level - 0=error, 1=warning, 2=info text - the actual message. stopaction – 0=action not stopped, 1=action has been stopped due to error

A simple example of a statusfunction is:

function imoStatusFcn( o ) {

var status=o.status;

if( status==='msg' ) {

var msg = o.text;

var level = o.level;

var eid = o.eventid;

var stopped = o.actionstopped===1;

if( (msg) && (eid) )

sendLogMessage( msg, level, eid);


if(stopped)

alert( ‘Action has been stopped due to an error’ );

}

}

In the above the function sendLogMessage() would be something you write to pass the log message back to the server, typically using XMLHttpRequest.


APPENDIX A – XML Document From IMO Format An XSD with the result XML format can be found at: https://sim.hravatar.com/tb/misc/descriptor/imo_reportingxml_latest.xsd The following defines the XML that is sent by the HR Avatar IMO directly to a third party source when a reporting event occurs during an interaction event: <clicflic id="IMO id defined by clicflic alphanum (removed in current version of IMO code)" actid=”Alternate unique IMO id defined by HR Avatar alphanum” deploydate=”The date that the IMO was deployed from the HR Avatar authoring system” name="Name of IMO" imonum=”the imo number. If present, must match the imo number of the loaded imo” swpltfrm=”software platform type, either as3 or html5”>  <event id="unique event id" xref="unique viewer identifier" altevtref=”alternate unique event identifier” hstpgurl="Host Page URL" points=”points assigned” pctcomplete=”Percent Complete” ttime=”Total Time So Far in Seconds” lastrnseq=”Seq Id of the last Clip played or last ordered clip played if ordered clips are present” lastresordr=”Order number of last ordered clip that was played” resorder=”Order number of most recently played ordered clip” rstrtndseqlst=”Comma-delimited list, in order, of the first rendered clip seq ids for each restart of an imo administration. Used for troubleshooting restart issues.” rstrttmstmplst=”Comma-delimited list of timestamps for all IMO restarts. Used for troubleshooting restart issues. uahistory=”Comma-delimited” list of all user agent codes used for each reload, one for the initial load and one for each reload. User agent codes are listed in Appendix C. minverhistory=”Comma-delimited list of all minor version numbers for this IMO,

in order – one for the initial load and one for each reload. acc1=”state variable 1 most recent value” acc2=”state variable 2 most recent value” acc3=”state variable 3 most recent value” acc4=”state variable 4 most recent value” … acc12=”state variable 12 most recent value” tmstmp=time of initial IMO load, millisecs since midnight 1/1/1970

tmrmax=current time limit (can be changed by interactions)



> <upperlayer>a state variable, with ~ delimited ndseq of all interactions currently visible in the upper layer. This is needed for restarts in the middle of an IMO since the upper layer is not synchronized with a specific clip. </upperlayer> < intnsshown>~ delimited ndseq of all interactions that have been displayed at least once. This is needed to ensure that state variable adjustments made when an interaction is displayed the first time are only made once, even during restarts. </ intnsshown> < dlydintns>~ delimited ndseq of upper layer interactions that have been set to

appear after a timer expires. Needed to ensure these interactions are actually shown if there is an IMO restart.

</ dlydintns> </event> <user>  <name>Name</name> <fn>First Name</fn> <ln>Last Name</ln> <ph>Phone Number</ph> <em>Email</em> <ques>Question Text</ques> <cmpny>Company Name</cmpny> <st>Street Address</st> <st2>Street Address 2</st2> <cty>City</cty> <state>State</state> <ctry>Country</ctry> <zip>Zip or Postal Code</zip> <resume>Resume</resume> <cust1>Custom Field 1</cust1> <cust2>Custom Field </cust2> ….. <cust49>Custom Field </cust49> <cust50>Custom Field </cus50> </user> <history>  <{custom xml name} attributes same as intn below>TEXT INPUT String (if any, see note below regarding format)</{custom xml name}> <intn

sq="interaction id" pass="pass number – always 1"

chcclk="click number for this pass – Always 0 for clips, 1 for interactions" crct="0 or 1 correct/incorrect, 1 means correct, -1 means not answered, -2 means timed out" isc="Number. Score associated with this interaction item"

ian=Number of “Items” that have been answered on this interaction. (SimBuilder IMOs with competencies assigned only).

ito=Total number of “Items” on this interaction (SimBuilder IMOs with competencies assigned only). u=”Text-based unique Id assigned to this interaction (if any)” cg=If a clip group is assigned to the active clip when this interaction is active, the clpgrp is included here. ct="Seconds taken from time interaction presented to response" desired="0 or 1 for this is a desired interaction item 1 means yes" id="interaction id + '_' + selected interaction item id" ns="interaction id" ss="selected interaction item id" nns="interaction id of targeted Interaction or Clip to show/play next" clkaction="Id code for what action was taken when this interaction was clicked" pss=”If history recording mode is unique interactions, this is a list of ~ delimited snseq values of previously selected interaction items from this interaction. This becomes useful when the same item is exposed multiple times and you need to know which choices have been selected in the past. pc=”Percent Complete ex 77.5” pts=”Outcome Points Assigned” sv=”State Var 1 Value~State Var 2 Value ~…~State Var 12 value tmstmp=milliseconds since midnight 1/1/1970, for time of first click> TEXT INPUT String (if any. See below) </intn> <clip sq="clip id"


pass="pass number – always 1" h="number of seconds the clip segment was watched for." id="clip id + '_' + clip segment id" u=”text-based unique Id assigned to this clip (if any)”

cg=If a clip group is assigned to this it’s included here. ns="clip id" sns="clip segment id" nns="targeted interaction or clip to play/show next" o=”integer ordered clip number of this clip (used for restarts)” pc=”Percent Complete ex 77.5” pts=”Outcome Points Assigned” pss=”If history recording mode is unique interactions, this is a list of ~ delimited snseq values of previously displayed clip segments from this clip. This is needed to ensure there is a record of all clip segments that were played from a clip even when there is only one ‘clip’element in the xml. sv=”State Var 1 Value~State Var 2 Value ~…~State Var 12 value tmstmp=milliseconds since midnight 1/1/1970, for time of first presentation of clip /> </history> <!— cronhist is only present if the history recording mode is unique interactions. Contains the most recent 20 interactions and clips, in order. Repeated interactions and clip segments appear as separate itn or clp elements. → <cronhist> <itn u=”Text-based unique Id assigned to this interaction (if any)” ct="Seconds taken from time interaction presented to response"

ns="interaction id" pc=”Percent Complete ex 77.5”

ss="selected interaction item id" src=”ndseq-snseq” of the clip segment that was playing when this interaction was activated or clicked. sv=”~ delimited series of state variable values, in order, if present” tmstmp=milliseconds since midnight 1/1/1970, for time of click > TEXT INPUT String

</itn> <clp u=”text-based unique Id assigned to this clip (if any)” h="number of seconds the clip segment was watched for" ns="clip id" pc=”Percent Complete ex 77.5” o=”integer ordered clip number of this clip” ss="clip segment id" src=”this is a code that identifies what caused this clip to be displayed, in the format: ndseq-subseq-actioncode” Action code is the click action for an


interaction item that was clicked, or a set of codes for other things that can initiate a clip presentation. See Appendix B for codes. sv=”~ delimited series of state variable values, in order, if present” tmstmp=millisecs since midnight 1/1/1970 GMT, for time of presentation /> </cronhist> </clicflic> Note that these attribute names changed on 19 June 2019. These changes only apply to HTML5 implementations, as Flash is no longer supported. So, any Flash implementations or legacy HTML5 implementations will continue to use the old attribute names, which are listed in the XSD. For additional information, please refer to the XSD at: https://sim.hravatar.com/tb/misc/descriptor/imo_reportingxml_latest.xsd Also, some of the above attributes are only sent when the IMO is operating in test mode. If there is no data available for a specific field, then it is not included in the xml. In some cases, 0 means 'no' and 1 means 'yes' Note that Interaction Id and Interaction Item Id are two different things. Remember that an interaction contains one or more interaction items. Interaction Item Ids are only unique within their interaction. User text input format Checkboxes, combo boxes, radio buttons, and text values entered by the viewer in form element interaction items in an interaction are included as a packed string inside a text node for a given interaction history record. This packed string used the following format:

− Delimited by tilde ~ characters. (previous versions used semicolons)

− interaction item id for the interaction item containing this form element

− URL-Encoded text – for the input from the viewer.

− Uses these substitutions within the content:

− @#@ = ~ [this avoids conflicts with the text str delimiter (~)]

− &#& = ^ [this avoids conflicts with the packed str delimiter (^, see appendix b)]

− $#$ = | [this avoids conflicts with the other packed str delimiter (^, see appendix b)]

If an interaction has a checkbox interaction item, the text input string would include the id of the interaction item, and either true or false, depending on whether it was checked when submitted. If an Interaction has a FileUpload interaction item, the text input string for that interaction item contains filename (with extension for file upload or without extension for media capture);size in bytes;Mime Type, all URL-encoded. An example is: 3~myfile.txt;4349;text/plain (before



URL encoding). If an interaction has any number or radio button or highlighted radio button interaction items, the text input string would include the id of each selected radio button or highlighted radio button interaction item, and the word 'true.' If an interaction has any number or combo box interaction items, the text input string would include the id of each combo box interaction item, and the 'value' of the selected entry. If an interaction has drag/drop interaction items. Any drag target interaction items that had draggable interactions dragged on top of them would be included in the text input string in the format: id of drag target and then (delimited by ~) all ids of each draggable item dragged on top of that target, separated by commas and then URL encoded, then the id of the next drag target (following a ~), etc. If an interaction item is a “pin image” format, where the user clicks or touches a spot on the screen and a pin is dropped as an image, the x,y coordinates of the actual click are presented as id~x,y,seconds. If there is more than one pin in the interaction and both are ‘pinned’, a ~ separates the info. Id1~x,y,seconds~id2~x,y,seconds. The x,y coordinates are relative to an image within the interaction designated as the pin cushion image. The seconds values are the time it takes to accept the pin. When the last pin is accepted (with submit button), the full submit is processed. If an interaction item is a “clickstream” format, where the user performs one or more clicks on one or more interactions before submitting, the interaction item captures this click stream in a format of

clickstream interaction item id~clkdnodeseq, clkdsubnodeseq, clkd node input string for the click that submitted the clickstream interaction item. If there was a hot key submit that caused the clickstream interaction item to submit the value is

clickstream interaction item id ~‘HKM;a;c;s;key’ where a means ‘ALT’, c means CTRL, s means SHFT, and key=asci keyCode. a, c, and s are all either 0 or 1. If the interaction item is an “IFrame” format, the user performs some action inside an iframe located inside the IMO and the internal webpage (presumably served by a server) eventually sends information back to the IMO to be included in the result xml. The format depends completely on the purpose of the iframe. The format is: Interaction item id ~ text from the iframe (URL encoded). Note that interactions with combo boxes, check boxes, text boxes, radio buttons or highlighted radio buttons must have a submit button interaction item in order for the form input values to be recorded.


It is expected that systems will 'know' how to correlate the interaction item id with the field that it represents. This data is available in the authoring system.


Appendix B – Click Action Codes and Action Codes

Click Action Codes 0 – no action 1 – show clip 2 – show interaction 3 – open external URL 4 - download file 5 - jump to time in clip 6 – display share panel 7 - call javascript function 8 – show feedback clip 9 – hide interaction 10 - pause clip 11 – show comments panel 12 – previous clip 13 – next clip 14 – fast forward 15 play clip 16 – go to full screen mode 17 – toggle captions 18 -- toggle font size 19 – issue HTTP GET request 20 -- play sound 21 -- go to previous ordered clip. 22 – go to next ordered clip 23 – play interaction item 24 – show or hide interaction item 25 -- play swf 26 – replay current clip 27 – go to next clip group 28 – go to previous clip group 29 – go to most recent ordered clip 30 – go to highest ordered clip 31 – rerender current clip 32 -- perform display action only 33 – video button play pause Action Codes 901 – Clip autoforward from another clip segment, timed from clip end. 902 – Clip autoforward from another clip segment, timed from clip start. 903 – Clip initiated by a global timeout. 904 – Clip initiated by a previous keyboard action, previous in order. 905 – Clip initiated by a next keyboard action, next in order. 906 – Post-Preloader Autoforward 907 – Clip appearance timeout. Clips can be set to appear X seconds after start of IMO.


908 – Clip initiated by a interaction-level timeout.


Appendix C – User Agent Codes

0=unknown, 1=iPhone Safari, 3=Android mobile 4=ipad Safari, 5=blackberry 6=symbian, 7= 8= 9=IE 8 or lower 10=Safari Desktop 11=Chrome 12=Firefox 13=Opera 14=Safari ipod 15=android tablet 16=windows phone 7 17=IE 9 18=Opera Mini (bad) 19=windows phone 8 20=silk 21=nook 22=Opera Mobile 23=IE 10+ 24=Chrome mobile 25=Firefox mobile 26=IE 10+ mobile 27=Blackberry 10 - phone version, Supports flash. 28=Blackberry Playbook - this is the blackberry tablet. Treat same as iPad. Supports flash.


Appendix D – Tab Indexes and Accessibility Prior to Feb 2018, ADA and Section 508 accessibility was only available via the Flash implementation of the IMOs. Testing systems could ask the candidate if they required accommodation and force Flash to be used. However, as of 2018 (and probably for some time before) Flash no longer works properly with most screen readers. This is because of the gradual phasing out of Flash by Adobe and most major web browsers. As a result, as of Feb 2018, the HTML5 code is now the preferred accessibility implementation. Flash should no longer be used for this purpose. All accessibility features of the HTML5 implementation are turned on by default and no action is necessary to use a screen reader. IMOs compiled before 2018 should be re-compiled. Additionally, the base HTML5 script should be replaced with a newer version. Regarding tab indexes, only relevant widgets within the IMO are set for tab stops. Tab indices within the IMO start at 1000 and continue through 30,000. This means that if you are embedding an IMO within a webpage, you should set all tab indices prior to the IMO between 1 and 1000, and all tab indices you want to be accessed after the IMO to 30,000 – 32,767 which is the max allowed tab index.

Documents

Reporting API for External Web Page Integrations...This is a new “form” element that allows the ... information on the format of this new attribute. ... HTML5 IMOs using the new