Versions Compared

Version Old Version 25 New Version Current
Changes made by

Seth Petry-Johnson

Justin Brown

Saved on

Key

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

...

Excerpt
nameSummaryForParentPage

RESTful APIs for the “Event Store” functionality of the Learning Hub, where the hub acts as a centralized “clearinghouse” of accomplishments and activities.

These APIs are called by Publishers to put data into the Learning Hub.

Data model

FUTURE USE

, indicating a successfully completed Activity in LearningBuilder.

This will probably change over time as the Hub is extended to support edits and deletes.

See also PublisherEventCategory, below.

EVENT

An Event is the thing being recorded in the hub: user completed a course, earned a credential, etc.

This design is influenced by the idea of a Learning Record Store in xAPI, but with less complexity.

Field

Type

Notes

EventId

PRG-UUID
(26+128 chars)

(universally unique Identifier)

E:{ProgramId}-{UUID}

The {ProgramId} helps guarantee uniqueness but also to make the IDs more human readable.

Event Ids are assigned by the Learning Hub.

PublisherProgramId

string (25 char)

Descriptive name for the Program that published this event.

PublisherSystemId

string (25 char)

Identifier for the type of system that published this data.

Currently, only the value “LB” is supported, for LearningBuilder.

EventType

string (50 char)

The type of event as reported by the publisherPublisher.

This list of possible types will vary by PublisherSystemId. For LearningBuilder this will be one of:

As of 12.4, the only supported value is AI_COMP_SUCCESS

