Thank you for your feedback.
Form temporarily unavailable. Please try again or contact docfeedback@servicenow.com to submit your comments.
Versions
  • London
  • Kingston
  • Jakarta
  • Istanbul
  • Helsinki
  • Geneva
  • Store
Close

Tutorial: set up an external knowledge base search source

Tutorial: set up an external knowledge base search source

Define an advanced search source to return data from any source on the Internet. To understand the power of search sources, follow this tutorial to set up an external knowledge base search source.

Before you begin

To create an advanced search source, you need an external resource that you can access via REST and basic knowledge of AngularJS.

About this task

In this integration, you will:

  • Create a data fetch script that uses the ServiceNow Table API to query a knowledge base from another ServiceNow instance.
  • Decode the JSON response and define the fields that the search widget expects.
  • Update the search sources HTML template to open the search result in the external site.

Procedure

  1. In the platform UI, navigate to Service Portal > Portals and select the portal you want to add the search source to.
  2. From the Search Sources related list, click New.
  3. Create a name and ID for the search source. The ID should be unique, and should not include any spaces or special characters.
  4. On the Data Source tab, select the Is scripted source check box.
  5. Add content to the data fetch script field.
    1. Define the search function to be executed by the instance.

      This example uses a recordless RESTMessage, but you can modify this example to use a pre-configured Outbound REST web service if needed, or create a more secure authentication profile.

      (function(query) {  
      var results = [];  
      /* Calculate your results here. */ 
      var url= "https://myInstance.service-now.com/api/now/table/kb_knowledge?sysparm_query=GOTO123TEXTQUERY321%3D" + encodeURI(query) + "&sysparm_fields=sys_id%2Cnumber%2Cshort_description%2Ccategory%2Ctext";  
          var ws = new sn_ws.RESTMessageV2();  
              ws.setBasicAuth("search_user", "search");  
              ws.setHttpMethod("get");  
              ws.setEndpoint(url);  
        
              var jsonOutput = ws.execute();  
      
      return results;  
      })(query);
      Note: In the preceding example, sw.setBasicAuth requires a user and password for the remote instance. For more detail, see RESTMessageV2 - Scoped, Global .
    2. Add an if statement to the data fetch script to decode the JSON object being returned, iterate over each result, and set expected fields.

      The final data fetch script:

      (function(query) {  
      var results = [];  
      /* Calculate your results here. */  
      var url= "https://myInstance.service-now.com/api/now/table/kb_knowledge?sysparm_query=GOTO123TEXTQUERY321%3D" + 
      encodeURI(query) + "&sysparm_fields=sys_id%2Cnumber%2Cshort_description%2Ccategory%2Ctext";  
      var ws = new sn_ws.RESTMessageV2();  
          ws.setBasicAuth("search_user", "search");  
          ws.setHttpMethod("get");  
          ws.setEndpoint(url);  
        
          var jsonOutput = ws.execute(); 
          if (jsonOutput) {  
              var response = new JSON().decode(jsonOutput.getBody());  
              results = response.result;  
              results.forEach(function(result) {  
                  result.url = "https://myInstance.service-now.com/kb_view.do?sysparm_article=" + result.number;            
                  result.target = "_blank";  
                  result.primary = result.short_description;  
              });  
          }  
      
      return results;  
      })(query); 
      In this example, the following fields are set on the result object:
      • url: If linking to an external site rather than opening the record in your ServiceNow instance, this defines where the link leads to.
      • target: The target for the link. Set the target to _blank to open results in a new tab, otherwise leave it blank.
      • primary: The primary field displayed in the search results.
  6. Update the search page template to open the search results in the external site.
    <div>
     <a href="https://myInstance.service-now.com/kb_view.do?sysparm_article={{item.number}}" target="_blank" class="h4 text-primary m-b-sm block">   
        <span ng-bind-html="highlight(item.primary, data.q)"></span>
      </a>
      <span class="text-muted" ng-repeat="f in item.fields | limitTo: 4">
        <span class="m-l-xs m-r-xs" ng-if="!$first"> &middot; </span>
        {{f.label}}: <span ng-bind-html="highlight(f.display_value, data.q)"></span>
      </span>
    </div>
  7. Click Update.

Result

Test the external search in your portal. Results display under the name field value defined in step three.

Each search result opens in the external site defined in the search page template.