Working with the Experience API (xAPI)

This section describes how to work with the xAPI elearning specification. This Experience API, known as xAPI, allows content developers to collect data based on the learning experience of their users. The section includes information about how to publish with the xAPI options and understanding the xAPI experience statements. For the latest specifications, documents, and explanations of terms, visit the official xAPI website (http://tincanapi.com/).

Publishing with the xAPI options

You need to publish to xAPI to enable the automated and manual xAPI statements. Follow the steps described in Publishing to xAPI to prepare project for publishing to xAPI.

Most of the automatic xAPI statements are controlled through the publishing options when you publish a project to xAPI. These options are grouped together on the xAPI Options tab after you click Publish:

Conformance Level	This field is disabled.
Launch course in separate window from LRS	Select this option if you want the published project to be launched in a new window. When this option is selected, and the user exits the published project, the window will close, and the user will be returned to the LRS.
Report test/survey question interaction to LRS	Select this to record interaction data for the questions contained in the graded test being submitted to the LRS. Interaction data includes the following information for each graded question: User's answer Whether the user's answer is correct or not Time the question was answered Amount of time the user spent on the page containing the answer
Prompt the user to navigate to the last viewed page	Select this to enable the automatic bookmarking feature for the published project. When this is selected, and the user is returning to the published project within the LRS, the user will have the option to skip to the page he or she last viewed within the published project.
Activity ID	Specify the ID of the course as it will be known within the LRS .
Activity Name	Specify the title of the course as you want it to be displayed within the LRS .
Activity Description	Specify the description of the course’s contents as you want it to be displayed within the LRS .

Consider the following when completing the options on xAPI Options tab:

Notice that the Activity ID, Activity Name, and Activity Description for the course can be set here. The options are used as the context for other statements. When creating the Activity ID, be sure to follow the rules for an IRI (International Resource Identifier), such as avoiding spaces and special characters.
The option Append timestamp to interaction to create a unique ID is always disabled so that a question always reports answers with the same Activity ID.
An attempted activity statement is sent automatically when the course is started. It is sent for the activity specified in the Course Information section (specified by Activity ID, Activity Name, and Activity Description) of the xAPI publishing options.

When the option Prompt the user to navigate to the last viewed page is selected, your published course can report a xAPI statement with the verb experienced for each page visited by a learner. The activity in this is the HTML page name and it is URI-encoded so it can be used for the Lectora Online bookmarking function.

If you want to track progress through the course, add these two actions at the project level:

On Show - xAPI Statement - attempted - VAR(CurrentPageName)
On Hide - xAPI Statement - completed - VAR(CurrentPageName)

Questions inside of a test or survey will be reported when answered if the option Report test/survey question interaction to the LRS is selected. The question text and the response are stated in the xAPI statement.

The test must be graded, but it does not need to be included in the overall score.
Additionally, the ActivityContext - Parent statement subsection is set to its test’s activity.

Sending Passed or Failed Test Statements

Passed or failed xAPI statements will automatically be sent for tests that are set to be graded. The score is set along with the verb passed or failed. The object display name is the name of the test. The ID is the IRI of the activity with the name of the test added to it. (See examples below.)

The result score properties for min to 0 and max to 100 are all set to 0 by default. The Lowest Passing Score (%) field (located on the test's Results tab) should always be included even if it is set to 0 (in case of none correct).

Sending Completed, Passed, or Failed Activity Statements

When you set the AICC_Lesson_Status variable, an xAPI statement is sent. The following conditions will determine what type of statement is sent:

You can use a modify variable action to set AICC_Lesson_Status to completed, passed, or failed. If this is done, the course will send a corresponding Completed or Passed or Failed statement.
Setting AICC_Lesson_Status to passed or completed will set the xAPI statement’s result.completion to true and the result.success to true. If AICC_Lesson_Status is completed and the score is less than the AU mastery score, result.success will be false.
If AICC_Lesson_Status is set to failed, the xAPI statement’s result.completion is set to true and result.success is set to false.
The score should be included in the completion statement if it exists if you have a graded, included test or if you manually set AICC_Score.

Sending an xAPI Statement

You can send an xAPI statement from any location in the course. It will default the common xAPI statement elements allowing you to specify a verb and an object. This can be triggered on one of the many triggers available for actions. If you need full control over the statement and all its values see Specifying verbs and objects below.

Specifying verbs and objects

Lectora Online uses the ADL definitions for verbs. Additionally, any verb name can be entered. Entered verb names are appended to the ADL namespace so any future ADL verbs can be used, or you can use your own unique verb. (The LRS would not validate the verb and would allow you to report on it; therefore allowing the use of that namespace.)

For more information on verbs, visit http://www.adlnet.gov/expapi/verbs.

For the object portion of the statement, you can use any of the dynamic variables using advanced edit and the variable macros. You can also use text to report on any activity. This object field will be the activity identifier. To ensure this is a valid IRI, a minimal replacement of characters is done using this expression:

ActivityID (the location of the Activity IDs)

Consider using conditional actions and action groups for the ability to do complex tracking scenarios.

Specifying additional statement values

ActivityContext values are automatically set.

Sending a xAPI statement and dynamically updating the statement

Using the run Javascript action, you can customize and dynamically update the xAPI statement as you go through the project with your learner by using variables defined in project. This allows you to easily set up templates that will satisfy any use case.

Below is a simple but effective example of the Javascript that you can execute using the action.. This javascript will create the statement and then send the statement that you created.

            var stmt=

{
   "verb": {
     "id": VarxAPIVerbID.getValue(),
     "display": {
        "und": VarxAPIVerbDisplay.getValue()
     }
  },
  "object": {
    "definition": {
      "name": {
         "en-US": "xAPIandLODemo"
      }
   },
   "id": "http://uniqueurl.com/xAPIandLoDemo",
   "objectType": "Activity"
 },
   "result": {
    "score": {
    "scaled": (parseInt(Test_1_Score.getValue()) / 100)
   },
   "completion": true,
   "success": true
  }
}

var tcAPI = window.parent.frames['titlemgrframe'];
var tc_driver = tcAPI.tc_driver;

tcAPI.TinCanSendStatement(tc_driver,stmt,function(xhr){});

The above statement contains some function calls to get the value of Lectora Online variables. These could also be static string values, for example if you just wanted to specify the verb and other values in the statement.

Below are two options for customizing the xAPI statement:

VarxAPIVerbID.getValue()

This uses the user defined variable xAPIVerbID. Use the same Var prefix as if you were referencing the variable in all the other actions. You can set this variable to any verb you want. Make sure that you do both the ID and the Display.

In this example, ID is an URI such as http://adlnet.gov/expapi/verbs/answered

(An example corresponding Display is answered.)

(parseInt(Test_1_Score.getValue()) / 100) This uses a reserved variable of Test_1_Score to send the score that they received on the test. (This does not have the Var prefix as it is not a user-defined variable. Additionally, the Var is automatically prepended to it when it is published.)

Getting additional information

For more information about xAPI statement specification, visit https://github.com/adlnet/xAPI-Spec/blob/master/xAPI.md. For more information about the xAPI statement generator and tester, visit http://tincanapi.com/statement-generator/.

xAPI Statement Output Examples (from SCORM Cloud)

2014-11-05T04:05:36.259
Joe King passed 'http://www.uniqueurl.com/xAPI%20Template' with score 50
2014-11-05T04:05:36.256
Joe King incorrectly answered 'Survey Question 1' with response 'true'
2014-11-05T04:05:36.254
Joe King incorrectly answered 'My Test Question 2' with response 'false'
2014-11-05T04:05:36.251
Joe King correctly answered 'My Test Question 1' with response 'true'
2014-11-05T04:05:34.803
Joe King sent 'Custom-xAPI-Statement'
2014-11-05T04:05:34.047
Joe King experienced 'xAPI Actions Page'
2014-11-05T04:05:31.994
Joe King experienced 'After Survey Page'
2014-11-05T04:05:27.433
Joe King experienced 'Last survey page'
2014-11-05T04:05:25.582
Joe King experienced 'Test 1 Fail'
2014-11-05T04:05:21.783
Joe King failed 'Test 1' with score 50
2014-11-05T04:05:17.391
Joe King experienced 'Last test page'
2014-11-05T04:05:12.855
Joe King experienced 'Page 1'
2014-11-05T04:05:10.555
Joe King experienced 'Page 1'
2014-11-05T04:05:09.837
Joe King attempted 'http://www.uniqueurl.com/xAPI%20Template'

Attempted Course Statement (auto)

2014-11-05T04:05:09.837
			Joe King attempted 'http://www.uniqueurl.com/xAPI%20Template'
			{
			    "id": "3d26bd57-0558-4a02-934d-501c7d85d3b7",
			    "actor": {
			        "name": "Joe King",
			        "account": {
			            "homePage": "http://cloud.scorm.com/",
			            "name": "ZUASCUHYVJ|wieloch@trivantisboca.com"
			        },
			        "objectType": "Agent"
			    },
			    "verb": {
			        "id": "http://adlnet.gov/expapi/verbs/attempted",
			        "display": {
			            "en-US": "attempted"
			        }
			    },
			    "context": {
			        "registration": "61d426da-436a-4b2a-8daa-ce94f6082f2f",
			        "contextActivities": {
			            "grouping": [
			                {
			                    "id": "http://www.uniqueurl.com/xAPI%20Template",
			                    "objectType": "Activity"
			                }
			            ]
			        }
			    },
			    "timestamp": "2014-11-05T04:05:07.734Z",
			    "stored": "2014-11-05T04:05:09.837Z",
			    "authority": {
			        "name": "Joe King",
			        "account": {
			            "homePage": "http://cloud.scorm.com/",
			            "name": "ZUASCUHYVJ|wieloch@trivantisboca.com"
			        },
			        "objectType": "Agent"
			    },
			    "version": "1.0.0",
			    "object": {
			        "id": "http://www.uniqueurl.com/xAPI%20Template",
			        "definition": {
			            "name": {},
			            "description": {}
			        },
			        "objectType": "Activity"
			    }
			}

Attempted Course Statement (auto)

			2014-11-05T04:05:10.555
			Joe King experienced 'Page 1'
			{
			    "id": "3ed638c0-a422-41e5-b7d7-42bf43e59b39",
			    "actor": {
			        "name": "Joe King",
			        "account": {
			            "homePage": "http://cloud.scorm.com/",
			            "name": "ZUASCUHYVJ|wieloch@trivantisboca.com"
			        },
			        "objectType": "Agent"
			    },
			    "verb": {
			        "id": "http://adlnet.gov/expapi/verbs/experienced",
			        "display": {
			            "en-US": "experienced"
			        }
			    },
			    "context": {
			        "registration": "61d426da-436a-4b2a-8daa-ce94f6082f2f",
			        "contextActivities": {
			            "grouping": [
			                {
			                    "id": "http://www.uniqueurl.com/xAPI%20Template",
			                    "objectType": "Activity"
			                }
			            ],
			            "parent": [
			                {
			                    "id": "http://www.uniqueurl.com/xAPI%20Template",
			                    "objectType": "Activity"
			                }
			            ]
			        }
			    },
			    "timestamp": "2014-11-05T04:05:08.506Z",
			    "stored": "2014-11-05T04:05:10.555Z",
			    "authority": {
			        "name": "Joe King",
			        "account": {
			            "homePage": "http://cloud.scorm.com/",
			            "name": "ZUASCUHYVJ|wieloch@trivantisboca.com"
			        },
			        "objectType": "Agent"
			    },
			    "version": "1.0.0",
			    "object": {
			        "id": "http://www.uniqueurl.com/xAPI%20Template/a001_page_1.html",
			        "definition": {
			            "name": {
			                "en-US": "Page 1"
			            }
			        },
			        "objectType": "Activity"
			    }
		}

Passed / Failed Test Statement (auto)

2014-11-05T04:05:21.783
			Joe King failed 'Test 1' with score 50
			{
			    "id": "1820c7e8-6509-4c45-b672-af7ae301ec40",
			    "actor": {
			        "name": "Joe King",
			        "account": {
			            "homePage": "http://cloud.scorm.com/",
			            "name": "ZUASCUHYVJ|wieloch@trivantisboca.com"
			        },
			        "objectType": "Agent"
			    },
			    "verb": {
			        "id": "http://adlnet.gov/expapi/verbs/failed",
			        "display": {
			            "en-US": "failed"
			        }
			    },
			    "result": {
			        "score": {
			            "raw": 50,
			            "min": 0,
			            "max": 100
			        },
			        "success": false,
			        "completion": false
			    },
			    "context": {
			        "registration": "61d426da-436a-4b2a-8daa-ce94f6082f2f",
			        "contextActivities": {
			            "grouping": [
			                {
			                    "id": "http://www.uniqueurl.com/xAPI%20Template",
			                    "objectType": "Activity"
			                }
			            ],
			            "parent": [
			                {
			                    "id": "http://www.uniqueurl.com/xAPI%20Template",
			                    "objectType": "Activity"
			                }
			            ]
			        }
			    },
			    "timestamp": "2014-11-05T04:05:20.030Z",
			    "stored": "2014-11-05T04:05:21.783Z",
			    "authority": {
			        "name": "Joe King",
			        "account": {
			            "homePage": "http://cloud.scorm.com/",
			            "name": "ZUASCUHYVJ|wieloch@trivantisboca.com"
			        },
			        "objectType": "Agent"
			    },
			    "version": "1.0.0",
			    "object": {
			        "id": "http://www.uniqueurl.com/xAPI%20Template/Test%201",
			        "definition": {
			            "name": {
			                "en-US": "Test 1"
			            }
			        },
			        "objectType": "Activity"
			    }
		}

Question Answered Statement (auto)

2014-11-05T04:05:36.251
			Joe King correctly answered 'My Test Question 1' with response 'true'
			{
			    "id": "a8af22bf-8e38-447c-8e6a-500c3673f867",
			    "actor": {
			        "name": "Joe King",
			        "account": {
			            "homePage": "http://cloud.scorm.com/",
			            "name": "ZUASCUHYVJ|wieloch@trivantisboca.com"
			        },
			        "objectType": "Agent"
			    },
			    "verb": {
			        "id": "http://adlnet.gov/expapi/verbs/answered",
			        "display": {
			            "en-US": "answered"
			        }
			    },
			    "result": {
			        "success": true,
			        "response": "true"
			    },
			    "context": {
			        "registration": "61d426da-436a-4b2a-8daa-ce94f6082f2f",
			        "contextActivities": {
			            "grouping": [
			                {
			                    "id": "http://www.uniqueurl.com/xAPI%20Template",
			                    "objectType": "Activity"
			                }
			            ],
			            "parent": [
			                {
			                    "id": "http://www.uniqueurl.com/xAPI%20Template",
			                    "objectType": "Activity"
			                }
			            ]
			        }
			    },
			    "timestamp": "2014-11-05T04:05:10.000Z",
			    "stored": "2014-11-05T04:05:36.251Z",
			    "authority": {
			        "name": "Joe King",
			        "account": {
			            "homePage": "http://cloud.scorm.com/",
			            "name": "ZUASCUHYVJ|wieloch@trivantisboca.com"
			        },
			        "objectType": "Agent"
			    },
			    "version": "1.0.0",
			    "object": {
			        "id": "http://www.uniqueurl.com/xAPI%20Template-Question_1_67_1415160320014",
			        "definition": {
			            "description": {
			                "en-US": "My Test Question 1"
			            },
			            "type": "http://adlnet.gov/expapi/activities/cmi.interaction",
			            "interactionType": "true-false",
			            "correctResponsesPattern": [
			                "true"
			            ]
			        },
			        "objectType": "Activity"
			    }
			}

Custom xAPI Statement from xAPI Statement Action

2014-11-05T04:05:34.803
			Joe King sent 'Custom-xAPI-Statement'
			{
			    "id": "6a108ff9-1bcc-4bb0-9021-732fb7bad775",
			    "actor": {
			        "name": "Joe King",
			        "account": {
			            "homePage": "http://cloud.scorm.com/",
			            "name": "ZUASCUHYVJ|wieloch@trivantisboca.com"
			        },
			        "objectType": "Agent"
			    },
			    "verb": {
			        "id": "http://adlnet.gov/expapi/verbs/sent",
			        "display": {
			            "en-US": "sent"
			        }
			    },
			    "result": {},
			    "context": {
			        "registration": "61d426da-436a-4b2a-8daa-ce94f6082f2f",
			        "contextActivities": {
			            "grouping": [
			                {
			                    "id": "http://www.uniqueurl.com/xAPI%20Template",
			                    "objectType": "Activity"
			                }
			            ],
			            "parent": [
			                {
			                    "id": "http://www.uniqueurl.com/xAPI%20Template",
			                    "objectType": "Activity"
			                }
			            ]
			        }
			    },
			    "timestamp": "2014-11-05T04:05:32.376Z",
			    "stored": "2014-11-05T04:05:34.803Z",
			    "authority": {
			        "name": "Joe King",
			        "account": {
			            "homePage": "http://cloud.scorm.com/",
			            "name": "ZUASCUHYVJ|wieloch@trivantisboca.com"
			        },
			        "objectType": "Agent"
			    },
			    "version": "1.0.0",
			    "object": {
			        "id": "http://www.uniqueurl.com/xAPI%20Template/Custom-xAPI-Statement",
			        "definition": {
			            "name": {
			                "en-US": "Custom-xAPI-Statement"
			            }
			        },
			        "objectType": "Activity"
			    }
		}

Passed / Compld / Failed Course Statement (auto)

2014-11-05T04:05:36.259
			Joe King passed 'http://www.uniqueurl.com/xAPI%20Template' with score 50
			{
			    "id": "6e8c000e-47d0-4b8c-842b-d9573422ce1b",
			    "actor": {
			        "name": "Joe King",
			        "account": {
			            "homePage": "http://cloud.scorm.com/",
			            "name": 
			"ZUASCUHYVJ|wieloch@trivantisboca.com"
			        },
			        "objectType": "Agent"
			    },
			    "verb": {
			        "id": "http://adlnet.gov/expapi/verbs/passed",
			        "display": {
			            "en-US": "passed"
			        }
			    },
			    "result": {
			        "score": {
			            "raw": 50,
			            "min": 0,
			            "max": 100
			        },
			        "success": true,
			        "completion": true,
			        "duration": "PT25.97S"
			    },
			    "context": {
			        "registration": "61d426da-436a-4b2a-8daa-ce94f6082f2f",
			        "contextActivities": {
			            "grouping": [
			                {
			                    "id": "http://www.uniqueurl.com/xAPI%20Template",
			                    "objectType": "Activity"
			                }
			            ]
			        }
			    },
			    "timestamp": "2014-11-05T04:05:33.714Z",
			    "stored": "2014-11-05T04:05:36.259Z",
			    "authority": {
			        "name": "Joe King",
			        "account": {
			            "homePage": "http://cloud.scorm.com/",
			            "name": "ZUASCUHYVJ|wieloch@trivantisboca.com"
			        },
			        "objectType": "Agent"
			    },
			    "version": "1.0.0",
			    "object": {
			        "id": "http://www.uniqueurl.com/xAPI%20Template",
			        "objectType": "Activity"
			    }
			}