Info
Although these APIs are publicly documented, the management of Event Subscriptions is currently handled by Heuristics staff due to the complex templating that is involvedAs of the 12.4 release, Event Subscriptions are editable through LearningBuilder for LearningBuilder Subscribers.

Table of Contents

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

...

Excerpt

hidden	true

RESTful APIs for establishing subscriptions between Programs.

Publisher data is 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.

Therefore, Subscribers must “subscribe” to a Program in order to pull its data from the Hub.

Heuristics staff establish these relationships partially to manage the complex templates that are required, but also to ensure that the Subscriber has a legitimate need to access that Publisher’s data

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

Note
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

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. (LB subscribers Applies to LearningBuilder Subscribers only)

Note
Setting this to TRUE does not automatically enable the nightly sync, it just allows the nightly sync to process this subscription.

LbApiPayloadTemplate

string

JSON

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

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

Note
Unless otherwise specified, all endpoints on this page require an API Key with SYSTEM permissions.

See below for detailed explanation

`LbApiPayloadTemplate` syntax and purpose

This section applies specifically to Subscribers using LearningBuilder. Other systems will need to implement their own mechanism for processing data from the Hub.

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:

Code Block

language	json

"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

Subscribe to all Publisher event categories, using the same template for everything

Code Block

language	json

"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

Code Block

language	json

"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

Code Block

language	json

"LbApiPayloadTemplate": {
  "COURSE": {
    "action": "import",
    "label": "ACME course",
    "importProcessId": {WIQ Process Id},
    "batchRowTemplate": "{handlebars template}"
  },
  "_default": {
    "action": "ignore",
    "label": "Nothing else matters"
  }
}

Ignore a specific category, process everything else using a common template

Code Block

language	json

"LbApiPayloadTemplate": {
  "SOME_CATEGORY": {
    "action": "ignore",
    "label": "ACME course"
  },
  "_default": {
    "action": "import",
    "importProcessId": {WIQ Process Id},
    "batchRowTemplate": "{handlebars template}"
  }
}

Omitting the “_default” mapping has the same result as setting it to "action": "ignore", but it is recommended to explicitly include the default mapping to make the configuration easier to understand.

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.

...

Event Subscriptions

Info
“Event Subscriptions” track which Programs will receive the Events published by other Programs.

...

Response Code

Headers and Body

200 (Ok)

Code Block

language	json

[
  { 
    "ProgramId": "subscriber_program_id", 
    "PublisherProgramId": "publisher_program_id", 
    "CreatedUtc": "UTC date/time",
    "LastSyncUtc": "UTC date/time",
    "SynEnabled": true,
    "LbApiPayloadTemplate": {
      "SOME_CATEGORY": {
        "action": "import",
        "label": "...""ACME Course",
        "importProcessId": {WIQ Process Id},
        "batchRowTemplate": "{handlebars template}"
      }
    }    
  },
  ...
]

...

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

...

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

Info
Returns the details about `{programId}`'s subscription to `{publisherIdpublisherProgramId}`'s Events.

Responses

Response Code

Headers and Body

200 (Ok)

Code Block

language	json

{ 
  "ProgramId": "foo", 
  "PublisherProgramId": "bar", 
  "CreatedUtc": "UTC date/time",
  "LastSyncUtc": "UTC date/time",
  "SynEnabled": true,
  "LbApiPayloadTemplate": "..." { see docs above }  
}

...

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

Info

Creates a new Event Subscription. Returns an error if it already exists.

Audit fields such as CreatedUtc are assigned during creation.

JSON Payload

Code Block

{
  "PublisherProgramId": "PublisherProgramId",
  "PublisherProgramIdSyncEnabled": true,
  "LbApiPayloadTemplate": {
    "SOME_CATEGORY": {
      "action": "import",
      "label": "PublisherIdACME Course",
      "SyncEnabledimportProcessId": true,{WIQ Process Id},
      "LbApiPayloadTemplatebatchRowTemplate": "..."{handlebars template}"
    }
  }    
}

Responses

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

Info
Updates an existing Event Subscription.

...

Code Block
{ "LastSyncUtc": "date", "SyncEnabled": true, "LbApiPayloadTemplate": "..." { see docs above } }

Responses

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

...

`DELETE /api/programs/{programId}/eventSubs/{`

...

`publisherProgramId}`
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 Subscription.

...

Versions Compared

Old Version 1

New Version Current

Key

API Hostnames

Authentication

Data model

SUBSCRIPTION

Calling the API

API Hostnames

Authentication

`LbApiPayloadTemplate` syntax and purpose

Syntax examples

Detailed data flow

Event Subscriptions

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

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

Responses

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

JSON Payload

Responses

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

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

Responses

`DELETE /api/programs/{programId}/eventSubs/{`

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

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

API Hostnames

Authentication

Data model

SUBSCRIPTION

Calling the API

API Hostnames

Authentication

LbApiPayloadTemplate syntax and purpose

Syntax examples

Detailed data flow

Event Subscriptions

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

publisherProgramId} Handy status macroset36399isLabeledfalsehistorySnapshotId7cfb151d-d309-448c-9e11-ef4dcd1953ccstatus185953historyChainId995d84a4-485f-470b-9882-e5f4d573912a

Responses

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

JSON Payload

Responses

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

publisherProgramId} Handy status macroset36399isLabeledfalsehistorySnapshotId7cfb151d-d309-448c-9e11-ef4dcd1953ccstatus185953historyChainId995d84a4-485f-470b-9882-e5f4d573912a

Responses

DELETE /api/programs/{programId}/eventSubs/{

publisherProgramId} Handy status macroset36399isLabeledfalsehistorySnapshotId7cfb151d-d309-448c-9e11-ef4dcd1953ccstatus185953historyChainId995d84a4-485f-470b-9882-e5f4d573912a

`LbApiPayloadTemplate` syntax and purpose

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

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

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

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

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

`DELETE /api/programs/{programId}/eventSubs/{`

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