Related Training

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

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
From within Seismic, an admin clicks the button "+ Add Training" which opens a content picker, giving you the ability to select related contents
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 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

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


ids	array	Contains objects of external content
ids.ExternalObjectId	string	The External Id that you have provided for each piece of content that is associated to this piece of Seismic content
surface	string	The 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 name	Field type	Description
filters	object	Contains the filters & filter values selected by the user. Defaults to null when no filter selection is made
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. Defaults to "null" when no search has been executed
pageNumber	integer	Indicates which page of results are being surfaced in Seismic. Defaults to 1 for your first page of results
state	string	Seismic 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


linkedContent	object	An object that contains an array of metadata for your linked content(s)
linkedContent.linkedContentId	string	The "cards.externalId" or "cards.ext_id" value that was given for this piece of content in the picker selection
externalContentType	string	The "cards.type" value that was given for this piece of content in the picker selection
externalContentHeader	string	The "cards.elements.text" value that was given for this piece of content in the object where "cards.elements.type"="header" in the picker selection
seismicContent	object	The object that contains metadata on this piece of Seismic content
seismicContent.id	string	Seismic's unique ID for this piece of content. Commonly referred to as contentId
seismicContent.seismicTeamsiteId	string	The Teamsite ID for this piece of content in Seismic's Library
seismicContent.respository	string	The repository where this content lives. It will always be "Library"
seismicContent.name	string	The name of the piece of content in the Seismic library
seismicContent.type	string	The 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