Caliper Events : Message Structure and Properties

Document created by Oxana Jurosevic Administrator on Oct 16, 2018Last modified by Oxana Jurosevic Administrator on Oct 22, 2018
Version 6Show Document
  • View in full screen mode

                                                                                                                                                  Back to Table of Contents

Caliper Event Message 

 

Caliper live events are Canvas live events transformed into the Caliper format. Caliper is a format based on JSON-LD that seeks to standardize analytical data. Each event consists of a JSON payload with a defined structure.

 

Caliper also has a concept of metric profiles. These are logical groupings of events that provide coverage of a certain set of actions. For example, the Assignable profile contains a number of events related to assignments.

 

We are currently using version 1.1 of the Caliper specification.

 

 

Caliper Event Message Structure an Properties

 

Canvas Caliper message event envelope consists of the following structure:

 

sensor, sendTime, dataVersion, data attributes.

 

sensor  

Canvas account domain name, e.g. "sensor": "http://oxana.instructure.com/"

 

sendTime

The timestamp of when a specific event was sent to subscriber. sendTime is valid if in ISO 8601 format, e.g. yyyy-mm-ddThh ss.SSSZ where 'T' separates the date from the time, while 'Z' indicates that the time is set to UTC.

dataVersion
Value conforms with Caliper 1.1, i.e. http://purl.imsglobal.org/ctx/caliper/v1p1

data
Contains an ordered collection of one Caliper event. In Canvas implementation, we issue one message per event. IMS Caliper v1p1 allows you to combine multiple Events/Entities in one message data and/or Entity described objects. Per Caliper v1p1 the Sensor MAY micEvent and Entity described data in the same Envelope.

Under  data  Event collection:

  • Each event has a @context attribute whose value is http://purl.imsglobal.org/ctx/caliper/v1p1

  • Each event has an id attribute whose value is a Version 4 UUID expressed as a URN using the form urn:uuid:, per RFC 4122, e.g: "id": "urn:uuid:19f57ead-f709-45e0-9869-25c68d933d45"

  • Each event has a valid actor, action, object, and eventTime attributes.
    • type is a string value corresponding to the Term defined for the Event in the external IMS Caliper JSON-LD context document.
    • action is formed as a result of a purposeful action undertaken by the actor at a particular moment in time and within a given learning context. It is a string set to the appropriate Caliper Term; only one action can be specified per event.
    • actor is the agent who initiated the event in the system of origin, typically a Person, but not always. It is a hash containing an id and type attribute, each valid strings. For example:

"actor": {

       "id": "http://oxana.instructure.com/",

       "type": "SoftwareApplication"

     }

// SoftwareApplication actor will appear when an Event is initiated by system of Event origin maybe as a result of user interaction with a specific asset, but without user specific actions, e.g. GradeEvent for assessment is generated by Canvas when a quiz is set to auto-grade setting.

 

If the Caliper Actor is a Person, the following mappings apply for actor properties:

 

 

 

Caliper Extension Property

Canvas Object Property

Example

extensions.com.instructure.canvas.id

shardId+000000000000+user_id

"id": "urn:instructure:canvas:user:21070000000000049"

extensions.com.instructure.canvas.real_user_id

real_user_id

"real_user_id": "12345678901768"

extensions.com.instructure.canvas.user_login

user_login

extensions.com.instructure.canvas.root_account_id

shardId+000000000000+ root_account_id

"root_account_id": "11110000000000001"

extensions.com.instructure.canvas.root_account_lti_guid

root_account_lti_guid

"root_account_lti_guid": "7db438071375c02373713c12c73869ff2f470b96.oxana.instructure.com"

extensions.com.instructure.canvas.root_account_uuid

root_account_uuid

"root_account_uuid": "VicYj3cu5BIFpoZhDVU4DZumnlBrWi1grgJEzAGs"

extensions.com.instructure.canvas.entity_id

shardId+000000000000+user_id

