Search
Surface and search against your external content directly from within Seismic
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
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 Search functionality SearchAll - the All Search Results page, only top 3 results shown SearchTab - the specific tab for your content where all content results are shown. Lazy loading & infinite scroll will load additional pages |
{
"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
Field Name | Field Type | Description |
---|---|---|
filters, filters.type, filters.values | object | This allows the user to use search filters within the UI. Echo back the filters from the Seismic POST * Highly Recommended for search functionality |
matchTerms | string array | Additional keywords and search terms that you associate with the term provided in the Seismic POST. * Recommended for bold text in the search result list |
resultCount | integer | A count of total results *Required |
pageNumber | integer | The current page of results. * Highly recommended for multiple pages of results and infinite scrolling to function |
totalPages | 1 | The count of total pages * Highly recommended for multiple pages of results and infinite scrolling to function |
cards | object | A card is the container that display content details. See Cards for more details |
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
Updated over 1 year ago