<!-- Source: https://docs.squirro.com/en/latest/technical/integrations/servicenow.html -->
# ServiceNow Insights

This page explains how to install, configure, and extend the Squirro Service Insights for ServiceNow application.

## Introduction

Squirro Service Insights for ServiceNow™ indexes data from your ServiceNow installation to provide insights from that data.

Out of the box, Squirro Service Insights provides the following functionality:

- Ticket level solution recommendations from past incidents and the knowledge base.
- Full-text search across the most important tables from ServiceNow.
- Incident overview with terminology tag cloud to understand what kind of incidents are being reported at the moment.

To achieve this, Squirro Service Insights installs the following components:

- Multiple dashboard integrations using UI Pages and UI Macros.
- Configuration properties to connect ServiceNow with a Squirro installation.

On the Squirro side, the following components need to be set up:

- A Squirro cluster installation - either cloud or on-premise.
- Data connector for indexing ServiceNow data in Squirro.

## Languages

The Squirro Service Insights for ServiceNow™ user interface is always in English. But but the data any language is supported and can be processed by Squirro.

## Devices

Squirro Service Insights is optimized for desktop browsers and does not currently support mobile devices.

### Installation

The Squirro Service Insights for ServiceNow application is installed from the ServiceNow app store.

Before you start, please ensure that the following prerequisites are met.

## Prerequisites

Before setting up the Squirro Service Insights integration, you need access to a Squirro installation with a valid license.

