Subscription Events
This is a reference of all the events in Engine you can subscribe to, as well as key information on how you can configure those subscriptions.
In addition to a general Topic, one can specifiy a special subset of that topic (Subtopics) or filter out events based on certain information about them (Filter Targets). The list of Subtopics and Filter Targets might span across multiple topics, but they represent that term only within the context of the topic the subscription is for.
The Message Body is what is sent for the given topic, though it will always be within the standard envelope. Not all topics will have a Message Body. The Response Body is what Engine expects as a response to an Exchange. A Notification will never expect a Response Body.
Subscriptions Reference
Each subscription is defined as follows:
SubscriptionIdentifier (Type (Notification or Exchange), Subtopics, Filter Targets, Message Body[, Response Body])
Description of topic
As always, if you have questions about how and when a particular event is fired, please feel free to ask us.
Course Subscriptions
| Type | Subtopics | Filter Targets |
|---|---|---|
| Notification | Success Failure |
CourseId LearningStandard Tenant |
When a course is imported.
Message Body:
ImportJobResultSchema:
type: object
properties:
jobId:
type: string
status:
type: string
enum:
- RUNNING
- COMPLETE
- ERROR
- TIMEOUT
message:
type: string
isDryRun:
type: boolean
importResult:
type: object
properties:
webPathToCourse:
type: string
description: web path to this course
parserWarnings:
type: array
items:
type: string
courseLanguages:
type: array
items:
type: string
course:
type: object
properties:
id:
type: string
title:
type: string
xapiActivityId:
type: string
description: xAPI activity id associated with this course
updated:
type: string
format: date-time
webPath:
type: string
description: The web path at which the course's contents are hosted. For AICC courses, refer to the href property of the child activities as this value will not be available.
version:
type: integer
format: int32
registrationCount:
type: integer
format: int32
activityId:
type: string
courseLearningStandard:
type: string
enum:
- SCORM11
- SCORM12
- SCORM20042NDEDITION
- SCORM20043RDEDITION
- SCORM20044THEDITION
- AICC
- XAPI
- CMI5
- LTI11
- LTI13
launchable:
type: boolean
description: Always 'true' except for courses created by the xAPI On-Demand Registrations process which are only there as a placeholder. If 'false', this course does not have the necessary information to be launched.
default: true
connector:
type: object
properties:
connectorId:
type: string
connectorIdForContent:
type: string
connectorName:
type: string
metadata:
type: object
properties:
title:
type: string
titleLanguage:
type: string
description:
type: string
descriptionLanguage:
type: string
duration:
type: string
typicalTime:
type: string
keywords:
type: array
items:
type: string
pluginSpecificMetadata:
type: object
additionalMetadata:
type: object
rootActivity:
type: object
properties:
externalIdentifier:
type: string
description: An arbitrary identifier that the external LMS system can associate with this LearningObject to track it as it isreused across courses
itemIdentifier:
type: string
description: The string which identifies this activity in the context of its course
resourceIdentifier:
type: string
description: The string which identifies this activity's resource in a course's manifest
activityType:
type: string
description: The type of activity this is
enum:
- UNKNOWN
- AGGREGATION
- SCO
- ASSET
- OBJECTIVE
href:
type: string
description: The web path used to launch this activity
scaledPassingScore:
type: string
description: The score required of a learner to pass this activity
title:
type: string
description: The title of the activity
children:
type: array
items:
type: CourseActivitySchema
| Type | Subtopics | Filter Targets |
|---|---|---|
| Notification | None | CourseId LearningStandard RegistrationId Tenant |
Fires when a course launches.
Message Body:
N/A
Registration Subscriptions
| Type | Subtopics | Filter Targets |
|---|---|---|
| Notification | ScoreChanged CompletionChanged SuccessChanged ObjectiveChanged InteractionChanged Exit RunTimeActivityCompletionChanged RunTimeActivitySuccessChanged |
CourseId LearningStandard RegistrationId Tenant |
When a registration's state significantly changes. The format of the report is determined by the `ApiRollupRegistrationFormat` configuration setting.
Message Body:
RegistrationSchema:
type: object
properties:
id:
type: string
instance:
type: integer
format: int32
xapiRegistrationId:
type: string
description: xAPI registration id associated with this registration
lti13SubjectIdentifier:
type: string
description: Identifier for the registration that will be sent to the LTI 1.3 tool during launch in the 'sub' claim. Corresponds to the 'userId' parameter in the Assignment and Grade Service endpoints
lti13CustomClaims:
type: object
dispatchId:
type: string
description: Dispatch ID for this registration, if applicable
updated:
type: string
format: date-time
registrationCompletion:
type: string
enum:
- UNKNOWN
- COMPLETED
- INCOMPLETE
default: "UNKNOWN"
registrationSuccess:
type: string
enum:
- UNKNOWN
- PASSED
- FAILED
default: "UNKNOWN"
score:
type: object
properties:
scaled:
type: number
format: double
description: Scaled score between 0 and 100
totalSecondsTracked:
type: number
format: double
firstAccessDate:
type: string
format: date-time
lastAccessDate:
type: string
format: date-time
completedDate:
type: string
format: date-time
createdDate:
type: string
format: date-time
course:
type: object
description: Basic information about a course for when a course is referenced by other objects, such as a registration.
properties:
id:
type: string
title:
type: string
version:
type: integer
format: int32
courseReferenceLearningStandard:
type: string
enum:
- SCORM11
- SCORM12
- SCORM20042NDEDITION
- SCORM20043RDEDITION
- SCORM20044THEDITION
- AICC
- XAPI
- CMI5
- LTI11
- LTI13
learner:
type: object
properties:
id:
type: string
firstName:
type: string
lastName:
type: string
globalObjectives:
type: array
items:
type: object
properties:
id:
type: string
primary:
type: boolean
score:
type: ScoreSchema
scoreMax:
type: number
format: double
scoreMin:
type: number
format: double
scoreRaw:
type: number
format: double
previousScoreScaled:
type: number
format: double
firstScoreScaled:
type: number
format: double
progressMeasure:
type: number
format: double
firstSuccessTimeStamp:
type: string
objectiveCompletion:
type: string
enum:
- UNKNOWN
- COMPLETED
- INCOMPLETE
default: "UNKNOWN"
objectiveSuccess:
type: string
enum:
- UNKNOWN
- PASSED
- FAILED
default: "UNKNOWN"
previousObjectiveSuccess:
type: string
enum:
- UNKNOWN
- PASSED
- FAILED
default: "UNKNOWN"
activityDetails:
type: object
properties:
id:
type: string
title:
type: string
attempts:
type: integer
format: int32
activityCompletion:
type: string
enum:
- UNKNOWN
- COMPLETED
- INCOMPLETE
activitySuccess:
type: string
enum:
- UNKNOWN
- PASSED
- FAILED
score:
type: ScoreSchema
timeTracked:
type: string
completionAmount:
type: object
properties:
scaled:
type: number
format: double
description: Scaled completion amount between 0 and 100
suspended:
type: boolean
children:
type: array
items:
type: ActivityResultSchema
objectives:
type: array
items:
type: ObjectiveSchema
staticProperties:
type: object
properties:
completionThreshold:
type: string
launchData:
type: string
maxTimeAllowed:
type: string
scaledPassingScore:
type: number
format: double
scaledPassingScoreUsed:
type: boolean
timeLimitAction:
type: string
runtime:
type: object
properties:
completionStatus:
type: string
credit:
type: string
entry:
type: string
exit:
type: string
learnerPreference:
type: object
properties:
audioLevel:
type: number
format: double
language:
type: string
deliverySpeed:
type: number
format: double
audioCaptioning:
type: integer
format: int32
location:
type: string
mode:
type: string
progressMeasure:
type: string
scoreScaled:
type: string
scoreRaw:
type: string
scoreMin:
type: string
scoreMax:
type: string
totalTime:
type: string
timeTracked:
type: string
runtimeSuccessStatus:
type: string
enum:
- UNKNOWN
- PASSED
- FAILED
default: "UNKNOWN"
suspendData:
type: string
learnerComments:
type: array
items:
type: object
properties:
value:
type: string
location:
type: string
dateTime:
type: string
lmsComments:
type: array
items:
type: CommentSchema
runtimeInteractions:
type: array
items:
type: object
properties:
id:
type: string
type:
type: string
enum:
- TrueFalse
- Choice
- FillIn
- LongFillIn
- Likert
- Matching
- Performance
- Sequencing
- Numeric
- Other
objectives:
type: array
items:
type: string
timestamp:
type: string
timestampUtc:
type: string
correctResponses:
type: array
items:
type: string
weighting:
type: string
learnerResponse:
type: string
result:
type: string
latency:
type: string
description:
type: string
runtimeObjectives:
type: array
items:
type: object
properties:
id:
type: string
scoreScaled:
type: string
scoreMin:
type: string
scoreMax:
type: string
scoreRaw:
type: string
runtimeObjectiveSuccessStatus:
type: string
enum:
- UNKNOWN
- PASSED
- FAILED
default: "UNKNOWN"
runtimeObjectiveCompletionStatus:
type: string
enum:
- UNKNOWN
- COMPLETED
- INCOMPLETE
- NOT_ATTEMPTED
- BROWSED
default: "UNKNOWN"
progressMeasure:
type: string
description:
type: string
sharedData:
type: array
items:
type: object
properties:
id:
type: string
value:
type: string
suspendedActivityId:
type: string
registrationCompletionAmount:
type: number
format: double
description: A decimal value between 0 and 1 representing the percentage of this course that the learner has completed so far, if known. Note: for learning standards other than SCORM 2004 4th Edition, this value is based on the percentage of activities completed/passed. This means that single-activity courses in those standards will always return either 0 or 1.
ErrorHandling Subscriptions
| Type | Subtopics | Filter Targets |
|---|---|---|
| Notification | InitialAttempt FinalAttempt |
SubscriptionId Tenant |
When an event notification fails on the initial and final attempts.
Message Body:
NotificationFailedBody:
type: object
properties:
subscriptionDefinition:
type: object
properties:
topic:
type: string
description: Topic to subscribe to
enum:
- CourseImport
- CourseLaunched
- RegistrationChanged
- NotificationFailed
- XapiGetAuthority
subtopics:
type: array
description: Topic dependent list of sub-topics for which the subscriber should be notified. Eg: 'success' or 'failed' for course import
items:
type: string
enabled:
type: boolean
url:
type: string
authId:
type: string
description: The ID for the subscription auth entry to use to authorize requests for this subscription.
timeoutMS:
type: integer
format: int32
description: Network timeout in milliseconds for sending subscription
asyncMode:
type: string
description: Will this Notification be sent in a thread, or synchronously? Note: Synchronous delivery should be used sparingly as it may severely degrade performance. Has no effect on Exchanges.
enum:
- Thread
- Sync
strictOrdering:
type: boolean
description: Should Engine keep track of notification ordering and drop out of date notifications? Note: Ordering notifications should be used sparingly as it may severly degrade performance. Has no effect on Exchanges.
expiresMS:
type: integer
format: int32
description: For how long (in ms) should Engine cache the response to this Exchange. Has no effect on Notifications.
retryAttempts:
type: integer
format: int32
description: The number of times Engine will attempt to send after a failure. Takes the lower value between this and the `SimpleQueueMaxRetries` configuration setting.
retryDelaySeconds:
type: integer
format: int32
description: The initial length of time Engine will wait before retrying after a failure. This time will be doubled after each retry. Takes the greater value between this and the `SimpleQueueRetryInitialDelaySeconds` configuration setting.
ignoreBeforeDate:
type: string
format: date-time
description: Queued messages generated before this date will be discarded.
filters:
type: array
description: Filters on resources such as course, registration, or tenant for which this subscriber should be notified. If multiple filters are defined, only events that match all the filters will trigger a notification.
items:
type: object
properties:
target:
type: string
description: List of valid resources to which filters can be applied.
enum:
- CourseId
- LearningStandard
- Tenant
- RegistrationId
- SubscriptionId
matches:
type: array
description: List of matches for specified target. At least one match is required. If multiple matches are defined, the filter applies if any match.
items:
type: string
description: RegEx indicated by enclosing '/' or literal to match against target
required:
- target
- matches
required:
- topic
- url
- enabled
message:
type: object
properties:
payloadId:
type: string
subscriptionId:
type: string
topic:
type: string
subtopics:
type: array
items:
type: string
tenantName:
type: string
timestamp:
type: string
format: date-time
body:
type: object
bodyVersion:
type: string
messageVersion:
type: string
resources:
type: object
properties:
course:
type: object
properties:
id:
type: string
learningStandard:
type: string
version:
type: integer
registration:
type: object
properties:
id:
type: string
instance:
type: integer
learner:
type: object
properties:
id:
type: string
firstName:
type: string
lastName:
type: string
isDispatch:
type: boolean
errorMessage:
type: string
description: The error in Engine which caused the failure.
errorReference:
type: string
description: A reference to the error in Engine.
httpResponseCode:
type: integer
description: The response code Engine recieved after attempting to send.
responseBody:
type: object
description: The response body Engine recieved after attempting to send.
Xapi Subscriptions
| Type | Subtopics | Filter Targets |
|---|---|---|
| Exchange | None | Tenant |
When a call to the LRS is made. Engine will send a copy of the authorization header it recieved, and expects in return the associated actor (if one exists) and their permissions.
Message Body:
XapiGetAuthorityBody:
type: object
properties:
authorizationHeader:
type: string
description: The authorization header Engine recieved at an xAPI endpoint.
required:
- authorizationHeader
Response Body:
XapiGetAuthorityResponseSchema:
type: object
properties:
verified:
type: boolean
description: Is there an actor associated with these auth credentials? Unverified credentials will always be rejected.
permission:
type: string
description: Permissions of the associated actor.
enum:
- NONE
- USER
- ROOT
- READONLY
- WRITEONLY
accountId:
type: string
description: The AccountId of the associated actor.
required:
- verified