External Rendering

How can I bring OneSearch results to an external system?

You may find that OneSearch works so well that you want to send results to an external system for display. OneSearch includes a set of REST APIs that you can use to query a particular Searcher or Section in the context of a specified user.

• First, you’ll need to visit YDS OneSearch->Install Global Components to install a small, globally scoped Script Include. This allows OneSearch to perform searches in the context of a specified user, ensuring your search sources are properly secured.

• Next, visit YDS OneSearch->Docs & Settings to see a form annotation that lists the API endpoints, URL parameters, and Request Payload needed to return valid search results.

• Using the REST API Explorer within ServiceNow or a utility like Postman is a great way to perform sample searches and see the format of returned results.

An example request to pull a single result from the sample KB section might look like:

POST https://[your instance].service-now.com /api/x_yala_yds_search/yds_search/getsearchresults?section=9c04880e840332006d1e520241c824d1&search_as=ben%40yansalabs.com&limit=1

Payload:
{“searchTerm”:”Is salesforce down?”}

In order to add a Filter or Order parameter to a query, you must add additional filterTerm and orderTerm data to the Request Payload as indicated below:

{
  “searchTerm”:”[searchTerm – ie “is salesforce down?”]”
  “filterTerm”:
  {
     “[SysID_of_Section]”:
        {
           “[fieldname – ie, ‘”kb_category”]”:”[Comma-separated list of kb_category SysIDs]”
        }
  }
  “orderTerm”:
  {
     “[SysID_of_Section]”:”[SysID of Order-by Field record – default is always by ‘relevance’]”
  }
}

An abridged example response is below. Though it isn’t shown in the example response, all responses will also contain data about available filters for the search results, according to Section configuration. These can be used by external systems but require a more complex Request Payload.

{
  "result": {
    "results": [
      {
        "short_description": {
          "displayValue": "Sales Force Automation is DOWN",
          "value": "Sales Force Automation is DOWN"
        },
        "text": {
          "displayValue": "On Friday, January 20th, we experienced a widespread outage that affected all Zoho services. The outage started around 8:13 am Pacific Time. Zoho services started coming back online for customer us...",
          "value": "On Friday, January 20th, we experienced a widespread outage that affected all Zoho services. The outage started around 8:13 am Pacific Time. Zoho services started coming back online for customer us..."
        },
        "rating": {
          "displayValue": "4",
          "value": "4"
        },
        "published": {
          "displayValue": "2017-04-10",
          "value": "2017-04-10"
        },
        "author": {
          "displayValue": "Ben Hollifield",
          "value": "726c8ec2db7e7200a574dfea5e9619de"
        },
        "sys_view_count": {
          "displayValue": "124",
          "value": "124"
        },
        "number": {
          "displayValue": "KB0000001",
          "value": "KB0000001"
        },
        "sys_id": "f2765f9fc0a8011b0120ec1b352bf09b",
        "table": "kb_knowledge",
        "query_score": "6",
        "rank": 1
      }
    ],
    "count": 7
  }
}

To see examples specific to your environment, enable Debug logging at YDS OneSearch->Docs & Settings, and then open OneSearch in a browser with the console log exposed. As you navigate searches, filters, and order selections, the API calls being made will be reflected in the console.

Any time you have an issue, a question, or an idea to make OneSearch better, don’t hesitate to reach out to us at yansalabs.com/support. We’re here to help!