Metadata
Event Data Identifiers
Event payloads use two types of identifiers: globalId and localId. Global identifier is equal to (shardId*10000000000000)+localId. Please note our global identifiers might change if your Canvas instance goes through shard migration process, in this case your current shardId in the global identifier will change to a new shardId. Local identifiers do not change after shard migration and stay unique in the context of the Canvas account. All new events will provide local identifiers in the body of the event payload. To achieve consistency across all events, in the future all supported events will share local identifiers only, global identifier support deprecation note will be given as soon as the change is planned.
Event Data Formats
Event data is a record of a single event at a particular moment in time. An event consists of core attributes such as an event_name and event_type, and can be annotated with many additional attributes to provide more context. For example, Canvas captures detailed events when a user traverses a Canvas account or course.
Canvas collects numerous data points and emits some of them via its Live Events Data Service. The Live Events user interface displays a list of available event types that the customer could choose from depending on their needs. There are two formats of event data available for Canvas customers: IMS Caliper v1.1 and Canvas. The event type and format matters when you want to answer a specific business need.
Event Data
Event data is useful when you need to filter data based on arbitrary characteristics—such as data queries that are unique to customer external data warehouse application, learning analytics, histograms, etc. Canvas emits numerous events with a list of attributes attached to each event. For example, individual user logged_in and logged_out sessions, assignment submission details, and grade_change transactions.
Event data is not aggregated over time; therefore, it should not be used as a single source for your data warehouse. Use it in conjunction with Canvas Data Extracts and Canvas APIs to ensure the integrity of your LMS analytics dataset.
Event data is not sequenced, and can only be arranged in time based order via the "event_time" attribute expressed in ISO-8601 where data and time values are formatted with the addition of millisecond precision. The format is yyyy-MM-ddTHH🇲🇲ss.SSSZ where ‘T’ separates the date from the time while ‘Z’ indicates that the time is set to UTC.
Events are delivered in a "best-effort" fashion. In order to not slow down web requests, events are sent asynchronously. That means that there's a window where an event may happen, but the process responsible for sending the request to the queue is not able to queue it.
Event data can be sent to AWS SQS queue and any HTTPS endpoint . In event of endpoint downtime, all events will be lost.
Event Structure
Each event consists of two main parts : event metadata and event body. Based on the event trigger the metadata and body sections of the event will share different data. There are two types of event triggers : user request and system process or asynchronous job. System generated event will have job_id and job_tag in metadata associated with the asynchronous jobs that trigger the event. User generated event will have user id and request data associated with the event actor.
Event Metadata
Events triggered by system processes such as a course content migration or SIS import jobs will share data around the process that triggered an event and the context of the trigger . All system generated events have job_id and job_tag associated with the asynchronous jobs that trigger the events.
Examples
Description: system-generated, Course context
Payload Example:
Description: system-generated, no context
Payload Example:
Description: user-generated, Account context
Payload Example:
Description: user-generated, AssessmentQuestion context
Payload Example:
Description: user-generated, Course context
Payload Example:
Description: user-generated, CourseSection context
Payload Example:
Description: user-generated, Group context
Payload Example:
Description: user-generated, no context
Payload Example:
Description: user-generated, User context
Payload Example:
Event Body Schema
root_account_uuid
The Canvas uuid of the root account associated with the context of the job.
root_account_id
The Canvas id of the root account associated with the context of the job.
root_account_lti_guid
The Canvas lti_guid of the root account associated with the context of the job.
event_name
The event type.
event_time
The time that Canvas emitted the event, in ISO 8601 format with millisecond precision.
job_id
The identifier for the asynchronous job. Only present in system-generated events (events emitted in an asynchronous job, not an HTTP request).
job_tag
A string identifying the type of job being performed. Only present in system-generated events (events emitted in an asynchronous job, not an HTTP request).
producer
Always "canvas".
user_login
The login of the current user. Only present in user-generated events (events emitted directly from an HTTP request).
user_account_id
The Canvas id of the account that the current user belongs to. Only present in user-generated events (events emitted directly from an HTTP request).
user_sis_id
The SIS id of the user. Only present in user-generated events (events emitted directly from an HTTP request).
user_id
The Canvas id of the currently logged in user.
time_zone
Time zone of the currently logged in user. Only present in user-generated events (events emitted directly from an HTTP request).
developer_key_id
The id of the Developer Key used to create the access token for user. Only available for events triggered by an external tool.
context_type
The type of context where the event happened.
context_id
The Canvas id of the current context.
context_sis_source_id
SIS source id of the current context.
context_account_id
The account id of the current context. This is the actual account the context is attached to.
context_role
The role of the current user in the current context.
request_id
The identifier for this request. Correlates to Canvas Data table Requests.id. Only present in user-generated events.
session_id
The session identifier for this request. Can be used to correlate events in the same session for a user. Only present in user-generated events.
hostname
The domain of the Canvas instance for the request. Only present in user-generated events.
http_method
HTTP method/verb (GET, PUT, POST etc.) that the request was sent with. Only present in user-generated events.
user_agent
The User-Agent sent by the browser making the request. Only present in user-generated events.
client_ip
The client IP address of the request that triggered the event. Only present in user-generated events.
url
The URL of the request that triggered the event. Only present in user-generated events.
referrer
URL of the page the user clicked to get to the current page. Only present in user-generated events.
real_user_id
If the current user is being masqueraded, this is the Canvas id of the masquerading user. Only present in user-generated events.
This documentation is generated directly from the Canvas LMS source code, available on Github.
Last updated
Was this helpful?