Audit Log Events Overview

Event

An Event represents some action that an actor took, which affected a list of targets. An Event is an object with the following top-level properties:

Identifier

Both actor and each target carry an identifiers array. Each element is an Identifier object with the following properties:

The identifiers array lets you associate multiple identifiers with the same entity when it is known across different systems. When at least one Identifier has an issuer of "edlink", Edlink will look up the referenced entity and enrich it with the matching Edlink model under a details property when the Event is read back.

Target

A Target is an object representing an entity affected by an action. It has two properties:

• type: an Edlink-preferred type string (e.g. assignment, class, person). Unrecognized types are accepted as customer-specific data.
• identifiers: an array of Identifier objects.

Actor

The actor is the entity that performed the action. It has two properties:

• type: one of the following enum values:
  • person: a natural person (a human user).
  • system: an automated system or service (e.g. a background job, a cron task, or a service account) acting on its own.
  • anonymous: an unauthenticated or unknown actor.
• identifiers: an array of Identifier objects. Required and non-empty for person and system. Optional (may be omitted or empty) when type is anonymous.

For example:

{
    "actor": {
        "identifiers": [
            { "value": "00000000-0000-0000-0000-000000000000", "issuer": "edlink" },
            { "value": "acme_user_42", "issuer": "acme" }
        ],
        "type": "person"
    }
}

An anonymous actor with no identifiers:

{
    "actor": {
        "type": "anonymous"
    }
}

Severity

severity is an optional enum describing how important the Event is. Valid values, from lowest to highest:

If an unrecognized value is supplied, Edlink accepts the Event, sets severity to debug, and returns a warning. Mixed-case values are accepted and normalized to lowercase before validation (e.g. High or HIGH become high). It is not controllable by a Schema.

Scope

scope is a required arbitrary string identifier, up to 128 bytes, that is meaningful within your own system — for example a tenant ID, customer ID, or any other string key you use to segment your users or data. It is how you list Events for search and review purposes.

institution is an optional Edlink UUID referencing an Institution from the Public Data API. We strongly encourage you to pass an institution whenever the Event is associated with a known learning institution, as it enables richer cross-referencing against Edlink's data set and institution-level analysis.

Recording Events

To record Events, use the Create Event endpoint. Send a single Event object, or an array of up to 100 Events in one request.

Network Context

The context object describes the request that produced the Event. It is not controllable by a Schema. Edlink only understands the properties enumerated below. Every property is optional, but the strings will be validated for reasonable formats, like "GET" for http_method or "1.1.1.1" for ip, and a warning will be given on non-compliant data.

Edlink-preferred Types

Some fields support a type sub-field that is "Edlink-preferred." When you pass an Edlink Data Model type name (such as person or class) as the type, Edlink will automatically match the supplied id to the related Edlink entity. When a match is found, the data is automatically enriched with the full Edlink model.

If you supply a type string that Edlink does not recognize, the data is still accepted — it is simply treated as customer-specific data that cannot be enriched. A common use case is passing your own internal user identifiers for users who log into your platform without using Edlink's SSO.

Note that actor.type does not participate in this Edlink-preferred mechanism — it is constrained to the enum person, system, or anonymous. To enrich an actor with an Edlink entity, include an Identifier with issuer: "edlink" in actor.identifiers.

The list of recognized Edlink types includes:

• assignment: Assignment model
• class: Class model
• course: Course model
• district: District model
• enrollment: Enrollment model
• file: File model
• integration: Integration model
• module: Module model
• page: Page model
• person: Person model
• resource: Resource model
• school: School model
• session: Session model
• source: Source model
• submission: Submission model

For example, this target:

{
    "targets": [
        {
            "identifiers": [{ "value": "00000000-0000-0000-0000-000000000000", "issuer": "edlink" }],
            "type": "person"
        }
    ]
}

is enriched with the Edlink Person model, which is returned under a details property:

{
    "targets": [
        {
            "identifiers": [{ "value": "00000000-0000-0000-0000-000000000000", "issuer": "edlink" }],
            "type": "person",
            "details": {
                "id": "00000000-0000-0000-0000-000000000000",
                "created_date": "2021-07-13T17:45:39.937Z",
                "updated_date": "2021-07-13T17:45:39.937Z",
                "first_name": "George",
                "last_name": "Bluth",
                "display_name": "Gob Bluth",
                "roles": ["student"],
                "email": "gob.bluth@example.com"
            }
        }
    ]
}

Similarly, an actor with an Identifier whose issuer is "edlink" will be enriched with the Edlink model that corresponds to its type:

{
    "actor": {
        "identifiers": [
            { "value": "00000000-0000-0000-0000-000000000000", "issuer": "edlink" }
        ],
        "type": "person",
        "details": {
            "id": "00000000-0000-0000-0000-000000000000",
            "first_name": "George",
            "last_name": "Bluth",
            "display_name": "Gob Bluth",
            "roles": ["student"],
            "email": "gob.bluth@example.com"
        }
    }
}

Starter Actions and Schemas

It can be difficult to know what to track. Edlink provides opt-in starter Schemas for common actions (user.login.success, user.login.error, user.logout, resource.access, resource.create, resource.update). Identify users via the Event actor; starter data / before / after fields are optional context only. Add them from the dashboard (Add Starter Schemas), which creates each Schema through the normal create endpoint. See Audit Log Schemas for the full definitions.