Versions Compared

Old Version 1

changes.mady.by.user Seth Petry-Johnson

Saved on

compared with

New Version 2

changes.mady.by.user Seth Petry-Johnson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info

This document contains a high level guide to developing an integration that puts data into the Learning Hub.

See also: Learning Hub: Subscriber Development Guide

Overview

This document contains a high level guide to developing an integration as a Publisher into the Learning Hub.

Step 1 - Preparation

1

Determine how to represent the “participant” in the payload

There is no guarantee that a person will be identified the same way in the Publisher and Subscriber systems. For instance, a Practitioner might use their personal email address in one system and a work email address in another.

In order for those two systems to integrate, they will need to agree on a shared identifier that is the same in both systems. That value must be included in the publisherEventData JSON object.

You should NOT use an internal identifier (such as a user_id value) unless you have a system in place to provide those values to your Subscribers.

2

Obtain an API Key to access the Learning Hub

You will need to contact Heuristic Solutions Technical Support to obtain credentials to access the Hub.

You will be assigned a Program Id, which is your identifier to the Hub, and an API Key that authenticates you as that Program.

Step 2 - Use the Event Store API

1

Prepare a JSON structure representing your data

This can be whatever makes sense for your use case, as long as it is valid JSON syntax.

The Learning Hub does not require you to publish or adhere to a specific schema, but you will need to share this with your Subscriber(s) so that they can configure their part of the exchange.

The sharing of that data occurs outside of the Learning Hub.

2

Send an event to the Hub

Using the POST /api/events API, send your event to the Hub.

See the documentation for a full explanation of the payload structure, but here are some quick pointers:

  • PublisherSystemId can be any string you want. Use it to differentiate data from different sources, if you have multiple systems pushing into the Hub.

  • PublisherEventId should be a unique identifier to the Event you are publishing. Typically, this will be some primary key from your source system.

  • PublisherEventCategory should be a JSON structure containing a “type” identifier that is meaningful in your system (“ABC123”, “104121”, etc), and a human-readable label that identifies that value to Subscribers.

  • PublisherEventData is the JSON structure representing your event

3

Confirm the event details were correctly recorded

The Event Store APIs can also be used to retrieve data from the hub.

Step 3 - Share data with Subscribers

1

Document your event schema

In order to use your data, Subscribers will need to know at least two things:

  • What value are you using as PublisherParticipantId? Is it an email address or a license number that the Subscriber will already know?

  • What is the schema of your PublisherEventData structure? Subscribers will need to know which fields are included so that they can map the data into their own system.

The sharing of that data occurs outside of the Learning Hub.