> For the complete documentation index, see [llms.txt](https://docs.dropzone.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dropzone.ai/integrations/data/servicenow_data.md).

# ServiceNow

Dropzone AI integrates with [ServiceNow](https://www.servicenow.com/now-platform.html), a cloud-based platform that provides digital workflow automation. Dropzone supports two methods of authentication for this integration: Basic and OAuth Inbound.

{% hint style="info" %}
If you wish to use Basic authentication, you may skip to the "Enable ServiceNow" section of this document.
{% endhint %}

### Integration Overview (OAuth Inbound):

To enable these integrations you will perform the following actions:

* Create an OAuth Application User with the appropriate permissions
  * Create a New Role and Access Control List
  * Create a User Group
  * Assign the Role to that Group
* Create an OAuth Inbound Integration
  * Obtain a Client ID and Secret
* Install the credentials into your Dropzone tenant
* Select the [ServiceNow tables](https://www.servicenow.com/docs/r/washingtondc/api-reference/rest-apis/c_TableAPI.html) you want Dropzone to access

### Create an OAuth Application User

To grant Dropzone access to [tables](https://www.servicenow.com/docs/r/washingtondc/api-reference/rest-apis/c_TableAPI.html) for use in analysis, you will need to add a user (either a dedicated Dropzone User or another user) to an [access control list](https://www.servicenow.com/docs/r/platform-security/access-control/exploring-access-control-list.html). Alternatively, you may use an administrative user as your OAuth Application User, which will allow Dropzone access to most organizational data and tables.

{% hint style="info" %}
If you choose to use an admin user, you may skip to the "Create an OAuth Inbound Integration" section of this document.
{% endhint %}

#### Create a New Role

To create a new role, do the following:

* In the top bar of the ServiceNow home page, click "All"
* In the search bar, navigate to System Security > Users and Groups > Roles

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2Fc7VuZ7knfUY2aUKmTXkl%2Fservicenow-1.png?alt=media" alt=""><figcaption><p>Navigate to Roles</p></figcaption></figure>

* Click "New"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2Fhymve3YiELyVLQuMbcTx%2Fservicenow-2.png?alt=media" alt=""><figcaption></figcaption></figure>

* Name the role something memorable, such as "dz\_table\_read"
* Click "Submit"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FrQ1atDvenDXBzndGImVQ%2Fservicenow-3.png?alt=media" alt=""><figcaption><p>Create a new role</p></figcaption></figure>

#### Create an Access Control List

To create an ACL, do the following:

* In the upper right corner, click your icon
* Click "Elevate Role"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2Fv3HaL4ea6Cjtn1NaJy76%2Fservicenow-4.png?alt=media" alt=""><figcaption><p>Elevate your role</p></figcaption></figure>

* Select security\_admin

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FX52mZGzTCLmPLUwpqn3X%2Fservicenow-5.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
For more information on elevated roles, see [ServiceNow's documentation](https://www.servicenow.com/docs/r/platform-security/c_ElevatedPrivilege.html#:~:text=to%20manually%20elevate-,The%20security_admin%20role,-In%20the%20base)
{% endhint %}

* Navigate to All > System Security > Access Control (ACL)
* Click "New"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2Fhymve3YiELyVLQuMbcTx%2Fservicenow-2.png?alt=media" alt=""><figcaption></figcaption></figure>

* Under "Operation," select "read"
* Under "Name," input a table you want Dropzone to have read access to

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FSyV8O1c9y8nksxD6jXax%2Fservicenow-6.png?alt=media" alt=""><figcaption><p>Assign the ACL scope</p></figcaption></figure>

* Under "Role," input the role you created earlier, e.g. dz\_table\_read

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FClWSHNL8GGrVsvLEvfgz%2Fservicenow-7.png?alt=media" alt=""><figcaption><p>Input the new role</p></figcaption></figure>

* Click "Submit"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FrMVNyc2JUdAwa6NHyizp%2Fservicenow-8.png?alt=media" alt=""><figcaption></figcaption></figure>

Repeat for every table you want Dropzone to have access to

#### Assign the ACL to the Role

* Navigate back to Roles
* Click on the role you just created
* In the "Modules with Role" section, click "New"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FKXeB65zK3QAl1HWwdc9e%2Fservicenow-9.png?alt=media" alt=""><figcaption></figcaption></figure>

* Name the record with the name of the table in question
* Click "Link Type"
* Under "Table," select your desired table

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2F2Y5XqR2UVS0qn3kiz7dd%2Fservicenow-11.png?alt=media" alt=""><figcaption></figcaption></figure>

* Click "Submit"

Repeat for every table you want Dropzone to have access to

#### Create a Group

* Navigate to All > System Security > Users and Groups > Groups

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FnQgYxiJnIjm84pnalUAl%2Fservicenow-13.png?alt=media" alt=""><figcaption></figcaption></figure>

* Click "New"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2Fhymve3YiELyVLQuMbcTx%2Fservicenow-2.png?alt=media" alt=""><figcaption></figcaption></figure>

* Name the role something memorable, such as "Dropzone AI"
* Assign yourself (or a dedicated Dropzone User) as the manager
* Click "Submit"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FP1Rt3h5EgP6SQN3o40Rg%2Fservicenow-14.png?alt=media" alt=""><figcaption></figcaption></figure>

* Click "Group Members"
* Click "Edit"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2Fjy1guf6tROAOc7XXsNew%2Fservicenow-15.png?alt=media" alt=""><figcaption></figcaption></figure>

* In the search bar under "Collection," add yourself (or a dedicated Dropzone User)
* Click the `>` then click "Save"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2F8T0dkKeXgm1r0GwIVHMI%2Fservicenow-16.png?alt=media" alt=""><figcaption></figcaption></figure>

* In the "Roles" section, click "Edit"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FCPZG6pjZfSXjqwBeoBbD%2Fservicenow-17.png?alt=media" alt=""><figcaption></figcaption></figure>

* In the search bar under "Collection," add the role you created earlier
* Click the `>` then click "Save"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FQEPVn2I2aE3VdFHlNMYw%2Fservicenow-18.png?alt=media" alt=""><figcaption></figcaption></figure>

The user associated with this group will be used as the OAuth Application User.

## Create an OAuth Inbound Integration

ServiceNow requires a Client ID and Client Secret to enable. To manage OAuth integrations, you must have access to a user with one of the following roles: oauth\_admin mi\_admin admin

To obtain a Client ID and Secret, do the following:

* Navigate to All > System OAuth > Inbound Integrations

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FRDSElHyF6rE1fzezKiy6%2Fservicenow-19.png?alt=media" alt=""><figcaption><p>Navigate to Inbound Integrations</p></figcaption></figure>

* In the upper right, click "New Integration"
* Select "OAuth - Client Credentials Grant"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FZACLyW21g7GfzHmyNlqR%2Fservicenow-20.png?alt=media" alt=""><figcaption></figcaption></figure>

* Name the client something memorable, such as "Dropzone AI"
* Under OAuth Application User, select the user you assigned earlier
* In the "Auth Scopes" section, click "Create auth scope"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2Fbq6xKZutO8G07yADr06N%2Fservicenow-21.png?alt=media" alt=""><figcaption></figcaption></figure>

* Name the scope something memorable, such as "Dropzone"
* Assign the integration the Table API scope

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2F2h34erBajo9nFxi2PN0T%2Fservicenow-22.png?alt=media" alt=""><figcaption><p>Add the Table API scope</p></figcaption></figure>

* Click "Submit"
* Copy the Client ID and Client secret generated for use later in the Dropzone UI where they are called "Client ID" and "Client Secret" respectively

### Enable ServiceNow

To enable the Data Source integration, you will need the following information:

| Dropzone Field    | Source                                                                                 |
| ----------------- | -------------------------------------------------------------------------------------- |
| Instance Hostname | Your ServiceNow instance URL, e.g. yourcompany.service-now\.com                        |
| Username          | The username of the admin user you are using. Only used for basic authentication       |
| Password          | The password for the aforementioned user's account. Only used for basic authentication |
| Client ID         | The Client ID value generated earlier                                                  |
| Client Secret     | The Client Secret value generated earlier                                              |

To enable the Data Source integration, do the following:

* Navigate to your Dropzone AI tenant home page e.g. https\://*mycompany*.dropzone.app
* In the left side bar, navigate to Platform Settings > Integrations

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FQKQGU2YK0KqsewZWvh0i%2Fui-integrations-dropdown.png?alt=media" alt=""><figcaption><p>Integrations Dropdown</p></figcaption></figure>

* Click "Library"

{% hint style="info" %}
If you have previously integrated this application, click "Configured"
{% endhint %}

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2Fx4O3FuRG5IqPwx5sFuHr%2Fapp_system_integrations_library.png?alt=media" alt=""><figcaption><p>Click Library</p></figcaption></figure>

* In the Search bar, search ServiceNow, then click "Configure"

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FOffzwgVrOx6zp4nlz0A1%2Fapp_system_integrations_available_servicenow.png?alt=media" alt=""><figcaption><p>The ServiceNow Tile</p></figcaption></figure>

* Under the Data Source heading, input the Instance Hostname and select your method of authentication from the dropdown

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2Fs79KWsY1eFeePMYRIo85%2Fapp_system_integrations_available_servicenow_data_config-1.png?alt=media" alt=""><figcaption><p>The ServiceNow Data Source Configuration (pt 1)</p></figcaption></figure>

* If you selected Basic, input the username and password

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FghLMxLl4FxHxqerzROLJ%2Fapp_system_integrations_available_servicenow_data_config-2.png?alt=media" alt=""><figcaption><p>The ServiceNow Data Source Configuration (pt 2)</p></figcaption></figure>

* If you selected OAuthInbound, input the Client ID and Secret

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2F4ufWCcos7q5n2t46VvOh%2Fapp_system_integrations_available_servicenow_data_config-3.png?alt=media" alt=""><figcaption><p>The ServiceNow Data Source Configuration (pt 3)</p></figcaption></figure>

* In the "User Base Table" section, input the [table](https://www.servicenow.com/docs/r/washingtondc/api-reference/rest-apis/c_TableAPI.html) that stores user information and identities. Only change it if your organization uses a non-standard table to store username/email information used to resolve user identities (usernames/emails) to a ServiceNow you want Dropzone to access
* In the "Asset Base Table" section, input the table that stores devices/IPs, e.g. [cmdb\_ci\_hardware](https://www.servicenow.com/docs/r/servicenow-platform/configuration-management-database-cmdb/class-hardware.html). To include cloud resources, change it to `cmdb_ci`

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2Fyanctr7yme1zaNFAPp69%2Fapp_system_integrations_available_servicenow_data_config-4.png?alt=media" alt=""><figcaption><p>The ServiceNow Data Source Configuration (pt 4)</p></figcaption></figure>

* If you wish to help guide the AI's information gathering process, you can input information under "Investigation Scope Tables". Here you can define what information resides in your tables, reducing search times and the number of queries run
* For each table, do the following:
  * Click "Add Item"
  * Under "Table Types", select the types of records within your table (`user` for people related information, `records` for divide or infrastructure related information). Both can apply
  * Under "Target Table", input the ServiceNow table
  * Under "Additional Filter", you may input a ServiceNow [encoded query string](https://www.servicenow.com/docs/r/platform-user-interface/c_EncodedQueryStrings.html) to further restrict results
  * Input the the longest length of time you want the AI to query data from
  * Input the maximum number of records to return from this table

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FjwyU4FHy4P2Dskd6RXkT%2Fapp_system_integrations_available_servicenow_data_config-5.png?alt=media" alt=""><figcaption><p>The ServiceNow Data Source Configuration (pt 5)</p></figcaption></figure>

* Click "Test & Save" to finish

<figure><img src="https://3968177484-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDt9gEGwbp9ApiQAJP3hQ%2Fuploads%2FzlXvpTSeEcWS1gYQgTan%2Fui-test-and-save.png?alt=media" alt=""><figcaption></figcaption></figure>

If you have any errors or questions, contact our Customer Success team.
