Related Training

Show related training blade on DocCenter and Library contents

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

Security & Authentication

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

Configure the Related Training extension point

Add the Related Training extension to your application as described here. See the table below for configuration fields

Field nameData typeDescriptionNotes
Extension Instance NamestringThe name by which this extension point is identifiedVisible to tenant admins that install your app
Data Fetch URLURLThe endpoint that we will call to get the data for the content pickerSupports search criteria
Default State LabelstringA label that we show on the initial launch of the content pickerOptional
Linked Content Callback URLURLAn endpoint we can call after content has been successfully linked or de-linkedOptional
Default State URLURLAn alternate URL we will post to for the initial load of the content pickerOptional

When it's triggered

POST #1 to Data Fetch URL Seismic looking for your content details to display

  • When an admin expands the Related Training widget in the Library
    • Seismic is sending the IDs of previously related content and expecting relevant details back for these items. The field "surface" = "ContentManager"
  • When any user views a piece of content in the DocCenter where Related Training materials have been associated
    • Seismic is sending the IDs of previously related content and expecting relevant details back for these items. The field "surface" = "DocCenter"

POST #2 to Data Fetch URL Seismic is requesting a list of content you want to give your admins to associate to that piece of Seismic content

  • When an admin clicks "+ Add Training" in the Related Training to add or remove content associations
  • Seismic is requesting your system to display contents that could be selected for related trainings. The fields "pageNumber" = 1 & "term" = null
  • This post will instead go to the Default State URL if you have populated this field in your extension point configuration
  • While an admin is browsing 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. The fields "pageNumber" = 1, "term" contains the search keywords, and "surface" = "ExternalContentPicker"
  • While an admin is browsing for external content and they scroll down to the end of the results
    • Seismic is requesting your system to display pageNumber X of contents that could be selected for related trainings. The fields "pageNumber" = X, "term" contains the search keywords if applicable, and "surface" = "ExternalContentPicker"

POST #3 to Linked Content Callback URL Seismic is letting you know a Related Training association has been made

  • When a piece of Seismic content is successfully associated or disassociated from your external content
  • On content association Seismic will provide an object "linkedContent" with the fields "linkedContentId" (Seismic's content ID) and echo back your "externalContentId" and "externalContentType"
  • On content disassociation Seismic will not provide provide any values in the "linkedContent" object
  • It is possible to associate and disassociate content at the same time. The associated content details will be provided, the disassociated content details will not be provided

Payloads

POST #1 to Data Fetch URL

Seismic looking for your content details to display
Basic information like userId, userEmail, appId, appName, tenant, requestId, versionId, timestamp, language, and extensionUniqueId are also included in this call

idsarrayContains objects of external content
ids.ExternalObjectIdstringThe External Id that you have provided for each piece of content that is associated to this piece of Seismic content
surfacestringThe location within Seismic where the Related Training blade is showing up. Values are "ContentManager" or "DocCenter"
{
  "userId": "11129fe0-0945-20e1-4648-2cdf8d3a4e2f",
  "userEmail": "[email protected]",
  "appId": "11107df8-9ebb-487a-98b8-471ececc5f46",
  "appName": "Extension Point Test App",
  "tenant": "tenantname",
  "requestId": "1114d4a1-629d-4603-814c-6e83fb65d001",
  "version": "0.13.2",
  "tenantId": "111a8707-a02f-4472-8fd2-113e6e3663a3",
  "timestamp": "2023-02-28T12:03:43Z",
  "language": "en-US",
  "extensionUniqueId": "11195b7e-a3cc-4718-b017-abbabd5cc6a5",
  "ids": [{
  	"ExternalObjectId": "UniqueIDValueForContent2",
  	"ExternalObjectType": "Lesson"
    }],
  "surface": "ContentManager"
}

POST #2 to Data Fetch URL &/or Default State URL

Seismic is requesting a list of content you want to give your admins to associate to that piece of Seismic content

  • When the content picker is launched, when a search is executed within it, or when scrolling to a new page of results we will POST this body to your Data Fetch URL.
  • However, if you have provided a value for Default State URL we will make the initial POST (page 1 with no search terms or filters) to that URL instead
  • Basic information like userId, userEmail, appId, appName, tenant, requestId, versionId, timestamp, and language are also included in this call

This is identical to the Search Extension POST Payload

Field nameField typeDescription
filtersobjectContains the filters & filter values selected by the user. Defaults to null when no filter selection is made
filters.typestringThe name of the field that is being filtered on
filters.valuesstring arrayComma delimited list of values for a given filter type
termstringThe keywords / text provided by the user for their search. Defaults to "null" when no search has been executed
pageNumberintegerIndicates which page of results are being surfaced in Seismic. Defaults to 1 for your first page of results
statestringSeismic will echo back to you the most recent State value you sent. This is useful for cursor-based pagination. Defaults to "null"
{
	"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"
}

Response to POST #1 or #2

Seismic is awaiting the necessary details to display your content in either the related training blade for existing associations, or in the Content Picker when setting up new associates

  • This same payload is acceptable as a response to both POST calls #1 and #2
    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": [{
			"externalId": "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"
				}
			]
		},
		{
			"externalId": "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
}

POST #3 to Data Fetch URL &/or Default State URL

Seismic is letting you know a Related Training association has been made

  • linkedContent refers to your external content.
  • SeismicContent refers to the files within Seismic
linkedContentobjectAn object that contains an array of metadata for your linked content(s)
linkedContent.linkedContentIdstringThe "cards.externalId" or "cards.ext_id" value that was given for this piece of content in the picker selection
externalContentTypestringThe "cards.type" value that was given for this piece of content in the picker selection
externalContentHeaderstringThe "cards.elements.text" value that was given for this piece of content in the object where "cards.elements.type"="header" in the picker selection
seismicContentobjectThe object that contains metadata on this piece of Seismic content
seismicContent.idstringSeismic's unique ID for this piece of content. Commonly referred to as contentId
seismicContent.seismicTeamsiteIdstringThe Teamsite ID for this piece of content in Seismic's Library
seismicContent.respositorystringThe repository where this content lives. It will always be "Library"
seismicContent.namestringThe name of the piece of content in the Seismic library
seismicContent.typestringThe type of the Seismic content. "file" or "url"
{
	"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