Support cmi5 specification

[k-jensen]

Subject of the issue/enhancement/features

Add support for the cmi5 specification.

1.0 Overview

cmi5 Implementation Flow for an AU (Assignable Unit)

(Figure from https://aicc.github.io/CMI-5_Spec_Current/flows/au-flow.html)

2.0 Requirements

To support cmi5, the extension should enable an Adapt course to:

• Meet all of the MUST requirements outlined in the official specification docs for an AU

https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/cmi5_spec.md#70-au-requirements

3.0 Acronyms

• LRS : Learning Record Store
• LMS : Learning Management System
• AU : Assignable Unit

4.0 Runtime Flow

What should happen when an Adapt course is launched from an LMS.
(With the adapt-contrib-xapi extension enabled and _specification set to "cmi5")

4.1 Read the URL params

The LMS should launch the adapt course with the following query params:

• fetch : Used to get the authentication token. This token will be used in the header of all requests to the LRS
• endpoint : The URL for the LRS. Used to send/read statements and state
• actor : The learner that launched the course from the LMS. This actor will be used for all xAPI statements
• registration : A registration ID corresponding to the learner's enrollment for the AU being launched. To be used in xAPI statements that require registration. Also used for requests to read/write state saved in the LRS.
• activityId : A unique ID generated by the LMS (should not match the AUs publisher ID defined in the course structure). Must be used as the ID property of the object in all "cmi5 defined" xAPI statements.

❓ How should we save these values? Set as model attributes on https://github.com/adaptlearning/adapt-contrib-xapi/blob/master/js/XAPI.js

4.2 Get the Auth Token

Before trying to communicate with the LRS, we need to used the fetch value provided by the LMS to get an authentication token.

• Make a POST request to the value of the fetch property.
  This POST request must only happen once.

The response should contain a JSON object with an auth-token property e.g.

{
  "auth-token": "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
}

This auth-token should then be used in all requests made to the LRS.

4.3 Set the xapiWrapper config

This plugin uses the xAPIWrapper.js library.
https://github.com/adlnet/xAPIWrapper

When loaded, the xAPIWrapper will check for some query params.

• It will look for endpoint and use it for the xapiWrapper.lrs.endpoint value
• It will look for the actor and use it for the xapiWrapper.lrs.actor value
• It will look for the registration and use it for the xapiWrapper.lrs.registration value

We need to do a little extra to handle our auth-token and activityId e.g.

  this.xapiWrapper.changeConfig({
    auth: `Basic ${this.get('auth-token')}`,
    activity_id: this.get('activityId')
  })

4.4 Read State Document

When launched the LMS will write a state document with details needed for the AU to send valid xAPI statements during it's session.
https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/cmi5_spec.md#xapi_state

• Make a GET request to ${theLRSendpoint}activties/state with query string params ?stateId=LMS.LaunchData (other params needed too, see xapiWrapper.getState(activityid, agent, stateid, registration, since, callback))

Example of LMS.LaunchData:

{
  "launchMode": "Normal",
  "masteryScore": 0.7,
  "moveOn": "Passed",
  "contextTemplate": {
    "contextActivities": {
      "grouping": [
        { "id": "http://www.example.com/LA1/001" }
      ],
      "extensions": {
        "https://w3id.org/xapi/cmi5/context/extensions/sessionid": "1234567890"
      }
    },
    "entitlementKey": {},
    "launchParameters": "Start=1,QuizMode=1,FastForward=On",
    "returnURL": "http://lms.example.com/returnURL.html"
  }
}

https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/cmi5_spec.md#1021-contexttemplate

10.2.1 contextTemplate

The AU MUST get the contextTemplate value from the LMS.LaunchData State document. The AU MUST NOT modify or delete the LMS.LaunchData State document. The AU MUST use the contextTemplate as a template for the context property in all xAPI statements it sends to the LMS. While the AU MAY include additional values in the context object of such statements, it MUST NOT overwrite any values provided in the contextTemplate. NOTE: this will include the session ID specified by the LMS.

• If a masteryScore is used, the "passed" or "failed" cmi5 defined statements MUST be based on the masteryScore provided
• If the launchParameters exist, the AU should attempt to get them https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/cmi5_spec.md#launchparameters

4.5 Read Agent Profile

https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/cmi5_spec.md#110-xapi-agent-profile-data-model

• set and use learner preferences

4.6 Order of xAPI Statements

• The "launched" xAPI statement should NOT be sent (This statement is sent from the LMS when using cmi5)
• The "initialized" xAPI statement MUST be sent as the first statement https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/cmi5_spec.md#first_statement_au
• Any number of custom xAPI statements can be sent during a session (cmi5 allowed)
• An AU MUST include the session ID provided by the LMS in the context as an extension for all cmi5 defined and cmi5 allowed statements it makes directly in the LRS. https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/cmi5_spec.md#9631-session-id
• The "terminated" xAPI statement MUST be sent when the session is ended

4.7 Return to URL

https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/cmi5_spec.md#1026-returnurl

• If the returnURL is provided in the LMS.LaunchData, the AU MUST attempt to get the returnURL value from the LMS.LaunchData state document. The AU MUST redirect the current browser window or frame to the returnURL when the AU is terminated if the returnURL is provided.

5.0 Properties schema update

5.1 Config

• "cmi5" option to be added to _specification
• help text to be updated, remove the "(coming soon)"

  "_specification": {
    "type": "string",
    "enum": [
      "xAPI"
    ],
    "default": "xAPI",
    "title": "Specification",
    "inputType": {
      "type": "Select",
      "options": [
        "xAPI",
        "cmi5"
      ]
    },
    "validators": [],
    "help": "Indicates whether the plugin should use standard xAPI or cmi5 profile."
  },
    "validators": [],
    "help": "(cmi5 only) Some useful help text."
},