Visit the [Squirro Support website](https://go.squirro.com/support) and submit a technical support request to start the process of setting this up.

Once installed, you will receive the following information from Squirro:

- Base URL of the Squirro installation
- Login email
- Login password
- Identifier of the Squirro project
- Dashboard ID for the ticket 360º view
- Dashboard ID for the power search
- Squirro authentication secret

## Installation

Follow this process to set up Squirro Service Insights for ServiceNow.

1. Open the ServiceNow app store site at [https://store.servicenow.com/](https://store.servicenow.com/)
2. In the Search field enter _Squirro_.
3. In the search results select the _Squirro Service Insights_ application.
4. On the application page, click the _Get_ button.
5. Enter your ServiceNow username and password and press _Login_.
6. Follow the ServiceNow instructions to download and install the application into your ServiceNow instance.

## Configuration

### Properties

After following the Installation process, the menu _Squirro_ is added to the ServiceNow navigation. Use the _Properties_ screen to configure the Squirro Service Insights installation.

You should have received all of the properties that are requested in this form from Squirro. Check the _Prerequisites_ section if you do not have this information.

### Users and Roles

Squirro Service Insights provides three different roles, that can be used for permissions.

|  |  |  |
| --- | --- | --- |
| Role | Description | Setup Instructions |
| x_squir_si.indexer | Used for the user with which Squirro indexes the ServiceNow data. All users of Squirro Service Insights will be able to see all the data that this role has access to. | Create one ServiceNow user and assign this role to the user. That user will be used from the Squirro side to index the data. |
| x_squir_si.user | Can access the Squirro Service Insights application, both on an individual incidents as well as the global dashboards. | Assign to any users or groups that should be able to use Squirro Service Insights. |
| x_squir_si.admin | Can administer the Squirro Service Insights application by changing the properties. | Assign to any users or groups that should be able to administer Squirro Service Insights. |

## UI Policy for Squirro Form

The 360º view on the Incident form is visible to all users by default. It is recommended to limit this to the role `x_squir_si.user` and `x_squir_si.admin` by creating a UI policy as follows:

1. Navigate to System UI → UI Policies and create a new policy
2. Fill in the form as follows:

   |  |  |
   | --- | --- |
   | Table | Incident |
   | Active | Yes |
   | Short description | Show Squirro section for Squirro users |
   | When to apply |  |
   | Conditions | Leave empty - add no conditions |
   | Global | Yes |
   | On load | Yes |
   | Revert if false | No |
   | Script |  |
   | Run scripts | Yes |
   | Execute if true | ```javascript function onCondition() { var showSquirro = !g_form.isNewRecord() && (g_user.hasRole('x_squir_si.user') \|\| g_user.hasRole('x_squir_si.admin')); g_form.setSectionDisplay('squirro', showSquirro); } ``` |
   | Execute if false | (Leave empty) |

## Configure Squirro Indexing

To index the data from ServiceNow to Squirro, configure the ServiceNow user which is used to connect to the ServiceNow web service.

1. Log in to Squirro. Use the base URL, username and password that were provided by Squirro for this.
2. Select the _Data_ tab.
3. You are now presented with the ServiceNow data source. Hover over the data source and on the right side click edit.
4. The ServiceNow data connector configuration opens up:
   [![image1](https://s3.amazonaws.com/download.squirro.net/docs/migrated-attachments/85496492/87316593.png)](https://s3.amazonaws.com/download.squirro.net/docs/migrated-attachments/85496492/87316593.png)

   1. On the initial step (_Configure source_) enter the ServiceNow server name, and the user name and password of the indexer user. Do not change the other two values (table name and columns).
   2. Press _Next_. If an error message appears, it is because Squirro can not connect to ServiceNow with the provided configuration. In that case verify the server, user name and password again.
   3. Go through the process until the last screen by pressing _Next_. Do not make any changes to the values.
   4. On the last screen press _Next_ to save the changes and index the data.
5. Once complete, switch to the _Search_ tab. Confirm that the data has been indexed.

## Extension

Squirro Service Insights for ServiceNow comes preconfigured with a few components. This default can be extended to tailor the solution more to your individual needs. Specifically, two extensions are common:

- Change the visualisations. Either by changing the default Squirro dashboards or even by adding completely new dashboards.
- Change the data connection. Squirro can be customized to take into account additional ServiceNow table customizations that have been done. Squirro can also connect to other data sources outside of ServiceNow.

## Changing Dashboards

To modify an existing dashboard, follow this process:

1. Log in to Squirro. Use the base URL, username and password that were provided by Squirro for this.
2. Select the _Dashboard_ tab.
3. Select the dashboard that you want to customize.
4. Enter the dashboard edit mode by clicking the pencil icon on the left.
5. Use the user interface to edit, add, remove and resize widgets.

## Adding Dashboards

Completely new dashboards can be added. This is a two-stepped process, where the dashboard is first configured in Squirro, and then added to ServiceNow.

First create the new dashboard on Squirro:

1. Log in to Squirro. Use the base URL, username and password that were provided by Squirro for this.
2. Select the _Dashboard_ tab.
3. Use the plus icon to create a new empty dashboard. Alternatively, select an existing dashboard and in the three-dot menu on the left select the option _Duplicate Dashboard_.
4. Use the user interface to edit, add, remove and resize widgets.

Now this dashboard can be added to ServiceNow. For this, create a new UI page with the following HTML:

```xml
<?xml version="1.0" encoding="utf-8" ?>
<j:jelly trim="false" xmlns:j="jelly:core" xmlns:g="glide" xmlns:j2="null" xmlns:g2="null">
    <g:macro_invoke macro="x_squir_si_dashboard" dashboard_id="DASHBOARD_ID" />
</j:jelly>
```

This makes use of a Squirro-provided UI Macro (`x_squir_si_dashboard`) to simplify the integration. Replace the `DASHBOARD_ID` value with the dashboard’s identifier.

## Known Issues

### Dashboard Always Loaded

Sometimes Squirro for ServiceNow loads the Squirro dashboards even when the corresponding roles have not been assigned to a user. This is because the _UI Policy_ is applied on the client side, and thus too late to prevent the embedded dashboard from loading. While a full fix is under development, you can prevent this from happening by changing the default Squirro `dashboard` UI Macro.

1. Navigate to `System`, `UI Macros`
2. Search by `Name` for `dashboard`
3. Open the `dashboard` UI Macro from the `Squirro Service Insights` application and edit it. Overwrite the XML with the following:

   ```xml
   <?xml version="1.0" encoding="utf-8" ?>
   <j:jelly trim="false" xmlns:j="jelly:core" xmlns:g="glide" xmlns:j2="null" xmlns:g2="null">
       <g:evaluate>
           var checkRole = gs.hasRole('admin') || gs.hasRole('x_squir_si.user') || gs.hasRole('x_squir_si.admin');
           if (current) {
               if (current.isNewRecord()) {
                   checkRole = false;
               }
           }
       </g:evaluate>
       <j:choose>
           <j:when test="${checkRole}">
               <j:choose>
                   <j:when test="${!empty(jvar_dashboard_id)}">
                       <g:evaluate var="urlRet" object="true">
                           var squirro = new Squirro();
                           var params = {};
                           if (current) {
                               params.tbl = current.getRecordClassName();
                               params.external_id = current.sys_id;
                               params.external_ref = current.getValue('number');
                           }
                           var urlRet = squirro.generateURL('${jvar_dashboard_id}', params);
                           urlRet;
                       </g:evaluate>
                       <g:breakpoint var="urlRet"/>
                       <j:choose>
                           <j:when test="${!urlRet.hasError}">
                               <style>
                                   .squirro_si_container {
                                       position: relative;
                                       padding-bottom: 918px;
                                       padding-top: 0;
                                       min-height: 880px;
                                       overflow: hidden;
                                   }
                                   .squirro_si_container iframe {
                                       position: absolute;
                                       top: 0;
                                       left: 0;
                                       width: 100%;
                                       height: 100%;
                                   }
                               </style>

                               <div class="squirro_si_container">
                                   <iframe class="squirro_si_container_iframe" width="100%" src="${urlRet.url}" frameborder="0" scrolling="0"></iframe>
                               </div>
                           </j:when>

                           <j:otherwise>
                               Error: ${urlRet.error}
                           </j:otherwise>
                       </j:choose>

                   </j:when>
                   <j:otherwise>
                       Error: No dashboard ID specified.
                       <j:if test="${!empty(jvar_property_description)}">
                           Specify the dashboard ID with the property "${jvar_property_description}" in the Squirro Properties.
                       </j:if>
                   </j:otherwise>
               </j:choose>
           </j:when>
           <j:otherwise>
               Missing access permissions for this Squirro integration. Please make sure the UI Policy is deployed to avoid showing this error message (see the Squirro for ServiceNow administration Guide).
           </j:otherwise>
       </j:choose>
   </j:jelly>
   ```