xAPI Overview¶

Each xAPI event object has the following sections:

id

a UUID (unique identifier) identifying this event object.

timestampe

a UTC date-time stamp telling when the event occurred, accurate to thousandths of a second.

actor

The person involved in the learning activity.

verb

The action that the actor performed.

object

The object affected by the action.

context

Additional information relevant to the event. In the case of Brightspace Data Streams, context includes information related to Brightspace. For example, context will give the Brightspace User ID number for actor.

xAPI documentation often uses I did this as a model for what an event is like. In this case, the actor is I, the verb is did, and the object is this.

As an example, consider a student logging in to a Brightspace session. The actor is the student, the verb represents logging in, the object specifies the Brightspace OrgUnit to which the student logged in, and the context provides other data such as the student’s Brightspace User Id number, the organization’s TenantID, and so on.

Special Types of Data Values¶

xAPI event objects produced by BDS typically contain several special types of data values (in addition to simple character strings):

UUIDs (Universally Unique Identifiers)

A UUID is an identifier unique to a particular object. For example, every event object is identified by a UUID. A UUID is an 128-bit number typically written in the form:

XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

where each X is a hexadecimal digit. UUIDs are documented in several standards, including RFC4122. The UUIDs produced by BDS should only be tested for equality or inequality; decomposing a BDS UUID in any way will not produce meaningful results.

URIs (Universal Resource Identifiers)

A URI is a string of characters that unambiguously identifies something, using a standard syntax. The best known type of URI is a URL, often known as a web address. A URL tells where to find a particular resource on the web; a URI identifies a resource but doesn’t necessarily tell where to find it. URIs often look like web addresses, but may not refer to an actual web page. For example, the verb in a BDS event object is represented by a URI such as:

https://api.brightspace.com/xapi/verbs/logged_in

This resembles a web address but doesn’t refer to an actual web page.

IRIs (Internationalized Resource Identifiers) and IRLs

IRIs are similar to URIs but are constructed using the full Unicode character set, rather than just ASCII characters. Similarly, an IRL is similar to a URL, but uses the Unicode character set.

URNs (Uniform Resource Names)

URNs are a type of URI that makes use of UUIDs. In BDS event objects, URNs are always expressed in the form:

urn:uuid:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Values of this type appear in various fields of BDS xAPI events.

Standard Information¶

The following are present in every event object:

"id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"timestamp": "yyyy-mm-ddThh:mm:ss.fffZ"

where:

id

is a UUID identifying this event uniquely within the event objects produced by BDS.

timestamp

tells when the event happened. This is the date-time when Brightspace originally registered the activity, not when the event object was posted by BDS. However, BDS is designed to post events as soon as possible after they take place.

timestamp is a string value that you should treat as an ISO 8061 formatted date-time string in the Z (UTC+0) time zone, with the addition of a three-digit millisecond value appended to the time value (before the Z time zone specifier).

Actor Information¶

The actor section of a BDS xAPI event object has the form:

"actor": {
        "account": {
            "homePage": "https://TTTTTTTT-TTTT-TTTT-TTTT-TTTTTTTTTTTT.lms.d2l.com/",
            "name": "urn:uuid:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
        }
    }

where:

homePage

TTTTTTTT-TTTT-TTTT-TTTT-TTTTTTTTTTTT is a UUID produced by an algorithm that takes the organization’s Brightspace TenantID as input. This value will be the same for all people and groups associated with this tenant. In this way, the homePage URI value is the same in all event objects associated with the tenant.

name

A UUID produced by an algorithm whose input is the person’s Brightspace UserID, the organization’s TenantID, and other identifying information. This same UUID will be used in every event where this person is the actor.

Brightspace ID numbers and strings used to produce homePage and name are given explicitly in the context section of the event object.

If User X is being impersonated by User Y, actor provides information on User X. The context section of the event object will contain an impersonatingUserId field identifying the impersonator (User Y).

Verb Information¶

The Verb section of a BDS xAPI event object has the form:

"verb": {
    "id": "https://api.brightspace.com/xapi/verbs/VERB"
}

where VERB specifies what the actor did. For example, when a user logs in, the verb is

"verb": {
    "id": "https://api.brightspace.com/xapi/verbs/logged_in"
}

The same verb may be used in different contexts. For example,

https://api.brightspace.com/xapi/verbs/viewed

is used in several different events where the user views some kind of information (e.g. a calendar event, a discussion thread, or an announcement).

