Integrations Search API

Last Updated July 16, 2024

Brief Overview

In order to provide more flexibility, and opening the Enterprise Search to new capabilities, we have created the Integrations Search API. Integrations API is the way to integrate 3rd party search results into the Workstation Enterprise Search.

The Integrations Search API allows you to connect integrations to the Enterprise Search, so that you will be able to add search capabilities control the experience on Workstation.

This article introduces the Workstation - Integrations Search API.

3rd-party integrations add two main capabilities to the WalkMe Workstation-

Enterprise Search - allows users to discover applications and resources with a single unified search.
Home Screen Widgets - initiating processes directly within Workstation and by streamlining access to commonly used tools and resources.

How Does It Work

In order to create a new integration connected to the Integrations API, two-steps are required-

Setup- create a new integration.
Runtime- get a request from the API (search query) and provide a response (search results).

Both flows will be explained in this document.

Setup

In order to create a new integration, it will be required to provide WalkMe with the following parameters:

Parameter	Description
apiUrl	End point to that Workstation services will send the search query request. Required
apiKey	Your service unique identifier authenticates the request source. Required
System GUID	Located in Workstation app Settings > About screen. Required
appDescription	One-liner description for the app, that will appear to users in the Integrations page. Example to a proper format- “Search through Google Drive files directly from Workstation.” Required
customName	Name of the integration, that will appear on the Integrations page, search results and app's filter. Required
customImage	URL of the icon that will appear on the Integrations page, search results and app's filter. Required

For creating a new integration, reach out to your Customer Success Manager with the parameters listed in the table above, and the relevant System GUID.

In the future this capability will be added to the WalkMe Console and will be managed by the system admin.

As described below in a. figure below, the setup flow starts in DB (in the future will be done in Console). After providing us with the setup parameters, we test the integration to make sure that we get a proper response.

This test will be done with a “dummy user” created on our side. It does not require any configuration or setup on the external service side, since it will be a regular search query call that will indicate whether the flow was completed successfully.

Runtime

Trigger for the flow is- end-user searches for something in the Workstation App.

An API call will be generated to the API Endpoint (URL) with the API Key provided, according to the following conditions-

User types 3 characters or more (or 2 characters in Chinese/Japanese)..
Search timeout is 300 ms (milliseconds) from the last character typed (also known as Debounce). That means that the user can type letters in a continuous pace, and each letter will not trigger the search, but it will start after the timeout.

Once this search query is triggered, Integrations Search API will send a search query call with the parameters.

Search Flow

Search Query

Sent from Integrations API:

POST <apiURL>/(search)

Content-type: application/json

Headers:

{

Authorization: <apiKey>

}

Body:

{

"user": "user@email.com"

"system": "652c91b1ec444c76a313a68f69478b93"

"env": "prod"

"term": "itay"

}

Parameter	Description
user	User's email
system	System GUID- a 32 characters string
env	Type of the Workstation environment. Available values- qa prod
term	Search query that is being typed in the Workstation App

Search Results

Sent to Integrations API (as a POST call):

Body:

[{

"id": "b2f8510d-9547-4d53-978f-6fc24371c113",

"title": "Creating a user",

"description":

"WalkMe does not collect personally identifiable information  (PII) other than IP addresses in logs for security purposes, end users' approximate geolocation (country and city in which they are located) and masked IP addresses for the ongoing operation of the WalkMe system."

,

"link": "https://workday.com/workers/details/b2f8510d-9547-4d53-978f-6fc24371",

"mimeType": "Answers",

"externalType": "Article",

"created": "2022-01-30T14:35:16.57Z",

"modified": "2022-01-30T14:37:07.40Z",

"copy": "https://support.walkme.com/knowledge-base/users/",

"source": "confluence",

"category": "Gitlab Service User creation and configuration",

"detail": "Account Management",

"relationaltime": "2022-01-30T14:35:16.57Z"

}

}]

API Reference

Attribute	Type	Description
id	String	The unique identifier of the item. Required
title	String	The name of the item. Required
description	String	The description/summary of the item. If populated, the search result title will be displayed in bold, while the description will be displayed beneath. Optional
link	URL	The URL to access the item once clicking on the search result. Required
mimeType	String	The filter category in which the item should be displayed. It needs to be an exact match, of one of the following options appear in this list- People Documents Tickets Presentations Spreadsheets Media Code Leads Opportunities Deals Accounts Messages Events Reports Apps Websites Answers Required
externalType	String	The item type. For example- Article, Dashboard, Case, etc. If populated, it will be displayed on the item next to the integration name. Optional
created	Date Time	The date and time item was created. This parameter is not displayed on the UI, but is used for sorting purposes. Optional
modified	Date Time	The date and time item was recently updated. This parameter is not displayed on the UI, but is used for sorting purposes. Optional
copy	String	If populated, will display a copy button on the search result. By clicking on that button, it will copy the text provided (item link, name, ID, etc.). Usually it is populated with the item's link. Optional
confidence	Decimal	Parameter to be used to display accuracy of the response (in percentage). If populated, It will be displayed on the search result UI. Optional
source	String	Display the source of the response (for example - Confluence). It will be displayed on the search result UI next to a magnifying glass icon. Optional
category	String	Parameter to be used by Ask-AI, to display the category of the article (“bread crumbs”). If populated, It will be displayed on the search result UI above the title. Optional
poweredBy	String	If populated, It will display a note on the search result UI on the bottom right. Notice that when populated, the integration name and icon will not be displayed on the result. Optional
detail	String	If populated, this data will be displayed on the search result UI (after the integration name and externalType). Optional
relationalTime	Date Time	If populated, this data will be displayed on the search result UI, at the end of it. Will display a relational time according to the date provided VS current time (for example- 3 days ago). Optional

Restrictions

String fields are restricted to 255 characters.

Parameters UI Design

Error Handling

Though in most cases the flow will result in a "HTTP 200" response with a plain text ok indicating that the search results were displayed successfully, we will need to prepare for scenarios where attempts to send search results will fail.

The errors appearing in this section are being generated on the Integrations API side, and should indicate as accurately as possible the cause for the error.

The API response may throw errors (“HTTP 400”) when receiving malformed requests, when utilized keys that are no longer valid, or when something truly exceptional prevents it from making it through to search results.

Error	Description
invalid_structure	Typically indicates that the received request is malformed — perhaps the JSON is structured incorrectly, or the message text is not properly escaped. The request should not be retried without correction.
api_key_invalid	Indicates that the API Key being addressed either do not exist or are invalid. The request should not be retried without API Key modification.
api_url_invalid	Indicates that the API URL being addressed is invalid. The request should not be retried without API URL modification.
title_invalid	Indicates that the title, which is a mandatory value, was not sent or is not within the characters restrictions.
link_invalid	Indicates that the link, which is a mandatory value, was not sent or is not within the characters restrictions.
mimeType_invalid	Indicates that the mimeType, which is a mandatory value, was not sent or is not within the characters restrictions.
id_invalid	Indicates that the ID, which is a mandatory value, was not sent or is not within the characters restrictions.

Security Overview

The Enterprise Search uses 3rd-party integrations to implement a "federal search". Searches within Workstation are backed by an NLP engine, and a graph database that supports a great user experience.

Workstation Enterprise Search doesn't index 3rd-party data on an independently searchable database.

See below sequence diagram describes the searching algorithm:

Technical Notes

To ensure the Workstation ServiceNow integration works correctly, customers need to allow list the following IP's:

QA: 54.229.168.224
PROD: 52.53.115.147
EUPROD: 3.126.219.141

Was this article helpful?

Yes No

Yes

Thanks for your feedback!