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
10361036

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:
10541054

Search auth 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