Learning Hub: Event Subscription API
- Seth Petry-Johnson
- Justin Brown
As of the 12.4 release, Event Subscriptions are editable through LearningBuilder for LearningBuilder Subscribers.
Overview
Subscribers must “subscribe” to a Program in order to pull its data from the Hub. The Publisher’s data are not publicly accessible to prevent it from being scraped, and to give Publishers controls over their data.
API Hostnames
See Learning Hub | API Hostnames
Authentication
See Learning Hub | Authentication
Unless otherwise specified, all endpoints on this page require an API Key with SYSTEM permissions.
Data model
SUBSCRIPTION | ||
|---|---|---|
A Subscription is a relationship from a Subscriber to a Publisher that allows the Subscriber to receive the Publisher’s data. | ||
Field | Type | Notes |
| string (25 char) | The identifier of the Subscriber |
| string (25 char) | The identifier of the Publisher |
| UTC date/time | UTC timestamp of the last time the Subscriber pulled data from this Publisher |
| boolean | Whether or not the subscription supports the nightly sync process. (Applies to LearningBuilder Subscribers only) |
| JSON | JSON structure mapping different See below for detailed explanation |
LbApiPayloadTemplate syntax and purpose
Publishers and Subscribers think about and model their data differently, so the Publisher’s data typically needs modified or converted before it can be imported into LearningBuilder.
Each Event Subscription specifies:
Which
PublisherEventCategoryvalues it cares aboutA Handlebars template that specifies how to convert
Eventsof that category into a JSON format that can be imported through the Subscriber’s API/WorkflowImportQueue/CreateBatch API.For more information about Handlebars Templates Introduction | Handlebars
For more info on the data manipulation Helpers available, please refer GitHub - Handlebars-Net/Handlebars.Net.Helpers: Handlebars.Net helpers in the categories: 'Boolean', 'Constants', 'Enumerable', 'Environment', 'Math', 'Regex', 'String', 'DateTime' and 'Url'.
Those templates are stored as the batchRowTemplate property in the LbApiPayloadTemplatef an EventSubsription:
"LbApiPayloadTemplate": {
"{EventCategory1}": {
"action": "import (default) | ignore",
"label": "human readable note",
"importProcessId": {WIQ Process Id},
"batchRowTemplate": "{handlebars template}"
},
// ... additional category mappings as needed ...
"_default": {
"action": "import (default) | ignore",
"label": "human readable note",
"importProcessId": {WIQ Process Id},
"batchRowTemplate": "{handlebars template}"
}
}Each key within the LbApiPayloadTemplate should match one of the Publisher’s PublisherEventCategory values, or the special marker “_default” which indicates a default template.
There are two reasons to include a PublisherEventCategory mapping:
To import it into the Subscriber, using the specified
batchRowTemplateTo ignore it, because the Subscriber isn’t interested in that category of Publisher data
Syntax examples
Example / scenario | Sample |
|---|---|
Subscribe to all Publisher event categories, using the same template for everything | "LbApiPayloadTemplate": {
"_default": {
"action": "import",
"label": "Import everything",
"importProcessId": {WIQ Process Id},
"batchRowTemplate": "{handlebars template}"
}
} |
Subscribe to all Publisher event data, with special handling for a specific category | "LbApiPayloadTemplate": {
"some_key": {
"action": "import",
"label": "ACME Course",
"importProcessId": {WIQ Process Id},
"batchRowTemplate": "{handlebars template}"
},
"_default": {
"action": "import",
"label": "Import everything",
"importProcessId": {WIQ Process Id},
"batchRowTemplate": "{handlebars template}"
}
} |
Subscribe to a specific category only, ignoring everything else | |
Ignore a specific category, process everything else using a common template |
Detailed data flow
It works like this:
When Publishers push data into the Hub, they specify a
PublisherEventCategoryvalue. (For example, this might differentiate between data representing a completed course and data representing work history)A Subscriber’s
EventSubscriptioncontain contain one or more templates, each one mapped to a specificPublisherEventCategoryvalue. (This allows the Subscriber to convert those courses and work history entries in different ways)Each template converts a single
PublisherEventDataJSON object into a different JSON schema that can be passed to the Subscriber’s API/WorkflowImportQueue/CreateBatch API endpoint.When LearningBuilder synchronizes data, it loops through each
PublisherEventDataitem, converts it using the relevant template, and then makes a single call to API/WorkflowImportQueue/CreateBatch to import the data.
PublisherEventData being converted into a /API/WorkflowImportQueue/CreateBatch API callEvent Subscriptions
GET /api/programs/{programId}/eventSubs
Responses
Response Code | Headers and Body |
|---|---|
200 (Ok) |
GET /api/programs/{programId}/eventSubs/{publisherProgramId}
Responses
Response Code | Headers and Body |
|---|---|
200 (Ok) |
POST /api/programs/{programId}/eventSubs
JSON Payload
Responses
Response Code | Headers and Body |
|---|---|
201 (Created) | A new Event Subscription was created. No body is returned. HTTP headers:
|
PATCH /api/programs/{programId}/eventSubs/{publisherProgramId}
JSON Payload
Responses
Response Code | Headers and Body |
|---|---|
204 (No Content) | Update was performed successfully. No body is returned. |
DELETE /api/programs/{programId}/eventSubs/{publisherProgramId}
Responses
Response Code | Headers and Body |
|---|---|
204 (No Content) | Delete was performed successfully. No body is returned. |