Learning Hub: Event Subscription API

Owned by Seth Petry-Johnson
Last updated: Oct 29, 2024 by Justin Brown
5 min read

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

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

ProgramId

string (25 char)

The identifier of the Subscriber

PublisherProgramId

string (25 char)

The identifier of the Publisher

LastSyncUtc

UTC date/time

UTC timestamp of the last time the Subscriber pulled data from this Publisher

SyncEnabled

boolean

Whether or not the subscription supports the nightly sync process. (Applies to LearningBuilder Subscribers only)

LbApiPayloadTemplate

JSON

JSON structure mapping different PublisherEventCategory values to the Handlebars template that converts those Events into a batch row payload for LearningBuilder’s WorkflowImportQueue/CreateBatch API.

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 PublisherEventCategory values it cares about

  • A Handlebars template that specifies how to convert Events of that category into a JSON format that can be imported through the Subscriber’s API/WorkflowImportQueue/CreateBatch API.

Those templates are stored in the LbApiPayloadTemplate property of 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 batchRowTemplate

  • To ignore it, because the Subscriber isn’t interested in that category of Publisher data

Syntax examples

Example / scenario

Sample LbApiPayloadTemplate

Example / scenario

Sample LbApiPayloadTemplate

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 PublisherEventCategory value. (For example, this might differentiate between data representing a completed course and data representing work history)

  • A Subscriber’s EventSubscription contain contain one or more templates, each one mapped to a specific PublisherEventCategory value. (This allows the Subscriber to convert those courses and work history entries in different ways)

  • Each template converts a single PublisherEventData JSON 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 PublisherEventData item, converts it using the relevant template, and then makes a single call to API/WorkflowImportQueue/CreateBatch to import the data.

image-20240911-171330.png
PublisherEventData being converted into a /API/WorkflowImportQueue/CreateBatch API call

Event Subscriptions

GET /api/programs/{programId}/eventSubs

Responses

Response Code

Headers and Body

Response Code

Headers and Body

200 (Ok)

GET /api/programs/{programId}/eventSubs/{publisherProgramId}

Responses

Response Code

Headers and Body

Response Code

Headers and Body

200 (Ok)

POST /api/programs/{programId}/eventSubs

JSON Payload

Responses

Response Code

Headers and Body

Response Code

Headers and Body

201 (Created)

A new Event Subscription was created. No body is returned.

HTTP headers:

Location: /API/programs/{programId}/eventSubs/{pubProgId}

PATCH /api/programs/{programId}/eventSubs/{publisherProgramId}

JSON Payload

Responses

Response Code

Headers and Body

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

Response Code

Headers and Body

204 (No Content)

Delete was performed successfully. No body is returned.