Learning Hub: Event Store APIs

Owned by Seth Petry-Johnson
Last updated: Mar 08, 2024
3 min read

The “Event Store” feature of the Learning Hub is designed to capture learning “events”, such as when someone completes a course or earns a credential.

These APIs will be called by individual “Programs” to put data into, or get data out of, the Event Store.

Overview

RESTful APIs for the “Event Store” functionality of the Learning Hub, where the hub acts as a centralized “clearinghouse” of accomplishments and activities.

Data model

EVENT

EVENT

An Event is the thing being recorded in the hub: user completed a course, earned a credential, etc.

This design is influenced by the idea of a Learning Record Store in xAPI, but with less complexity.

Field

Type

Notes

EventId

PRG-UUID
(26+128 chars)

{ProgramId}-{UUID}

The {ProgramId} helps guarantee uniqueness but also to make the IDs more human readable.

Event Ids are assigned by the Learning Hub.

PublisherProgramId

string (25 char)

Descriptive name for the Program that published this event.

PublisherSystemId

string (25 char)

Identifier for the type of system that published this data.

Currently, only the value “LB” is supported, for LearningBuilder.

EventType

string (50 char)

The type of event as reported by the publisher.

This list of possible types will vary by PublisherSystemId. For LearningBuilder this will be one of:

  • LPI_STARTED - FUTURE USE

  • LPI_COMP_UNSUCCESS - FUTURE USE

  • LPI_COMP_SUCCESS - FUTURE USE

  • LPI_REOPENED - FUTURE USE

  • AI_STARTED - FUTURE USE

  • AI_COMP_UNSUCCESS - FUTURE USE

  • AI_COMP_SUCCESS - MVP

  • AI_REOPENED - Recalled from complete to incomplete - FUTURE USE

PublisherEventId

string (200 char)

The Program’s unique identifier for the source event.

For LearningBuilder this will be something like “AI:1234”, which would be the Activity Instance WFI #1234

PublisherParticipantId

string (200 char)

The Program’s unique identifier for the person, organization, or entity that the event relates to.

PublisherEventData

JSON blob

The Program’s representation of the event data

EventStartUtc

UTC date/time

Non-null date/time the event started. (If only a single date/time is associated with the event, it is stored here)

EventEndUtc

UTC date/time

Nullable date/time that the event ended.

CreatedUtc

UTC date/time

UTC timestamp when this record was created.

Calling the API

API Hostnames

See

Authentication

See

Event Type

Different systems track different types of events, and different types of events may be associated with different data fields. Additionally, subscribers may only care about certain types of events from a given publisher.

In the initial launch of the Learning Hub, the only recognized value is AI_COMP_SUCCESS, representing a Completed Successfully event for a LearningBuilder Activity Instance.

Publishing Events into the Registry

POST /api/events

JSON Payload

{ "PublisherProgramId": "ProgramId", "PublisherSystemId": "LB", "PublisherEventId": "some_key_id", "EventType": "Event Type indicator", "PublisherParticipantId": "joebob@example.com", "PublisherEventData": { JSON }, "EventStartUtc": "UTC date/time", "EventEndUtc": "UTC date/time" }

Parameter

Description

Parameter

Description

PublisherProgramId

The Program that owns the Event.

The API Key must have access to this Program.

PublisherSystemId

The type of system that published the event. For now, only “LB” is supported.

EventType

The type of Event this record represents.

See the “Event Types” section, above.

PublisherEventId

A value that uniquely identifies this event in the publisher’s system.

For LearningBuilder publishers, this will be an “entity-scoped identifier” such as AI:1234, representing Activity Instance 1234.

PublisherParticipantId

Email address or some other piece of information that uniquely identifiers the primary participant within the Program’s system.

PublisherEventData

JSON object representing the Event in the source Program’s system.

EventStartUtc

The UTC date/time when this Event occurred, or the time that the Event started.

EventEndUtc

The UTC date/time when this Event ended. For Events with only a single timestamp, rather than a range, set this equal to EventStartUTC.

Responses

Response Code

Headers and Body

Response Code

Headers and Body

201 (Created)

A new Event was created. No body is returned.

HTTP headers:

Location: /events/{eventId}

DELETE /api/events/{eventId}

Responses

Response Code

Headers and Body

Response Code

Headers and Body

204 (No Content)

Delete was performed successfully. No body is returned.

Pulling events from the Registry

GET /api/events/{programId}

Querystring parameters

Parameter

Description

Parameter

Description

createdOnUtc

(required) The created-on date to match.

Responses

Response Code

Headers and Body

Response Code

Headers and Body

200 (Ok)

[ { "PublisherProgramId": "ProgramId", "PublisherEventId": "some_key_id", "PublisherSystemId": "LB", "EventType": "Event Type indicator", "PublisherParticipantId": "joebob@example.com", "PublisherEventData": { JSON }, "EventStartUtc": "UTC date/time", "EventEndUtc": "UTC date/time" }, ... ]