"entity_id": "11110000000000049"

 

    • eventTime is a valid ISO 8601 formatted server timestamp when an event happened in the system of origin; e.g. yyyy-mm-ddThh ss.SSSZ where 'T' separates the date from the time while 'Z' indicates that the time is set to UTC, e.g. "eventTime":"2018-09-24T21:43:50.000Z"

The following OPTIONAL properties are available for certain events, please see Event Payloads ( hyperlink this to the event table)  for more details

 

generated  

 

Encapsulates an entity that was created as a result of the interaction. Expressed as an object. Available only in a few specific event types , see payloads for details.

 

Example:

 

GradeEvent, action = Graded, object.type = Attempt

 

{...

 

"generated": {

       "id": "urn:instructure:canvas:submission:21070000000011096",

       "type": "Score",

       "extensions": {

         "com.instructure.canvas": {

           "grade": "10",

           "entity_id": "21070000000011096"

         }

       },

       "attempt": {

         "id": "urn:instructure:canvas:submission:21070000000011096",

         "type": "Attempt",

         "extensions": {

           "com.instructure.canvas": {

             "grade": "10"

           }

         },

         "assignee": {

           "id": "urn:instructure:canvas:user:21070000000000048",

           "type": "Person",

           "extensions": {

             "com.instructure.canvas": {

               "sis_id": "Test2"

             }

           }

         },

         "assignable": {

           "id": "urn:instructure:canvas:assignment:21070000000000365",

           "type": "AssignableDigitalResource"

         }

       },

       "maxScore": {

         "numberStr": "10.0"

       },

       "scoreGiven": {

         "numberStr": "10.0"

       }

     },

}

 

edApp

 

The software that constitutes the application context. Expressed as an object.

 

edApp.id  is represented as a  customer Canvas domain URL e.g : http://oxana.instructure.com/  or a default URL: www.canvaslms.com depending on the producer of the event and the application end user accessing Canvas from.

 

edApp.id = account hostname when an event is produced by end user action : submitting an assignment, browsing application. Hostname might vary based on the account settings, it could show up as a vanity account URL , events triggered thru mobile app follow the same logic and provide canvas account domain URL for all events produced by end user.

 

edApp.id = DEFAULT_URL = 'www.canvaslms.com' when an event is triggered by an automated job run by software application.  Typically you will not see  "session" in those events as well as there won’t be a “hostname” available in the “extensions”

 

Example:

 

User Generated Event :

 

{

 "sensor": "http://oxana.instructure.com/",

 "sendTime": "2018-10-05T21:21:03.716Z",

 "dataVersion": "http://purl.imsglobal.org/ctx/caliper/v1p1",

 "data": [

   {

     "@context": "http://purl.imsglobal.org/ctx/caliper/v1p1",

     "id": "urn:uuid:87d8e3c3-ba1c-49e1-aff7-9bcee49d50b3",

     "type": "NavigationEvent",

     "actor": {

       "id": "urn:instructure:canvas:user:170000004596604",

       "type": "Person",

       "extensions": {

         "com.instructure.canvas": {

           "user_login": "oxana",

           "root_account_id": "21070000000000001",

           "root_account_lti_guid": "7db438071375c02373713c12c73869ff2f470b68.oxana.instructure.com",

           "root_account_uuid": "VicYj3cu5BIFpoZhDVU4DZumnlBrWi1grgJEzADs",

           "entity_id": "170000004596604"

         }

       }

     },

     "action": "NavigatedTo",

     "object": {

       "id": "urn:instructure:canvas:attachment:21070000000000606",

       "type": "Entity",

       "name": "attachment",

       "extensions": {

         "com.instructure.canvas": {

           "asset_type": "attachment",

           "entity_id": "21070000000000606"

         }

       }

     },

     "eventTime": "2018-10-05T22:48:09.000Z",

     "edApp": {

       "id": "http://oxana.instructure.com/",

       "type": "SoftwareApplication"

     },

     "session": {

       "id": "urn:instructure:canvas:session:de5d82bcf15621c615fd470200c5073e",

       "type": "Session"

     },

     "extensions": {

       "com.instructure.canvas": {

         "hostname": "oxana.instructure.com",

         "request_id": "35d77f34-1f03-4196-a258-4be2f2a5509d",

         "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",

         "version": "1.0.0"

       }

     }

   }

 ]

}

 

