# ServiceNow Connector

## Overview

This topic discusses ingesting the tickets and associated objects from ServiceNow. Aisera’s ServiceNow integration uses the [ServiceNow REST API](https://www.servicenow.com/docs/bundle/zurich-api-reference/page/build/applications/concept/api-rest.html) to automatically pull the following records from a ServiceNow database:

* Approvals
* Assignment Groups
* Incidents
* Knowledge Base Articles
* Requests
* Service Catalog
* Users

## Prepare

Before completing the configurations for the ServiceNow, you will need to ensure that you complete the following items, and gather the required information.

### Authentication

Aisera's ServiceNow connector supports two authorization types: **OAuth 2.0** and **Basic.**

#### OAuth 2.0

To set up a ServiceNow integration using OAuth 2.0 for authorization the Aisera Platform will require the following information:

* Client Id
* Client Secret
* Authorization URL
* Access Token URL: `https://aiserademo1.service-now.com/oauth_token.do`

You will need to create an [OAuth 2.0 Application for External Clients](https://www.servicenow.com/docs/r/application-development/app-engine-management-center/create-oauth-api-endpoints-for-external-clients.html). Use the following for the Redirect URLs during the registration of the OAuth Application:

`https://<tenant_id>.login.aisera.<top_level_domain>/?id=aisera.oauth.oauthCommand,https://<tenant_id>.login.aisera.<top_level_domain>/studio/oauth-callback?id=aisera.oauth.oauthCommand`

After creating the new application you will be able to obtain the **Client Id** and **Client Secret** for the application from ServiceNow.

#### Basic Authentication

Basic Authentication uses an account's **username** and **password.** It is common practice to create a dedicated service account for this authorization type.

### Service Account

To pull tickets, KB articles, and related objects from ServiceNow, you will need to create a Service Account.&#x20;

#### Read Permissions

The service account will need read permissions to the following tables:

* `close_notes` (Task)
* `cmdb_ci` (Related CMDB/CI info)
* `cmn_location` (Location information)
* `incident` (incidents)
* `kb_article_template`
* `kb_knowledge` (Knowledge)
* `sc_item_option`
* `sc_item_option_mtom`
* `sc_req_item`
* `sc_requests`
* `sc_cat_item`
* `sys_journal_field`
* `sys_user` (Users, when crawling any type of ticket)
* `sys_user_group` (Assignment Groups)
* `sysapproval_approver` (Approval list)

#### Write Permissions

To create or update any incidents or approvals, the ServiceNow service account needs write permissions for the following tables:

* `incident`
* `request`
* `sys_journal_field`
* `sysapproval_approver`

#### Roles

To crawl the service catalog, the service account needs **Service Catalog ITIL** and **Catalog\_Admin** roles.

## Integration Setup

To create the ServiceNow integration:

1. In the Aisera Admin UI navigate to **Settings > Integrations.**
2. Click on + **New Integration**
3. In the menu, select **ServiceNow** and click **Next**<br>

   <div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2Fghef5awckUNn1A1VjcD4%2Fsn1.png?alt=media&#x26;token=15f3abe4-7de6-476e-a73b-dcfd617a8cb6" alt="" width="563"><figcaption><p>Choose the ServiceNow Integration</p></figcaption></figure></div>
4. Fill in the integration details and click **Next**<br>

   <div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2F4dAMVybdNntVqLM6rTLV%2Fsn2.png?alt=media&#x26;token=be78ea40-6c67-4b3c-9a19-67df331b7f62" alt="" width="563"><figcaption><p>Add Configuration Details</p></figcaption></figure></div>

   <table><thead><tr><th width="233">Field</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>Enter the name you want to give to the integration</td></tr><tr><td>Endpoint</td><td>Enter the base URL for your ServiceNow instance. This will look like: <code>https://&#x3C;company>.service-now.com/</code></td></tr><tr><td>Live API Agent</td><td>Select the version of the ServiceNow API</td></tr><tr><td>Public</td><td>Determines whether the integration can be used outside the firewall</td></tr><tr><td>Description</td><td>Mention the details for the integration you want to configure</td></tr></tbody></table>
5. Select the **Auth Type** and fill in the respective credentials
6. Click **Ok** to save the integration

## Data Source Setup

To create the ServiceNow data source:

1. In the Aisera Admin UI navigate to **Settings > Data Source**
2. Click **+ New Data Source**
3. Select **ServiceNow** and click **Next**<br>

   <div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FdW1aOcH7vAqynjGFQc37%2Fsn6.png?alt=media&#x26;token=4afb2673-9018-49c8-9b1e-38f3fa7f0163" alt="" width="563"><figcaption><p>Designate the Data Source</p></figcaption></figure></div>
4. Enter the configuration details and click **Next**<br>

   <div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FWBPrjG42JJZEb87X0WQM%2FServiceNowConnector-DataSourceGeneral..png?alt=media&#x26;token=b733d26c-20cd-4245-9429-402f5d12011f" alt=""><figcaption></figcaption></figure></div>
5. All remaining options are optional. See the section below for more information. Click **Next** until the window closes to complete the creation of the **Data Source**

## Optional Configurations

During data source configuration, several optional parameters are available to customize the ingestion process or formats. These options may vary based on the functions and parameters selected earlier.

<div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FQAXEEscl5ljL6zX99Zcu%2Fimage.png?alt=media&#x26;token=350be770-7e8c-41b7-bb1a-59a9a9fc228a" alt=""><figcaption><p>Optional Data Source Parameters</p></figcaption></figure></div>

#### Custom Endpoint Modification Map

When a gateway is configured, you can map standard ServiceNow API endpoints to gateway endpoints. This mapping is done using a JSON string in the format of  `"<ServiceNow_Endpoint>:<Gateway_Endpoint>"`.&#x20;

To enable the import of ServiceNow service catalogs as intents, set the **Import Service Catalogs as Intents** flag to **Yes.** When this setting is enabled, the system will use the provided gateway information to query, retrieve and update data used for intent generation, automatically populating dropdowns for Service Catalogs and categories within the Admin UI.

Example Input:

```json
{
    "api/now/table": "api/esp/table",
    "api/now/attachment": "api/cisit/esp/attachment"
}
```

#### Incidents Table

Specify the custom incidents table name so the data source can locate it.

#### Custom Script

This field is used to transform the data being ingested into the Aisera platform. This script is written in JavaScript.

#### Additional Query Parameters

This field is used to ingest additional attributes that are not part of the out of the box connector query.

#### Download Attachments

Enable this flag to ingest document attachments.

#### Join Tables

This JSON configuration enables the association of additional tables with content types being ingested. It offers the flexibility to join and integrate data from any desired table into the table currently being ingested.

#### Bypass Test Connection

If checked, the connector will not perform the test connection. In case the entered credentials are wrong, you may not get good error messages. Hence, it is advised to have it unchecked.

If checked, the connector will not perform a test connection.

{% hint style="warning" %}
In case the entered credentials are wrong, you may receive an unclear error message. It is recommended to leave this unchecked.
{% endhint %}

#### Custom Query

This query acts as a filter to the out of the box connector query. This is used when only certain KB articles or tickets from specific departments are to be ingested.

## Post-Connection Steps

### Data Ingestion

After you've successfully set up your connector, your data will automatically sync according to the schedule settings or on demand, as specified during the Data Source Configuration step. However, you should perform a manual sync immediately. This initial run will serve two key purposes:

After setting up your connector, your data will sync automatically based on your schedule parameters, or you can choose the "on demand" configuration to sync data only when requested.

1. It confirms the connector is working properly.
2. It provides an immediate view of the information being ingested into the Aisera Application, allowing you to validate and begin working with the data.

To manually ingest data:

1. In the Aisera Admin UI navigate to **Settings > Data Sources.**<br>

   <div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FUIsDFUfemqsV7ML86iHS%2FDataIngestion-DataSourceWindow.png?alt=media&#x26;token=c41635bd-16b9-4b13-b35b-84705fa26309" alt=""><figcaption><p>Data Sources Window</p></figcaption></figure></div>
2. **Click** on the **Data Source** you wish to manually ingest data from.
3. At the top right of the **Data Source Details** page, click the **Play** button to manually ingest data.<br>

   <figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FWOAAURoDxlvnQcfI7gws%2FDataIngestion-DataSourceDetailsWindow.png?alt=media&#x26;token=41069e6a-e0be-4924-a9b2-41aae8fb5d43" alt=""><figcaption><p>Data Source Window</p></figcaption></figure>

### Viewing Ingested Tickets

After data ingestion has occurred, tickets can be viewed in the Aisera Admin UI by navigating to **SOR > Tickets** using the left navigation panel.

<div align="left"><figure><img src="https://3281977978-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvBFXjH9S1CAy9f5hzg5Q%2Fuploads%2FiS2FNRZ1uUP9KWYiUt2L%2Fimage.png?alt=media&#x26;token=59eed962-909d-40bd-8ba3-b7a5f824b0fd" alt=""><figcaption><p>Navigation to Tickets Window</p></figcaption></figure></div>

### Reviewing Crawled Knowledge Documents

After data ingestion has occurred, you may then review the knowledge documents and sections that have been ingested.

To view all of the ingested documents:

1. Navigate to **AI Workbench > Review** on the left-hand main navigation panel
2. Click the **Knowledge Review** tab at the top of the page
3. You will see **Commit Reviewed** and the number of documents that have been ingested.
4. If this is the first crawl, all the documents are in **Reviewed** status by default. Refer to [How to Review Crawled Knowledge](https://docs.aisera.com/aisera-platform/data-ingestion/how-to-set-up-knowledge-base-crawls#th0tcz1mntbl) documents  for more details
5. Click on **Commit Reviewed** and click **Commit**.
6. Now, navigate to **SOR > Knowledge** in the left navigation panel and you will see all the ingested documents. It might take a couple of minutes to load the docs in the knowledge tab.