An account definition in the actor is required. The account must:
include a homePage of "https://motar.io"
include the actor's MOTAR account name in the name field.
A verb ID must be from the xAPI library, located here. If your implementation requires additional verbs, please contact us and we can add your custom verbs to our allowed list.
An object definition must include the object's MOTAR API ID in its extensions definition. This is how MOTAR links your statement to the object internally. The object's id parameter can be a MOTAR URI or a URI linking the object to your system, if desired.
To make sure your statement is properly linked in MOTAR, you may include any additional IDs that are not directly part of the object definition in the extensions section of the context definition.
These URIs must be used in the id field of the object definition. You do not need to match the name or description of the object in your statement, these are arbitrary.
Use the extensions definition in either the context or object definition to add additional MOTAR API IDs. Although optional, adding these IDs is strongly recommended to ensure your statement is linked properly by the MOTAR API. These ID URIs are listed below.
Class (Education Class): https://www.dynepicdx.com/xapi/api-id/education-class
User: https://www.dynepicdx.com/xapi/api-id/user
xAPI v1
Create Statement
POSThttps://api.motar.io/edu/v1/xapi/statement
This endpoint creates an xAPI statement. See below for special keys needed for indexing your metrics.
Headers
Name
Type
Description
Authorization
string
Auth token generated by login.
Request Body
Name
Type
Description
timestamp
string
A parseable ISO date (eg. 2020-01-07T21:45:35.649Z).
actor
string
User ID of the actor performing the action.
verb
string
Action that the actor is carrying out on the object.
object
object
Target of the action the user is carrying out. This is expected to be a JSON object (stringified or raw).
{ success:true}
Object: There are a few keys you can attach to your object to ensure your statement is indexed to other MOTAR objects:
lessonId: this statement is part of a specific lesson. This is required for the statement to appear in a student's results in MOTAR.
classId: this statement happened in a specific class.
studentId: this statement was the action of a specific student in a class. If not provided, the API will attempt to guess the student ID as follows: take the user making the statement and take their newest class that is taking the lesson indicated by a provided lesson ID.
lessonResultId: this statement is part of a specific lesson result.
objectiveId: this statement is related to a specific course objective.
Object: Additionally, you can add certain flags to your object that will be respected and highlighted by the MOTAR Dashboard and/or other systems:
questionText: if the xAPI statement is about a certain question, you can include the question's text to index the statement to the relevant question. You must also include a lessonId for this indexing to be successful.
questionIndex: alternative to questionText, this accomplishes the same indexing but uses the array index of the question rather than the text.
error: indicates the statement is an error by the student.
assist: indicates an assist to the student.
safety: indicates a safety by the student.
knowledge: indicates a skill or piece of knowledge the student has demonstrated.
target: free text indicating an object that is not covered by the above IDs. For example, you can send in "Tool Control" to indicate the verb applies to a specific skill in your application.
Verb: If possible, re-use verbs to group statements together. For example, you can use the preset verb "Correct Item Selected" when the user picks up the correct tool in a simulation.
Other preset verbs:
Perfect Sequence: indicates a user aced a lesson sequence.
Incorrect Item Selected: opposite of "Correct Item Selected"
Repeated Steps: indicates a user repeated the steps in a module one or more times.
xAPI Used in Event Set module
MOTAR Event Set modules use xAPI. See here for more details on how to use xAPI statements to record user activity in a lesson.
Example Statements
Below are a few examples of how to create data-rich xAPI statements in MOTAR. Under each is a representation of how that statement will appear to MOTAR users. Note that the "verb" text is arbitrary and should be tailored to your application's actions, but re-using verbs throughout your application is highly recommended.
A student correctly picked up a tool in a VR simulation:
17:13:26 SAFETY: Entered Safety Area -> Left Wing Propeller
A student required their first prompt (assist) to carry out a task:
{"actor": "3a02cbb9ae4c2e157927d3259159bfa80793ecfebebd74ef89d4db65def37778dc592a8e0bee5b7b39608f5609446cf5f8832576d6a2b992d4919a42acc7e194e81ede86ea2aa670a1436be0678f2fa1ce","verb": "Required Prompt 1","object": {"lessonId":"ac5f1ba630fe00c39a1c938a22e80a8ba402e1e98b67597a7d4b66a670c510075639ebca09d275cd700f615f956512718ad53c561bb1ec697c5896386c31a850aafc865c1352981453e1d0e45a5ccbba13","assist":true,"target":"Pick Up Torque Wrench" }}
17:13:26 ASSIST: Required Prompt 1-> Pick Up Torque Wrench
A student learned knowledge from an NPC:
{"actor": "3a02cbb9ae4c2e157927d3259159bfa80793ecfebebd74ef89d4db65def37778dc592a8e0bee5b7b39608f5609446cf5f8832576d6a2b992d4919a42acc7e194e81ede86ea2aa670a1436be0678f2fa1ce","verb": "Briefed By NPC","object": {"lessonId":"ac5f1ba630fe00c39a1c938a22e80a8ba402e1e98b67597a7d4b66a670c510075639ebca09d275cd700f615f956512718ad53c561bb1ec697c5896386c31a850aafc865c1352981453e1d0e45a5ccbba13","knowledge":true,"target":"Do not pass under wing propeller" }}
17:13:26 KNOWLEDGE: Briefed By NPC-> Do not pass under wing propeller