Software Generated Event :

 

{

 "sensor": "http://www.canvaslms.com/",

 "sendTime": "2018-10-08T14:33:17.834Z",

 "dataVersion": "http://purl.imsglobal.org/ctx/caliper/v1p1",

 "data": [

   {

     "@context": "http://purl.imsglobal.org/ctx/caliper/v1p1",

     "id": "urn:uuid:baece193-e3cf-42e6-bd4f-9b693593c5d2",

     "type": "Event",

     "actor": {

       "id": "urn:instructure:canvas:user:21070000000000047",

       "type": "Person",  // in some cases the actor is listed as a person who triggered the chain of events though it should be the software application, this should be reviewed by product management as a potential gap. 

       "extensions": {

         "com.instructure.canvas": {

           "root_account_id": "21070000000000001",

           "root_account_lti_guid": "7db438071375c02373713c12c73869ff2f470b68.oxana.instructure.com",

           "root_account_uuid": "VicYj3cu5BIFpoZhDVU4DZumnlBrWi1grgJEzADs",

           "entity_id": "21070000000000047"

         }

       }

     },

     "action": "Modified",

     "object": {

       "id": "urn:instructure:canvas:submission:21070000000011168",

       "type": "Attempt",

       "dateModified": "2018-10-08T20:06:06.000Z",

       "extensions": {

         "com.instructure.canvas": {

           "submission_type": "discussion_topic",

           "entity_id": "21070000000011168"

         }

       },

       "assignee": {

         "id": "urn:instructure:canvas:user:21070000000000047",

         "type": "Person"

       },

       "assignable": {

         "id": "urn:instructure:canvas:assignment:21070000000000394",

         "type": "AssignableDigitalResource"

       },

       "count": 1

     },

     "eventTime": "2018-10-08T20:06:06.000Z",

     "edApp": {

       "id": "http://www.canvaslms.com/",

       "type": "SoftwareApplication"

     }, //no session will also indicate Software triggered event

     "extensions": {

       "com.instructure.canvas": {

         "job_id": "1020020480864088",

         "job_tag": "DiscussionEntry#context_module_action",

         "version": "1.0.0" //no hostname in the extension is another indicator of the event generated by a job

       }

     }

   }

 ]

}

 

 

group

 

Representation of the Canvas context type where the action took place. Expressed as an object. There are only two types of context used in Basic Caliper implementation: CourseOffering (Canvas Course) and CourseSection (Canvas Section).

 

Example:

 

{...

"group": {

       "id": "urn:instructure:canvas:course:21070000000000565",

       "type": "CourseOffering",

       "extensions": {

         "com.instructure.canvas": {

           "context_type": "Course",

           "entity_id": "21070000000000565"

         }

       }

},

}

 

membership

 

The relationship between the actor and the group in terms of roles assigned and current status. Expressed as an object. We do not include a membership for gradeChanged since the actor is SoftwareApplication.

 

Example:

 

{...

"membership": {

       "id": "urn:instructure:canvas:course:21070000000000565:user:1700000045678945",

       "type": "Membership",

       "member": {

         "id": "urn:instructure:canvas:user:1700000045678945",

         "type": "Person"

       },

       "organization": {

         "id": "urn:instructure:canvas:course:21070000000000565",

         "type": "CourseOffering"

       }

     },

}

 

 

session

 

A web application user session. Expressed as an object.  

 

 

Example:

 

{...

"session": {

       "id": "urn:instructure:canvas:session:fe03cd7d1de8d27ca95e2d6f5fe11891",

       "type": "Session"

     },

}

 

extensions

 

Not all Canvas assets properties are covered by the Caliper spec. We add extensions to many events and entities. See specific Message type for details around supported extensions.

 

Example:

 

Event => Entity= AssignableDigitalResource => action = Created

 

extensions:

       lock_at: formatDateTime(lock_at),

       entity_id: assignment_id

   

 

Back to:  Table of Contents 

Attachments

    Outcomes