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 GG4L 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 into 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 into a district's data source or unshared with your application by the district.

All the supported types are listed below.

How to process events?

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