> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incident.io/llms.txt
> Use this file to discover all available pages before exploring further.
# ServiceNow
We have a ServiceNow integration to keep your incidents in sync with incident.io.
For teams running their operations in ServiceNow, we know how important it is to preserve the structured record-keeping you rely on. This integration closes the loop between fast-moving incident response in Slack or Microsoft Teams and the structured processes in ServiceNow, so you get the best of both worlds without duplicate effort.
This document will explain how to connect ServiceNow to [incident.io](http://incident.io/).
## Connecting ServiceNow
incident.io connects to ServiceNow using an **OAuth app** and **Web Service user account**. Let's get started with the OAuth app.
You will need a ServiceNow Admin to complete these steps.
## 1. Create an OAuth App
Log in to ServiceNow and search for "**OAuth**" in the filter navigation:
Select **Application Registry**, and click **New**.
Select **New Inbound Integration Experience**.
Click **New Integration.**
Click **OAuth - Resource owner password credential grant.**
Enter 'incident.io' for the name, and add 'useraccount' to the Auth Scopes section. Leave other options as the defaults:
Find the app you've just created in the list. Copy the **Client ID** and **Client Secret** values: we'll need them later!
## 2. Create a Web Service Account
Any ServiceNow user account can be used so long as it has the relevant roles assigned. However, any actions taken by incident.io in ServiceNow will appear as being taken by this user account, so we strongly recommend creating a user for this purpose only.
In ServiceNow, search for '**User Administration**' in the filter navigation:
Select **Users**, then click **New** in the top-right.
Select a **username** and **email**, for example 'incident.io' and '[incidentio-service@my-domain.com](mailto:incidentio-service@my-domain.com)':
Make sure **Password needs reset** and **Locked out** are not selected, and **Active** is selected.
Change the identity type to **Machine.**
Click **Submit**, then navigate to the newly-created user.
At the bottom, select the **Roles** tab, then **Edit..** Add the following roles:
* `admin`: allows us full access to your ServiceNow instance. This is the recommended approach, as it ensures all current and future features work without additional configuration.
* If you don't wish to grant the `admin` role, create the user without the `admin` role and follow the [granular permissions](#granular-permissions) section below to create a custom role.
Click **Save** to apply these changes and return to the user page.
Click **Set Password**, then **Generate**, then **Save Password**.
Copy the newly-generated password, we'll need it shortly! Make sure to update the record before coming back to [https://app.incident.io](https://app.incident.io/).
## 3. Installing the integration
We're now ready to install the ServiceNow integration in incident.io.
Go to [Settings → Integrations](https://app.incident.io/~/settings/integrations/servicenow), and click on **ServiceNow**, then **Connect**.
Use the following details:
* Your **subdomain** is the part of the URL where you log in to ServiceNow. For example, if your ServiceNow instance is accessed at `hyper-payments.service-now.com`, your subdomain is `hyper-payments`.
* Your **OAuth Client ID** and **OAuth Client Secret** are the credentials you created in [part 1](#1-create-an-oauth-app) above.
* Your **Username** and **Password** are the credentials for the service account you created in [part 2](#2-create-a-web-service-account).
* Click **Connect** to verify your credentials and complete the connection
If you have any issues, please get in touch.
Next, you'll want to set-up your incident ticket to sync incidents to ServiceNow, which you can view steps to complete [here](/integrations/servicenow-sync).
## Granular Permissions
If you do not wish to grant the `Admin` role, you can set-up a custom role and assign it to the service user.
Setting up granular permissions may mean that new features for ServiceNow are not available unless you manually update the role with new permissions.
### Custom Role
First, we need to create a new role for the service user.
Search for '**Roles**' and select the '**Roles**' option under '**Users and Groups**'.
Click **New**.
Create a new role named `incident.io Application Role`.
### ACLs
Next, we need to create new ACLs that grant read-only access to the data and UI policies.
To add new ACLs, you first need to elevate your user to Security Admin.
Click your profile icon and select '**Elevate role**'.
Click '**security\_admin**' and then '**Update**'.
Search for '**Access Control**' and select '**Access Control (ACL)**' under 'System Security'.
We need to create 5 new ACLs to read the following tables:
* `sys_ui_policy`
* `sys_ui_policy_action`
* `sys_data_policy`
* `sys_data_policy_rule`
* `sys_journal_field`
Select '**New**'.
Create a new Access Control record with the following properties:
* **Type**: `record`
* **Operation**: Change from `create` to `read`
* **Application**: `Global`
* **Active**: checked
* **Decision Type**: `Allow If`
* **Admin overrides**: checked
* **Name**: Type the table name in the first dropdown.
* Leave the second dropdown as `-- None --`.
Click '**Submit**'. You will be prompted to select a role. Select the role you created earlier.
Click '**OK**' and then click '**Update**' to save the ACL.
Repeat this for each table, so that you have 5 new ACLs created:
* `sys_ui_policy`
* `sys_ui_policy_action`
* `sys_data_policy`
* `sys_data_policy_rule`
* `sys_journal_field`
### Assign Roles To The Service User
Now that we have the role and the ACLs, we need to add the required roles to our user.
Search for '**User Administration**' in the filter navigation:
Select '**Users'**, then select the user you created for incident.io.
At the bottom, select the '**Roles'** tab, then **Edit...** Add the following roles:
* `cmdb_read`: allows us to read data from your Configuration Management Database.
* `sn_cmdb_user`: allows us to read information about users and groups in your ServiceNow account.
* `incident_manager`: allows us to sync incident data into ServiceNow incident records.
* `incident.io Application Role`: allows us access to UI and data policies, as well as work notes on incidents.
Click **Save** to apply these changes and then **Update** to save the user.