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"
    }
}

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.

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"
        }
    }
}

Default Actions and Schemas

It can be difficult to know what to track. To facilitate easy adoption of Audit Logs, Edlink pre-defines some common actions with their associated Schemas. All Schemas are set to lax for flexibility. Of course, your deep understanding of your own product will let you create new ones, or update these existing actions with Schemas that are more appropriate to your product's needs. However, we consider these a good starting point for developers:

user.login Schema

{
    "version": "00000000-0000-0000-0000-000000000000",
    "validation_level": "lax",
    "action": {
        "id": "user.login",
        "type": "create" // "creating" a session
    },
    "data": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "$id": "https://ed.link/api/default-schemas/user.login.json",
        "title": "user.login",
        "description": "An event describing a user logging into a client's application.",
        "type": "object",
        "properties": {
            "internal_user_id": {
            "description": "The unique identifier for a user in the client's application",
            "type": "string"
            },
            "application_name": {
            "description": "Name of the application the user is accessing",
            "type": "string"
            },
            "previous_login_date": {
            "description": "The timestamp of the user's last login",
            "type": "string"
            }
        },
        "required": [ "internal_user_id" ]
    }
}

user.logout Schema

{
    "version": "00000000-0000-0000-0000-000000000000",
    "validation_level": "lax",
    "action": {
        "id": "user.logout",
        "type": "delete" // "deleting" a session
    },
    "data": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "$id": "https://ed.link/api/default-schemas/user.logout.json",
        "title": "user.logout",
        "description": "An event describing a user logging out of a client's application.",
        "type": "object",
        "properties": {
            "internal_user_id": {
            "description": "The unique identifier for a user in the client's application",
            "type": "string"
            },
            "application_name": {
            "description": "Name of the application the user is accessing",
            "type": "string"
            },
            "session_duration_ms": {
            "description": "The duration of the user's session in milliseconds",
            "type": "integer"
            }
        },
        "required": [ "internal_user_id" ]
    }
}

content.access Schema

{
    "version": "00000000-0000-0000-0000-000000000000",
    "validation_level": "lax",
    "action": {
        "id": "content.access",
        "type": "read"
    },
    "data": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "$id": "https://ed.link/api/default-schemas/content.access.json",
        "title": "content.access",
        "description": "An event describing a user accessing some content within a client's application.",
        "type": "object",
        "properties": {
            "internal_user_id": {
                "description": "The unique identifier for a user in the client's application",
                "type": "string"
            },
            "application_name": {
                "description": "Name of the application the user is accessing",
                "type": "string"
            },
            "content_name": {
                "description": "The human-readable name of the content",
                "type": "string"
            },
            "content_type": {
                "description": "The internal type of the content (text, video, etc)",
                "type": "string"
            }
        },
        "required": [ "internal_user_id" ]
    }
}