Search

Purpose

The Search Extension allows users to search against and display content from 3rd party systems within Seismic. This is typically used for content that does not benefit from Seismic's delivery options, like LiveSend.
Common use cases include:

• Learning and Training systems
• Internal documentation repositories

App Prerequisites

• Your app must be configured with a signing secret

How it works

High Level Flow

• A user is searching for content within Seismic and there is a specific tab which represents your external system.
• We pass the search and user details to your external system's endpoint
• Your service can validate the user's existing token
  • If the user does not have an active token, you can return a 401 response and we can launch a window to prompt the user to log in then execute our outbound search again via the External Auth extension point which is configured separately
• Your external system returns the details and metadata required to list the content in Seismic
• Seismic lists the content to the end user within Cards

When it's triggered

• When a user opens the search environment within Seismic
• A user executes a search within Seismic
• A user changes an existing search with filters or keywords
• A user infinite scrolls onto a new 'page' of materials
• After a user submits their credentials to access the external repository

Security & Authentication

• It is recommended to validate the Signing Secret in the POST request that Seismic is making
• It is recommended to validate the user's authentication before retrieving and returning search results using this workflow:

How to Configure

Configure the Search Extension Point

* Add the **Search** extension to your application as described [here](https://developer.seismic.com/seismicsoftware/docs/extension-points-v2#how-to-configure)  * Fill out the Extension fields
* Extension Instance Name - A Name that references this usage of this extension point within your app
* Search Endpoint - Where Seismic will make the POST calls with the search and user details
* Tab Label field - The name that is displayed to end users that are looking for your content
* Click Save Changes
* Make sure to enable the extension point and click Save Changes

Payloads

Outbound payload from Seismic to your endpoint

POST request from Seismic contains the search details and additional generic details. For generic field definitions, please refer back to the Extension Points parent page

{
  "filters": [],
  "appId": "c7f07df8-9ebb-487a-98b8-471ececc5f46",
  "appName": "Extension Tests",
  "version": "0.3.4",
  "requestId": "4333f52e-c41b-4deb-8d72-d87a0e44e54e",
  "tenant": "tenantNameHere",
  "tenantId": "cd881086-49d3-495b-b063-2c35319a30b5",
  "timestamp": "2022-04-06T23:10:43.4736031Z",
  "userId": "7a87ab09-30e2-47df-9e2a-f86134045d05",
  "userEmail": "[email protected]",
  "term": "",
  "pageNumber": 1,
  "language": "en-US",
  "state": {},
  "surface": "SearchAll"
}

{
	"filters": [{
		"type": "Type",
		"values": ["Curriculum", "Course"]
	}],
	"appId": "c7f07df8-9ebb-487a-98b8-471ececc5f46",
	"appName": "Extension Tests",
	"version": "0.3.4",
	"requestId": "9f54ae9d-2f9f-4d7e-9165-ecdcc365215c",
	"tenant": "tenantNameHere",
	"tenantId": "cd881086-49d3-495b-b063-2c35319a30b5",
	"timestamp": "2022-04-07T18:06:24.6477537Z",
	"userId": "8d04431f-4eee-42d5-9141-e56c5b00b391",
	"userEmail": "[email protected]",
  "term": "marketing",
	"pageNumber": 1,
	"language": "en-US",
	"state": {},
	"surface": "SearchTab"
}

Inbound Response from your system to Seismic

After receiving the Search details from Seismic your system should respond with a 200 or 202 code and a JSON body with the content's details. Each piece of content is seismic is displayed in a Cards

🚧

Timeout

• If a response is not received within 2 seconds, Seismic will not display your search results

{
	"state": {},
	"filters": [{
			"type": "Type",
			"values": [{
					"term": "Curriculum",
					"count": 4
				},
				{
					"term": "Course",
					"count": 2
				},
				{
					"term": "Quick-Take",
					"count": 1
				}
			]
		},
		{
			"type": "Skill",
			"values": [{
					"term": "Pitching",
					"count": 4
				},
				{
					"term": "Objection Handling",
					"count": 223,
					"selected": true
				}
			]
		}
	],
	"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": 223,
	"pageNumber": 2,
	"totalPages": 3
}

Troubleshooting

• Ensure the extension point is enabled within your app

• The app will need to be upgraded in the tenants where it has been installed after making a change

• Validate that your service is responding to Seismic within 2 seconds

• Authentication and Scopes are NOT required for this app to function

Related Docs

Extension points v2
External Auth
Main Nav
Cards
Related Training