https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/cmi5_spec.md#moveon
https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/cmi5_spec.md#9622-moveon-category-activity

6.0 Post Build actions

• tincan.xml should be deleted

6.1 cmi5.xml - The Course Structure

• a valid cmi5.xml should be created/edited e.g.

<?xml version="1.0" encoding="utf-8"?>
<courseStructure xmlns="https://w3id.org/xapi/profiles/cmi5/v1/CourseStructure.xsd">
    <course id="@@config._xapi._activityID">
        <title>
            <langstring lang="en-US"><![CDATA[@@course.title]]></langstring>
        </title>
        <description>
            <langstring lang="en-US">
                <![CDATA[@@course.description]]>
            </langstring>
        </description>
    </course>
    <au id="@@config._xapi._auID" moveOn="CompletedOrPassed">
        <title>
            <langstring lang="en-US"><![CDATA[@@course.title]]></langstring>
        </title>
        <description>
            <langstring lang="en-US">
                <![CDATA[@@course.description]]>
            </langstring>
        </description>
        <url>index.html</url>
    </au>
</courseStructure>

7.0 Resources

• The cmi5 Specification Profile for xAPI https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/cmi5_spec.md
• Understanding and Applying cmi5 in an xAPI Solution https://www.youtube.com/watch?v=KXZG3cJF7lI&t=4701s
• cmi5 Best Practices Guide https://adlnet.gov/assets/uploads/cmi5%20Best%20Practices%20Guide%20-%20From%20Conception%20to%20Conformance.pdf
• cmi5 AU runtime library https://github.com/RusticiSoftware/cmi5.js
• Collection and playground of resources https://app.mural.co/t/laerdal/m/laerdal/1699005657768/6d06ea3b18b3853d621219f88b29d233055e7245?sender=u799d3b387fda83345de09799

x.x TODO: make notes about...

• launchMode https://github.com/AICC/CMI-5_Spec_Current/blob/quartz/cmi5_spec.md#1022-launchmode
• How to test? new test harness html/js files?
• Should be compatible with both v0.11.2 and v1+ of the Authoring Tool
• Handling attempts
• Checklist: update readme, xAPI still works as expected
• Restoring interrupted sessions
• Add support for an "Exit" button in the navbar? to either close the window or redirect using the returnUrl from the LMS.LaunchData
• ❓ Should the _defaultLanguage from config be used to set <langstring lang="en-US"> in cmi5.xml?
• ❓ Should we aim to breakdown the https://github.com/adaptlearning/adapt-contrib-xapi/blob/master/js/XAPI.js file a bit?