Info

These API keys have a similar format to LearningBuilder API Keys, but are completely separateThe “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.

Table of Contents

minLevel	1
maxLevel	2
outline	false
type	list
separator	brackets
printable	false

Overview

TODO

Excerpt

name	SummaryForParentPage

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

These APIs are called by Publishers to put data into the Learning Hub.

Data model

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`	UUID (26+128 chars) (universally unique Identifier)	`E:{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. As of 12.4, the only supported value is AI_COMP_SUCCESS, indicating a successfully completed Activity in LearningBuilder. This will probably change over time as the Hub is extended to support

...

Calling the API

...

Authentication

Method

Explanation

edits and deletes.

See also PublisherEventCategory, below.

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.

Info
Each event contains the ID of the related party in the Publisher’s system. It is up to Subscribers and Publishers to determine how those values should be mapped between their systems.

PublisherEventCategory

JSON object
optional

High level classification of this event, within the Publisher’s system.

Code Block

language	json

{
  "value": "some constant value",
  "label": "some human readable value"
}

The value property should be an ID or code that represents the event type to the Publisher.

The label property is a human readable explanation of that value, at the time of publishing.

The label can change over time, but the value should stay constant.

This data can be used by the Subscriber to map different types of Publisher data to different import templates. If omitted, Subscribers will not be able to differentiate between different types of records coming from the Publisher.

`EventType` vs `PublisherEventCategory`

EventType is a system concept that indicates if data is being reported, updated, deleted, etc. These are fixed values that have specific meaning to the Hub.

PublisherEventCategory is a Publisher concept that differentiates different types of events in their system, such as “Course” or “Exam Result”. These are NOT fixed values and will vary by Publisher. (For LearningBuilder Publishers, this will usually be the Activity Type)

Subscribers can subscribe to specific event categories for specific Publishers, with separate mapping templates for each category.

Calling the API

API Hostnames

See https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/3697770890/Learning+Hub#API-Hostnames

Authentication

See https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/3697770890/Learning+Hub#Authentication

Publishing Events into the Registry

Info
“Events” are records of activity or accomplishment. These are published by a Program and other Programs can consume them.

`POST /api/events`
Handy status macro
set 36399
isLabeled false
historySnapshotId

...

7cfb151d-

...

d309-

...

448c-

...

9e11-

...

ef4dcd1953cc
status 185953
historyChainId

...

995d84a4-485f-

...

470b-

...

These endpoints require an API Key, assigned by the system administrators.

These should be passed using Basic Authentication

If the endpoint requires a {PROGRAM_ID}, then this key must either be a SYSTEM key or have access to the specified Program.

Publishing events into the Registry

TODO

Pulling events from the Registry

...

9882-e5f4d573912a

Info

Creates a new Event in the Learning Hub and returns its system-assigned EventId.

The API Key used for authentication must have rights to modify data for PublisherProgramId.

JSON Payload

Code Block

{
    "PublisherProgramId": "YourProgramId",
    "PublisherSystemId": "YourSystemName",
    "PublisherEventId": "some_key_from_your_system",
    "EventType": "AI_COMP_SUCCESS",
    "PublisherParticipantId": "joebob@example.com",
    "PublisherEventCategory": { "value": "some_key", "label": "friendly description" },
    "PublisherEventData": { JSON },
    "EventStartUtc": "UTC date/time",
    "EventEndUtc": "UTC date/time"
}

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.

This is an arbitrary string provided by the Publisher. Can be used when a Publisher has multiple systems pushing data into the Hub.

EventType

The type of Learning Hub Event this record represents.

For now, the only supported value is “AI_COMP_SUCCESS”

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 Publisher's system.

Ideally, this is an email address or some other identifier that is shared with the Subscribers.

PublisherEventCategory

JSON object containing information about the type of Event, according to the source Program’s system.

The value should be some sort of stable identifier with meaning to the Publisher. This value will determine the Template that will be used in the /processEvent endpoint.

The label should be a human readable value that helps explain the event category to Subscribers.

Code Block
{ value: "ABC123", label: "Online Course" }

PublisherEventData

JSON object representing the Event in the source Program’s system. When calling /processEvents endpoint, this data will be put thru a template and sent to learningBuilder.

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.

PublisherEventData Node Example

The exact fields and field names in the PublisherEventData node will be determined as part of the implementation process, as these are determined by the LearningBuilder instance configuration and that data the Publisher is providing to the LearningHub.

The below payload is provided for example purposes only. Please contact your implementation contact to finalize the event data requirements.

Code Block

{
  "PublisherEventData": {
    ":ActivityId": "A0099999",
    ":Completion Date": "2024-08-03T21:43:58Z",
    ":LearningPlanName": "Recertification Application",
    ":Member Name": "Redacted Name",
    ":Product ID": "000",
    ":RoleLabel": "RN",
    ":TaskGroupName": "Reported Contact Hours",
    ":UniqueId": "439BB892-FE3C-4B5D-A8EA-6130F10xxxxx",
    "ActivityTypeId": 000,
    "Contact Hours Designation": "Medical-Surgical",
    "Course Name": "Reduction of Pain in a Medical Unit",
    "Education Provider": "NEA",
    "Granted Units": "1.30",
    "Is Provider Verified": true,
    "Requested Units": "1.30",
    "WorkflowActionName": "Submit"
   }
 }

Responses

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}`
Handy status macro
set 36399
isLabeled false
historySnapshotId 7cfb151d-d309-448c-9e11-ef4dcd1953cc
status 185953
historyChainId 995d84a4-485f-470b-9882-e5f4d573912a

Info

Deletes an existing Event.

The API Key used for authentication must have access to the Program that owns the Event.

Responses

Response Code	Headers and Body
204 (No Content)	Delete was performed successfully. No body is returned.

...

Pulling events from the Registry

Info
Event data is optimized for retrieval since the last sync date.

`GET /api/events/{programId}`
Handy status macro
set 36399
isLabeled false
historySnapshotId 7cfb151d-d309-448c-9e11-ef4dcd1953cc
status 185953
historyChainId 995d84a4-485f-470b-9882-e5f4d573912a

Info

Returns a list of Events published by the specified Program and matching the criteria provided as querystring arguments.

The API Key must belong to {programId}, or to a Program with an active subscription to {programId}.

Querystring parameters

Parameter	Description
`createdOnUtc`	(required) The created-on date to match. Date format `"YYYYMMDD"`

Responses

Response Code

Headers and Body

200 (Ok)

Code Block

language	json

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

...

Version	Old Version 5	New Version Current
Changes made by	Seth Petry-Johnson	Justin Brown
Saved on	Nov 14, 2023	Oct 29, 2024

Content Comparison

Versions Compared

Key

Overview

Data model

EVENT

Calling the API

Authentication

EventType vs PublisherEventCategory

Calling the API

API Hostnames

Authentication

Publishing Events into the Registry

POST /api/events Handy status macroset36399isLabeledfalsehistorySnapshotId

7cfb151d-

d309-

448c-

9e11-

ef4dcd1953ccstatus185953historyChainId

995d84a4-485f-

470b-

Publishing events into the Registry

Pulling events from the Registry

9882-e5f4d573912a

JSON Payload

PublisherEventData Node Example

Responses

DELETE /api/events/{eventId} Handy status macroset36399isLabeledfalsehistorySnapshotId7cfb151d-d309-448c-9e11-ef4dcd1953ccstatus185953historyChainId995d84a4-485f-470b-9882-e5f4d573912a

Responses

Pulling events from the Registry

GET /api/events/{programId} Handy status macroset36399isLabeledfalsehistorySnapshotId7cfb151d-d309-448c-9e11-ef4dcd1953ccstatus185953historyChainId995d84a4-485f-470b-9882-e5f4d573912a

Querystring parameters

Responses

`EventType` vs `PublisherEventCategory`

`POST /api/events`
Handy status macro
set 36399
isLabeled false
historySnapshotId

ef4dcd1953cc
status 185953
historyChainId

`DELETE /api/events/{eventId}`
Handy status macro
set 36399
isLabeled false
historySnapshotId 7cfb151d-d309-448c-9e11-ef4dcd1953cc
status 185953
historyChainId 995d84a4-485f-470b-9882-e5f4d573912a

`GET /api/events/{programId}`
Handy status macro
set 36399
isLabeled false
historySnapshotId 7cfb151d-d309-448c-9e11-ef4dcd1953cc
status 185953
historyChainId 995d84a4-485f-470b-9882-e5f4d573912a