xAPI Real-time Events#

Standardized Integration with xAPI#

We have chosen xAPI as one of the primary communication standards for real-time events since it has widespread industry support and usage for tracking and analyzing learning activity. Please see xAPI Architecture Overview for further information on xAPI.

Note

Although xAPI specifies a standardized format, it is a low-level transaction schema and relies on higher-level “profiles” applied on top of it. So the profiles for specific Activities, Verbs, Contexts, etc used by Open edX need to be contractually maintained. This can be ensured by a community maintained Router component.

Learning Record Store (LRS) - Future#

xAPI includes a specification for a Learning Record Store (LRS), which encapsulates a data store with APIs for storing and accessing xAPI data. While an LRS could be used for many different purposes, it can be used to train adaptive engines as shown in the diagram below.

The diagram above is enhanced with a new LRS component that receives events from the Open edX "Eventing" component and is accessed by adaptive engines for training purposes, using xAPI for both transactions.

We will not implement our own LRS. We will look into integration efforts with third party LRS services.

Statement API#

xAPI specifies 4 standard REST-ful JSON payload APIs, of which only the Statement API is needed for our purposes as that API is sufficient for tracking learning activity.

The Statement API has essentially the following parts: xAPI Actor, xAPI Verb, xAPI Object, xAPI Context, and xAPI Result.

xAPI Actor#

Although the Actor field can be either an Agent or a Group, we will primarily support only the Agent type, which is used for individuals performing an activity (xAPI Verb on an xAPI Object).

An Actor can be identified using Friend of a Friend (FOAF) vocabulary with either: (1) email address, (2) hash of email address, (3) OpenID URI, or (4) account with a homepage-scoped identifier. One of these is sent along with the Actor’s “name”. To be mindful of learner privacy, we will initially take a conservative approach and only send #3, with an Open edX anonymized unique identifier of the learner (Anonymized User ID).

In the future, if certain external systems require Personally Identifiable Information (PII), like the learner’s email address or name, then those may be conditionally sent with appropriate permissions. Adaptive engines, however, do not need PII.

Initially, we will exclude the “name” field. However, if we find that xAPI JSON parsers assume this field always exists, then we can include the field but provide a non-PII value, such as a copy of the Anonymized User ID.

Example#

Here is an example of an Actor JSON value that we would generate:

"actor": {
    "objectType": "Agent",
    "openid": "https://openedx.org/users/user-v1:<anonymized-user-id>",
    "name": "https://openedx.org/users/user-v1:<anonymized-user-id>"  # only include this field if necessary
}

See Deep Dive: Actor/Agent for more information on xAPI Actors.

xAPI Verb#

The Verb in xAPI is a past tensed value, identified by a URI from the xAPI registry and paired with a short display string. It denotes the action that was performed by the Actor on the Object in the statement. As best as possible, we will use standard and registered Verbs rather than creating custom ones. The chosen Verbs are documented in the Open edX Events section below.

The registry is automatically created from multiple profiles. For now, we will limit ourselves to only URIs prefixed by the following domains, in the following priority order (in case of conflicting names):

  • http://adlnet.gov

  • http://w3id.org

  • http://id.tincanapi.com

If, by any chance, a verb needed by Open edX does not exist in the registry, then we will create a pull request to recommend adding it to the central GitHub repository of xAPI Profiles.

Here is an example of a Verb JSON value that we would generate:

"verb": {
    "id": "http://adlnet.gov/expapi/verbs/answered"
}

Note

To keep the size of events as small as possible, we choose to avoid extraneous fields. For example, we intentionally exclude a “display” field in the example above.

See Experience API Deep Dive: Verbs for more information on xAPI Verbs.

xAPI Object#

Initially, the Object in an Open edX xAPI event will be an xAPI Activity, which is uniquely defined by a URI. (In the future, we may expand Objects to also be Actors in case of social interactions, and Statements in case of voiding.)

The id field is a unique identifier. The Open edX Events section has specifics on which Open edX identifier is used in each event.

The type of the Activity and the name of the Activity are included in the definition field. Similar to Verbs, the type of the Activity is a standard URI taken from the xAPI registry.

Here is an example of an Object JSON value that we would generate:

"object": {
    "id": "https://courses.openedx.org/xblock/block-v1:openedx+origami-folding+1T2018+type@problem+block@abcd",
    "definition": {
        "type": "http://adlnet.gov/expapi/activities/question",
        "name": {
            "en-US": "Question on mountain fold needed to create an origami crane base",
        }
    }
}

See Deep Dive: Object for more information on xAPI Object.

xAPI Context#

The Context field allows us to embed additional contextual information in each statement. See specifics in the Open edX Events section below since it varies by event type.

Here is an example of a Context JSON value that we would generate:

"context": {
    "registration": "https://openedx.org/enrollments/enrollment-v1:<anonymized-enrollment-id>",
    "contextActivities": {
        "parent": [{
            "objectType": "Activity",
            "id": "https://openedx.org/courses/course-v1:openedx+origami-folding+1T2018"
        }]
    }
}

See Deep Dive: Context for more information on xAPI Context.

xAPI Result#

The Result field specifies the score the user earned on an activity. Here is an example of a JSON value that we would generate for a problem type:

"result": {
    "success": false,
    "completion": true,
    "score": {
        "min": 0,
        "max": 50,
        "raw": 10,
        "scaled": 0.20
    },
    "response": "foo"
}

See Deep Dive: Result for more information on xAPI Result.

Open edX Events#

Currently, the Open edX system supports and maintains events that are sent to tracking logs, as described in Tracking Log Events.

Prioritized List of Events#

For this first iteration, we will focus primarily on the following events:

Event Field Mapping#

Please see the Open edx xAPI Events document for a detailed view of the mapping between the above Open edX events and their equivalent Open edX xAPI formats.