Events

Events are generated when actions take place within district data sources or data sharing. Events are generated from user interactions such as deleting or editing a class, changes in the district`s state, and other causes. Learn more about Event types

📘

Note

Events are stored for 30 days and organized chronologically (from oldest to newest). Once the 30-day period has ended, events are automatically deleted.

Event structure

You can get multiple events for a single object in one HTTP call via a JSON array. Here is an example of a typical JSON data set for sending with the API. This call sends Student.Updated type event as a JSON.

{
  "events": [
    {
      "sourcedId": "8d1db09b-abe4-4071-88ae-Bd3FgHj7Kl",
      "eventType": "Student.Updated",
      "timestamp": "2024-03-05T12:30:45.123Z",
      "object": {
        "sourcedId": "Bd3FgHj7Kl-gf51-1025-ST123456",
        "status": "active",
        "dateLastModified": "2024-02-03T17:41:18.777Z",
        "metadata": {
          "student_number": "ST123456",
          "gg4l.primary_school": "",
          "gg4l.preferred_contact_method": "email"
        },
        "username": "john.doe",
        "givenName": "John",
        "familyName": "Doe",
        "role": "student"
      },
      "changes": {
        "metadata": {
        },
        "phone": "(800) 555‑0175"
      }
    }
  ]
}

The top-level fields sourcedId, eventType, timestamp, and object, are always present, though object may be null.

  • sourcedId: A unique SchoolDay ID for this event.
  • eventType: Indicates one of the event types provided below.
  • timestamp: The time when the event was generated.
  • object: A full JSON object of the event.
  • changes: For .Updated events only. Displays any changes made to an object. If changes are made to related objects, the changes field will be empty.

Events types

Each event has a type of event:

  • .Created: A new object was created in a district's data source or shared with your application by the district.
  • .Updated: Any object`s field or linked field was modified.
  • .Deleted: An object was deleted from a district's data source or unshared with your application by the district.

All the supported types are listed below.

Created

Updated

Deleted

AcademicSession.Created Contact.Created Course.Created Class.Created Demographic.Created District.Created Enrollment.Created School.Created Student.Created Teacher.Created

AcademicSession.Updated
Contact.Updated
Course.Updated
Class.Updated
Demographic.Updated
District.Updated
Enrollment.Updated
School.Updated
Student.Updated
Teacher.Updated

AcademicSession.Deleted
Contact.Deleted
Course.Deleted
Class.Deleted
Demographic.Deleted
District.Deleted
Enrollment.Deleted
Student.Deleted
School.Deleted
Teacher.Deleted

How to process events?

Events should be processed in chronological order. Each action must start with checking the SchoolDay ID before it's performed. Failure of this may lead to an increase in sync errors.