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.
  • external: an outside party acting on the system (e.g. a third-party webhook, a partner integration, or an unauthenticated external request).
• identifiers: an array of Identifier objects.

For example:

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

Scope

A scope in an Event refers to the segment of your application which an Event belongs to. Ideally, this is an Edlink Integration, to allow for the richest data-filling and search capabilities. Scope is required, because it's how you can list Events for search and review purposes.

However, you might wish to send Events related to other schools or districts you do business with, but are not connected via Edlink. The institution option is ideal for this, since it references Learning Institutions which Edlink still knows about via our Public Data API.

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 external. 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" ]
    }
}