Although these APIs are publicly documented, the management of Event Subscriptions is currently handled by Heuristics staff due to the complex templating that is involved.
Overview
Publisher data is 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
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) Setting this to TRUE does not automatically enable the nightly sync, it just allows the nightly sync to process this subscription. |
| JSON | JSON structure mapping different {
"{EventCategory}": {
"label": "human readable note",
"importProcessId": {WIQ Process Id},
"batchRowTemplate": "{handlebars template}"
}
}
See below for detailed explanation |
Converting Provider data into Subscriber data
Publishers and Subscribers think about and model their data differently. Each Event Subscription contains one or more templates that convert from the Provider’s data model into the Subscriber’s data model.
Each template is mapped to a PublisherEventCategory value. The template is responsible for converting the PublisherEventData JSON, for that category value, into a BatchRowvalue that can be passed into API/WorkflowImportQueue/CreateBatch.
Event Subscriptions
“Event Subscriptions” track which Programs will receive the Events published by other Programs.
GET /api/programs/{programId}/eventSubs
Returns a list of Event Subscriptions for the specified Program.
Responses
Response Code | Headers and Body |
|---|---|
200 (Ok) | [
{
"ProgramId": "subscriber_program_id",
"PublisherProgramId": "publisher_program_id",
"CreatedUtc": "UTC date/time",
"LastSyncUtc": "UTC date/time",
"SynEnabled": true,
"LbApiPayloadTemplate": "..."
},
...
]
|
GET /api/programs/{programId}/eventSubs/{publisherId}
Returns the details about {programId}'s subscription to {publisherId}'s Events.
Responses
Response Code | Headers and Body |
|---|---|
200 (Ok) | {
"ProgramId": "foo",
"PublisherProgramId": "bar",
"CreatedUtc": "UTC date/time",
"LastSyncUtc": "UTC date/time",
"SynEnabled": true,
"LbApiPayloadTemplate": "..."
}
|
POST /api/programs/{programId}/eventSubs
Creates a new Event Subscription. Returns an error if it already exists.
Audit fields such as CreatedUtc are assigned during creation.
JSON Payload
{
"PublisherProgramId": "PublisherId",
"SyncEnabled": true,
"LbApiPayloadTemplate": "..."
}
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/{publisherId}
Updates an existing Event Subscription.
JSON Payload
{
"LastSyncUtc": "date",
"SyncEnabled": true,
"LbApiPayloadTemplate": "..."
}
Responses
Response Code | Headers and Body |
|---|---|
204 (No Content) | Update was performed successfully. No body is returned. |
DELETE /api/programs/{programId}/eventSubs/{publisherId}
Deletes an existing Event Subscription.
Responses
Response Code | Headers and Body |
|---|---|
204 (No Content) | Delete was performed successfully. No body is returned. |