- Complete Activity WFsuccessful

  • LPI_STARTED -

    Status
    titleFUTURE USE

  • LPI_COMP_UNSUCCESS -

    Status
    titleFUTURE USE

  • LPI_COMP_SUCCESS -

    Status
    titleFUTURE USE

  • LPI_REOPENED -

    Status
    titleFUTURE USE

  • AI_STARTED -

    Status
    titleFUTURE USE

  • AI_COMP_UNSUCCESS -

    Status
    titleFUTURE USE

    • AI_REOPENED - Recalled from complete to incomplete -
    Status
    title

    PublisherEventId

    string (200 char)

    The Program’s unique identifier for the source event.

    For LearningBuilder this will be something like “AI:1234”, which would be the Activity Instance WFI #1234

    PublisherParticipantId

    string (200 char)

    The Program’s unique identifier for the person, organization, or entity that the event relates to.

    Info

    Each event contains the ID of the related party in the publisher’s Publisher’s system. It is up to subscribers Subscribers and publishers Publishers to determine how those values should be mapped between their systems.

    PublisherEventCategory

    JSON object
    optional

    High level classification of this event, within the publisher’s Publisher’s system.

    Code Block
    languagejson
    {
  "value": "some constant value",
  "label": "some human readable value"
}

    The value property should be an ID or code that represents the event type to the publisherPublisher.

    The label property is a human readable explanation of that value, at the time of publishing.

    The label can change over time, but the value should stay constant.

    This data can be used by the subscriber Subscriber to map different types of publisher Publisher data to different import templates. If omitted, subscribers Subscribers will not be able to differentiate between different types of records coming from the publisher.Publisher.

    See also:

    PublisherEventData

    JSON blob

    The Publisher’s representation of the event data.

    Info

    The schema of this JSON structure should be shared with the Subscriber(s), so that they know how to translate it into their own representation in their Event Subscriptions.

    EventStartUtc

    UTC date/time

    Non-null date/time the event started. (If only a single date/time is associated with the event, it is stored here).

    EventEndUtc

    UTC date/time

    Nullable date/time that the event ended.

    CreatedUtc

    UTC date/time

    UTC timestamp when this record was created.

    Event Type

    Different systems track different types of events, and different types of events may be associated with different data fields. Additionally, subscribers may only care about certain types of events from a given publisher.

    ...

    EventDateBucket

    string

    {ProgramId}-LB-YYYYMMDD

    Gathers the year, month, and date from the CreatedUtc field.

    Identifier used by the LearningHub query that gathers events to process.

    EventType vs PublisherEventCategory

    EventType is a system concept that indicates if data is being reported, updated, deleted, etc. These are fixed values that have specific meaning to the Hub.

    PublisherEventCategory is a Publisher concept that differentiates different types of events in their system, such as “Course” or “Exam Result”. These are NOT fixed values and will vary by Publisher. (For LearningBuilder Publishers, this will usually be the Activity Type)

    Subscribers can subscribe to specific event categories for specific Publishers, with separate mapping templates for each category.

    Calling the API

    API Hostnames

    ...

    Code Block
    {
    "PublisherProgramId": "ProgramIdYourProgramId",
    "PublisherSystemId": "LBYourSystemName",
    "PublisherEventId": "some_key_from_your_idsystem",
    "EventType": "Event Type indicatorAI_COMP_SUCCESS",
    "PublisherParticipantId": "joebob@example.com",
    "PublisherEventCategory": { "value": "some_key", "label": "friendly valuedescription" },
    "PublisherEventData": { JSON },
    "EventStartUtc": "UTC date/time",
    "EventEndUtc": "UTC date/time"
}

    Parameter

    Description

    PublisherProgramId

    The Program that owns the Event.

    The API Key must have access to this Program.

    PublisherSystemId

    The type of system that published the event. For now, only “LB” is supported

    This is an arbitrary string provided by the Publisher. Can be used when a Publisher has multiple systems pushing data into the Hub.

    EventType

    The type of Learning Hub Event this record represents.See the “Event Types” section, above.

    For now, the only supported value is “AI_COMP_SUCCESS”

    PublisherEventId

    A value that uniquely identifies this event in the publisher’s Publisher’s system.

    For LearningBuilder publishersPublishers, this will be an “entity-scoped identifier” such as AI:1234, representing Activity Instance 1234.

    PublisherParticipantId

    Email address or some other piece of information that uniquely identifiers the primary participant within the publisherPublisher's system.

    Ideally, this is an email address or some other identifier that is shared with the Subscribers.

    PublisherEventCategory

    JSON object containing information about the type of Event, according to the source Program’s system.

    The value should be some sort of stable identifier with meaning to the publisherPublisher. This value will determine the Template that will be used in the /processEvent endpoint.

    The label should be a human readable value that helps explain the event category to subscribersSubscribers.

    Code Block
    { value: "ABC123", label: "Online Course" }

    PublisherEventData

    JSON object representing the Event in the source Program’s system. When calling /processEvents endpoint, this data will be put thru a template and sent to learningBuilder.

    EventStartUtc

    The UTC date/time when this Event occurred, or the time that the Event started.

    EventEndUtc

    The UTC date/time when this Event ended. For Events with only a single timestamp, rather than a range, set this equal to EventStartUTC.

    PublisherEventData Node Example

    The exact fields and field names in the PublisherEventData node will be determined as part of the implementation process, as these are determined by the LearningBuilder instance configuration and that data the Publisher is providing to the LearningHub.

    The below payload is provided for example purposes only. Please contact your implementation contact to finalize the event data requirements.

    Code Block
    {
  "PublisherEventData": {
    ":ActivityId": "A0099999",
    ":Completion Date": "2024-08-03T21:43:58Z",
    ":LearningPlanName": "Recertification Application",
    ":Member Name": "Redacted Name",
    ":Product ID": "000",
    ":RoleLabel": "RN",
    ":TaskGroupName": "Reported Contact Hours",
    ":UniqueId": "439BB892-FE3C-4B5D-A8EA-6130F10xxxxx",
    "ActivityTypeId": 000,
    "Contact Hours Designation": "Medical-Surgical",
    "Course Name": "Reduction of Pain in a Medical Unit",
    "Education Provider": "NEA",
    "Granted Units": "1.30",
    "Is Provider Verified": true,
    "Requested Units": "1.30",
    "WorkflowActionName": "Submit"
   }
 }

    Responses

    Response Code

    Headers and Body

    201 (Created)

    A new Event was created. No body is returned.

    HTTP headers:

    Location: /events/{eventId}

    ...