| 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 | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Overview
...
| Excerpt | ||
|---|---|---|
| ||
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 to support system integrations. |
Calling the API
...
Authentication
...
Method
...
Explanation
...
| Handy status macro | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
...
These endpoints require an API Key, assigned by the system administrators.
These should be passed using Basic Authentication
Configuration and diagnostics
/health
| Handy status macro | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
| Handy status macro | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
| Info |
|---|
Returns a summary of the configuration’s health. Indicates if it is properly configured for the specified client and the results of any diagnostics that are run. |
...
. 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 | |||||
| UUID (universally unique Identifier) |
The Event Ids are assigned by the Learning Hub. | |||||
| string (25 char) | Descriptive name for the Program that published this event. | |||||
| string (25 char) | Identifier for the type of system that published this data. Currently, only the value “LB” is supported, for LearningBuilder. | |||||
| 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 edits and deletes. See also | |||||
| 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 | |||||
| string (200 char) | The Program’s unique identifier for the person, organization, or entity that the event relates to.
| |||||
| JSON object | High level classification of this event, within the Publisher’s system.
The The The 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. See also: | |||||
| JSON blob | The Publisher’s representation of the event data.
| |||||
| 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). | |||||
| UTC date/time | Nullable date/time that the event ended. | |||||
| UTC date/time | UTC timestamp when this record was created. | |||||
| string |
Gathers the year, month, and date from the Identifier used by the LearningHub query that gathers events to process. | |||||
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
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 | |||||
|---|---|---|---|---|---|
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
| Info |
|---|
Creates a new Event in the Learning Hub and returns its system-assigned The API Key used for authentication must have rights to modify data for |
JSON Payload
| Code Block |
|---|
{
"PublisherProgramId": "YourProgramId",
"ClientId "PublisherSystemId": "YourSystemName",
"PublisherEventId": "{{lb_client_id}}some_key_from_your_system",
"ClientCredentialsEventType": {
"AI_COMP_SUCCESS",
"PublisherParticipantId": "joebob@example.com",
"PublisherEventCategory": { "value": "UserApiKeys"some_key", "label": "friendly [description" },
"PublisherEventData": { JSON },
{ "userEventStartUtc": "LearningBuilderUTC date/time",
"api_keyEventEndUtc": "abcdef123", "scope": "SYSTEM" },
{ "user": "joe_schmoe", "api_key": "abcdef123", "scope": "SYSTEM" },
{ "user": "bob_dylan", "api_key": "defabc654", "scope": "CLIENT" }
],
"LbApiKeyOwner": "{{lb_api_key_username}}",
"LbApiKey": "{{lb_api_key_password}}"
},
"ClientSettings": {
}
} |
...
Parameter
...
Description
...
ClientId
...
Client Id that is used in learning builder
...
ClientCredentials
...
UserApiKeys
...
An array of API Keys for individual users. These are used to make API calls against the Lambda endpoints.
The scope is either “SYSTEM” or “CLIENT”.
...
LbApiKeyOwner
...
LearningBuilder API key. Used when the Lambda makes API calls to LearningBuilder.
...
LbApiKey
...
ClientSettings
...
LbHostOverride
...
The hostname to use when making API calls back to LearningBuilder.
When empty, the Lambda uses the LbConfiguration.ClientLbDomain value for {CLIENT_ID}
If you need to override that value during testing or troubleshooting, enter the fully qualified hostname here.
...
UTC date/time"
} |
Parameter | Description | ||
|---|---|---|---|
| The Program that owns the Event. The API Key must have access to this Program. | ||
| 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. | ||
| The type of Learning Hub Event this record represents. For now, the only supported value is “AI_COMP_SUCCESS” | ||
| A value that uniquely identifies this event in the Publisher’s system. For LearningBuilder Publishers, this will be an “entity-scoped identifier” such as | ||
| 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. | ||
| JSON object containing information about the type of Event, according to the source Program’s system. The The
| ||
| JSON object representing the Event in the source Program’s system. When calling | ||
| The UTC date/time when this Event occurred, or the time that the Event started. | ||
| The UTC date/time when this Event ended. For Events with only a single timestamp, rather than a range, set this equal to |
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:
|
...
DELETE /api/events/{eventId}
| Handy status macro | |
|---|---|
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
| 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 | |||||
|---|---|---|---|---|---|
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
| Info |
|---|
Updates one or more of the configuration settings at a time, without sending the entire configuration document. NOTE: This can not be used to change API Key credentials. Use |
JSON Payload
| Code Block |
|---|
| { Returns a list of Events published by the specified Program and matching the criteria provided as querystring arguments. The API Key must belong to |
Querystring parameters
Parameter | Description |
|---|---|
| (required) The created-on date to match. Date format |
Responses
Response Code | Headers and Body | |||||
|---|---|---|---|---|---|---|
200 (Ok) |
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
Parameter
...
Description
...
settings
...
Array of settings to set
...
name
...
Name of the setting to update.
This must be “scope-prefixed” with the name of the relevant settings bucket, e.g.:
“ClientCredentials.NursysUsername”
“ClientSettings.SomeValue”
...
value
...
Value to set
...
| Handy status macro | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
| Info |
|---|
Adds or updates API Keys for individual users. |
JSON Payload
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...