Object Information¶

The object section of a BDS xAPI event object has the form:

"object": {
        "objectType": "Activity",
        "id": "urn:uuid:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "definition": {
            "type": "https://api.brightspace.com/xapi/activities/ACTIVITY"
        }
    }

where:

objectType

is always “Activity” (see the xAPI specifications).

id

is a UUID identifying the object. This UUID is produced by an algorithm whose input is all distinguishing information about the object. The algorithm creates a unique identifier that is always the same for the same object. For example, for events that involve a discussion forum, the algorithm uses the forum’s Brightspace ID number and the organization’s Tenant ID number as input values. The resulting UUID for the forum will always be the same whenever it appears in any event object.

definition

The type always has the form as given. The ACTVITY part of type indicates what type of object is involved. For example, activities on the user’s home page use

"definition": {
    "type": "https://api.brightspace.com/xapi/activities/tools/homepage"
}

For a complete list of object types that appear in BDS events, see BDS xAPI Keywords.

The context section of the event provides more information about the object. For example, if the event involves a discussion forum, context will include the Brightspace ID number of the forum.

Context Information¶

The context section of an event object provides additional information about the event. In particular, it gives Brightspace-specific information such as the actor’s User ID number, the organization’s TenantID, and so on.

Presence or absence of contextual information. The information in context varies according to the type of event; specifics are given in the documentation for each event type. Note that some contextual property fields may not appear in some events; event publishers within Brightspace may elect to simply not send a field for which they have no useful value, rather than attempting to send a field with an “empty value”.

Here is a simple context section:

"context": {
      "contextActivities": {
          "category": [
              {
                  "id": "https://api.brightspace.com/xapi/profiles/brightspace-activity-v1p0.jsonld"
              }
          ]
      },
      "registration": "00000000-0000-0000-0000-000000000000",
      "extensions": {
          "https://api.brightspace.com/xapi/extension_keys/context/actor": {
              "userId": "15961",
              "roleId": "578"
          },
          "https://api.brightspace.com/xapi/extension_keys/context/object": {
              "id": "6606"
          },
          "https://api.brightspace.com/xapi/extension_keys/context/context": {
              "tenantId": "TTTTTTTT-TTTT-TTTT-TTTT-TTTTTTTTTTTT",
              "originalEventId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
              "orgUnitType": "Organization",
              "orgUnitId": "6606",
              "sessionId": "urn:uuid:00000000-0000-0000-0000-000000000000",
              "originalSessionId": "3",
              "orgUnitTypeId": "1",
              "imsRoleIds": [
                  "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Student",
                  "http://purl.imsglobal.org/vocab/lis/v2/membership#Learner"
              ]
          }
      }
  }

Notes about this example:

extensions field names

as per the xAPI specification, our field names within an extensions structure are URIs within our own controlled vocabulary name space:

• https://api.brightspace.com/xapi/extension_keys/context/actor corresponds to extended meta-data about the xAPI statement’s actor

• https://api.brightspace.com/xapi/extension_keys/context/object corresponds to extended meta-data about the xAPI statement’s object

• https://api.brightspace.com/xapi/extension_keys/context/context corresponds to extended meta-data about the xAPI statement’s context in general

contextActivities

provides information about context itself. In particular, the id within category indicates the version of the event object’s format. This will change if the format changes.

registration

typically a UUID identifying the OrgUnit.

extensions

provides additional information about actor, object, and more, organized into composed structures that correspond to the other appropriate parts of the xAPI statement.

userId

the actor’s Brightspace User ID number; note that some events involve “the system” taking action, and in these cases, a userId value of 0 indicates “the system actor”, rather than a regular Brightspace user.

roleId

the actor’s Brightspace Role ID number.

object

the Brightspace identifier number for the object.

tenantId

the organization’s TenantID, expressed as a UUID.

originalEventID

a UUID identifying the original event within Brightspace itself. Since customers are not provided with direct access to Brightspace internal events, this identifier is only recorded for the use of D2L personnel during troubleshooting.

Organization information

fields used to identify the organization involved.

IMS Role information

fields used to identify the user’s IMS roles. These are specified as an array of URIs. The array may be empty. Common IMS roles seen in BDS events include

"http://purl.imsglobal.org/vocab/lis/v2/institution/person#Administrator"
"http://purl.imsglobal.org/vocab/lis/v2/institution/person#Student"
"http://purl.imsglobal.org/vocab/lis/v2/membership#Learner"