Related Training

Pull an HTML page into your App Configuration

Purpose

The Related Training extension allows you to link together external training documents to content living within Seismic. Your training content is easily accessed through Seismic's interface.

Common use cases include:

  • Helping your Seismic users to find the correct training for the correct piece of content

App Prerequisites

  • Your app must be configured with the Related Training extension

How it works

High level flow

  1. When an app on your tenant contains the Related Training extension then the "Related training" section is available in the Seismic UI.
    1. This is available through Content Manager, Collections, or Library, which are typically only accessed by those with administrator privileges, i.e., Premium Users
  2. From within Seismic, an admin clicks the button "+ Add Training" which opens a content picker, giving you the ability to select related contents
  3. Once external content is linked to Seismic content, your Seismic end-users will see the content on the side of the Seismic UI under the 'Related Training' widget

When it's triggered

  • When an admin clicks in the Library's Related Training widget to add or remove content associations. Seismic is looking for a complete list of available content that could be selected. There is no search term provided yet.
  • While an admin is looking for external content to associate to this piece of Sesimic content and they execute a search from within the Content Picker. Seismic sends over the search term that are input and expects back a list of acceptable content to expose in the picker.
  • When an admin expands the Related Training widget from the Library. Seismic is looking for the details of the already related content, via the stored IDs of your external content.
  • When a business user loads a piece of content in DocCenter when it has Related Training associated with it. Seismic is looking for the details of the already related content, via the stored IDs of your external content.
  • When a piece of Seismic content is associated or disassociated from your external content. Seismic will let your system know Seismic's content ID and teamsite ID and also validate the external content details.

Security & Authentication

It is recommended to validate the Signing Secret in the POST request that Seismic is making

How to Configure

Configure the Related Training extension point

  1. Add the Related Training extension to your application as described here

Field name

Data type

Description

Notes

Extension Instance Name

string

The name by which this extension point is identified

Visible to tenant admins that install your app

Data Fetch URL

URL

The endpoint that we will call to get the data for the content picker

Supports search criteria

Default State Label

string

A label that we show on the initial launch of the content picker

Optional

Linked Content Callback URL

URL

An endpoint we can call after content has been successfully linked or de-linked

Optional

Default State URL

URL

An alternate URL we will post to for the initial load of the content picker

Optional

Payloads

Outbound payload from Seismic to your endpoint(s)

When the content picker is launched from Seismic's UI by an admin, we will PSOT this body to your Data Fetch URL or Default State URL. This is identical to the Search Extension POST Payload

Field name

Field type

Description

filters

object

Contains the filters & filter values selected by the user

filters.type

string

The name of the field that is being filtered on

filters.values

string array

Comma delimited list of values for a given filter type

term

string

The keywords / text provided by the user for their search

pageNumber

integer

Indicates which page of results are being surfaced in Seismic

state

string

Seismic will echo back to you the most recent State value you sent. This is useful for cursor-based pagination

surface

string

The location within Seismic where the user engaged the Related Training widget

  • library - when ad admin is doing it
  • DocCenter - when an end user is doing it
{
    "filters": null,
    "appId": "b7f07df8-9ebb-487a-98b8-471ececc5f46",
    "appName": "Extension Point Test App",
    "version": "0.6.12",
    "requestId": "b9636638-f488-4408-b457-5e9e8eac5c9f",
    "tenant": "wannabelikemike",
    "tenantId": "cc881086-49d3-495b-b063-2c35319a30b5",
    "timestamp": "2022-07-07T17:38:14.6760045Z",
    "userId": "8d04431f-4eee-42d5-9141-e56c5b00b391",
    "userEmail": "[email protected]",
    "term": null,
    "pageNumber": 1,
    "language": "en-US",
    "state": null,
    "surface": "ExternalContentPicker"
}

Inbound response from your system to Seismic

Your system will return a count of valid contents per search term, and the related contents in a Cards compatible format. This is also identical to the response expected in the Search extension point.

{
    "state": null,
    "cards": [{
            "ext_id": "UniqueIDValueForContent",
            "type": "Lesson",
            "accessories": {
                "url": "fakeLink.toDocument.com",
                "thumbnail": {
                    "image_url": "fakeLink.DocumentURL.png",
                    "alt_text": "Document Thumbnail"
                }
            },
            "elements": [{
                    "type": "header",
                    "text": "Company X Marketing Onboarding Materials"
                },
                {
                    "type": "markdown",
                    "text": "The description goes here./n/n![TrainingCompleted](https://fakeLink/TrainingCompleted.png) Training Completed"
                }
            ]
        },
        {
            "ext_id": "UniqueIDValueForContent",
            "type": "Lesson",
            "accessories": {
                "url": "fakeLink.toDocument.com",
                "thumbnail": {
                    "image_url": "fakeLink.DocumentURL.png",
                    "alt_text": "Document Thumbnail"
                }
            },
            "elements": [{
                    "type": "header",
                    "text": "Second Document Title"
                },
                {
                    "type": "markdown",
                    "text": "The description for the second document is here./n/n![TrainingNotCompleted](https://fakeLink/TrainingNotCompleted.png)Training Incomplete"
                }
            ]
        }
    ],
    "matchTerms": [
        "Market",
        "Marketing"
    ],
    "resultCount": 2,
    "pageNumber": 1,
    "totalPages": 1
}

Outbound payload from Seismic to your endpoint(s) when content is associated or disassociated.

linkedContent refers to your external content.
SeismicContent refers to the files within Seismic

{
    "userId": "8d04431f-4eee-42d5-9141-e56c5b00b391",
    "userEmail": "[email protected]",
    "appId": "b7f07df8-9ebb-487a-98b8-471ececc5f46",
    "appName": "Extension Point Test App",
    "extensionId": "22695b7e-a3cc-4718-b017-abbabd5cc6a5",
    "tenant": "wannabelikemike",
    "tenantId": "cc881086-49d3-495b-b063-2c35319a30b5",
    "type": "RelatedTraining",
    "timestamp": "2022-07-07T18:51:26Z",
    "linkedContent": {
        "linkedContentId": "efbc47d7-111e-461c-b5d5-e3478702c68f",
        "externalContentId": "ExternalUniqueID",
        "externalContentType": "Lesson",
        "externalContentHeader": "Company X Marketing Onboarding Materials"
    },
    "seismicContent": {
        "id": "6c82f765-4999-4b82-9d92-1cd916c0f27c",
        "seismicTeamsiteId": "1",
        "repository": "library",
        "name": "Seismic TestFile",
        "type": "file"
    }
}

Troubleshooting

  • Ensure your app is configured with a signing secret
  • Double check the extension point is enabled within your app
  • Validate that your program knows how to handle each type of POST request that Seismic will send
    • Related training widget launch looking for the details of content that has already been associated when surface = DocCenter or library
    • Initial picker POST with empty filters looking for a list of content when surface = ExternalContentPicker
    • Filtered picker POST with a populated filter object looking for a list of content when surface = ExternalContentPicker
    • A successful association or disassociation POST

Related Documentation

Extension points
Search
Cards