> For the complete documentation index, see [llms.txt](https://documentation.ardoq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ardoq.com/integrations/out-of-the-box-integrations/servicenow.md).

# ServiceNow

Integrate Ardoq and ServiceNow to ensure your data is always up to date with the latest changes.

Ardoq’s ServiceNow integration allows you to import your data as components and references so that you can visualize the dependencies that exist between them and other components in your architecture such as applications, departments, people, etc.

## ServiceNow Setup <a href="#h_b3c96a0973" id="h_b3c96a0973"></a>

{% stepper %}
{% step %}

### Install the Ardoq add-on on your ServiceNow instance

Navigate to the ServiceNow Store and install the [Ardoq ServiceNow Add-on](https://store.servicenow.com/sn_appstore_store.do#!/store/application/17aff7a91b1050508581a79b2d4bcb92/1.0.19).

{% hint style="info" %}
**Note**: You will need **ServiceNow HI** credentials to install add-ons. Contact your company ServiceNow administrator if needed.
{% endhint %}
{% endstep %}

{% step %}

### Set up a ServiceNow integration user

We recommend that you create a dedicated integrations-specific user with table-permissions limited to exactly the data you want to sync with Ardoq.

{% hint style="info" %}
**Note**: Assign the role `x_ardas_ardoq_int.rest` to your integration user. Without this role, the user won’t be able to use the integration. Additionally, multi-factor authentication should be disabled by default for the integration user.
{% endhint %}
{% endstep %}
{% endstepper %}

## Ardoq Setup <a href="#h_6668c8916a" id="h_6668c8916a"></a>

1. From the main menu, navigate to Imports & Integrations and select the ServiceNow integration.
2. Select the **Connections** tab and click **Create new connection**
3. In the dialog that appears, fill in the following details:

   1. **Connection name**: A relevant name for your ServiceNow connection.
   2. **Base URL**: The URL to your ServiceNow instance.
   3. **Authentication type**: Select an authentication type — basic or OAuth — and fill in the relevant credentials.

   **Note**: Make sure that the Base URL doesn't contain /login.do at the end.
4. Click **Create connection** to finalize your changes.

### Authentication Methods <a href="#h_a639a5f60c" id="h_a639a5f60c"></a>

Ardoq supports basic authentication with a username and password, but also the following OAuth 2.0 methods:

* OAuth 2.0 JWT
* OAuth 2.0 Password
* OAuth 2.0 Client Credentials (ServiceNow)
* OAuth 2.0 Client Credentials (Generic)

Refer to the OAuth configuration example for more details.

## ServiceNow Integration Permissions for Ardoq <a href="#h_76c580d8e0" id="h_76c580d8e0"></a>

### Basic Permissions <a href="#h_86b40c3d3e" id="h_86b40c3d3e"></a>

The ServiceNow integration is flexible — there are no restrictions on the data you can import from ServiceNow.

Once the Ardoq Integration add-on is installed from the ServiceNow store, an Ardoq user account with the specific role `x_ardas_ardoq_int.rest` is required.

For security and efficiency, ensure the integration user has access only to necessary tables for importing data, aligning with the principle of least privilege.

It's critical to define Groups, Roles, and Access Control Lists (ACLs) in ServiceNow accurately. Precise ACL privileges are needed on tables for read, create, write, and delete operations.

Ensure that the integration user has `canRead` privileges with the group `x_ardas_ardoq_int.rest` assigned to these operations.

### ACL Rules <a href="#h_e39db45687" id="h_e39db45687"></a>

You'll need to ensure that the following rules are properly set up:

* **User Roles**: Match ServiceNow roles with required access levels in Ardoq.
* **Table Level ACL Rules**: Control the integration user’s access to necessary tables.
  * Access controls within ServiceNow should be configured based on the roles assigned to tables to ensure appropriate read and write operations are maintained. Additionally, it's crucial to activate these rules to enforce the access control effectively. After setting up these role-based access permissions and activating them, the integration user should gain the necessary visibility of the table.
* **Field Level ACL Rules**: Manage permissions at the field level within tables. Remember, field-level ACL rules can supersede table-level ACL rules.

Remember to double-check User Roles, Table-level, and Field-level ACL rules to maintain a secure integration. Field-level ACLs can override broader ACL policies.

{% hint style="info" %}
Refer to the ServiceNow documentation for a complete guide on setting up ACL rules: [Access Control Rules](https://docs.servicenow.com/bundle/utah-platform-security/page/administer/contextual-security/concept/access-control-rules.html) and [Creating an ACL Rule](https://docs.servicenow.com/bundle/utah-platform-security/page/administer/contextual-security/task/t_CreateAnACLRule.html).
{% endhint %}

To ensure seamless integration between ServiceNow and Ardoq, the integration user must have the following combination of roles:

1. **X\_ardas\_ardoq\_int.rest**: Core Ardoq integration role.
2. **snc\_internal**: The integration user should be assigned this standard ServiceNow role. It is required for the Scripted REST APIs to be accessible, especially if the Explicit Roles plugin is enabled.
3. **Sn\_cmdb\_user**: Provides read access to specific CMDB tables, the CMDB class manager hierarchy, relationships, and service maps.
4. Service\_viewer: Allows read access to every table in CMDB as all tables inherit from `cmdb_ci`.

If you are using ServiceNow's High Security/Identity Security ACLs, then it is also recommended that you add the following role:

1. **dm\_user\_role\_read**: provides access to the user table.

## FAQ

### Does the Ardoq integration with Servicenow allow import of all tables or just CMDB tables? <a href="#h_66ba44597e" id="h_66ba44597e"></a>

As long as the integration user being used for the ServiceNow integration has the appropriate read permissions in ServiceNow then all the tables can be retrieved.

### Is it possible to specify which fields are/aren't bi-directional? <a href="#h_7d7b23249b" id="h_7d7b23249b"></a>

The import is a one-way update — there are no two-way fields.

### What happens if the exact same field in Ardoq and Servicenow is updated at the same time? Which takes precedence? <a href="#h_f104766e69" id="h_f104766e69"></a>

Data from ServiceNow will override data at Ardoq side on import because it is 1-way update.

### How can I use a prefetch filter for ServiceNow data imports? <a href="#h_c68a5e7446" id="h_c68a5e7446"></a>

To filter data before importing from ServiceNow, you can use a ServiceNow-specific filter with the `sysparm_query` parameter. This allows you to set a filter directly on the ServiceNow table, fetching only relevant information to improve load times. Refer to [ServiceNow's sysparm\_query documentation](https://developer.servicenow.com/dev.do#!/learn/courses/vancouver/app_store_learnv2_rest_vancouver_rest_integrations/app_store_learnv2_rest_vancouver_inbound_rest_integrations/app_store_learnv2_rest_vancouver_more_about_query_parameters) for guidance on creating these filters.

#### Where to Add the Query Filter <a href="#h_9f5d8dee7f" id="h_9f5d8dee7f"></a>

In the Ardoq data import process, the query filter should be applied in the **Select data** step, specifically after selecting the table you want to import. Here’s a step-by-step guide:

1. Navigate to the **Select data** step in the ServiceNow import setup.
2. Select your connection to your ServiceNow instance.
3. Under Select tables and fields, choose the table you wish to import data from.
4. Click the **Filters** button and enter your filter criteria using the `sysparm_query` syntax to narrow down the data fetched from ServiceNow.
5. Click Apply to save the filter.

This filter will be applied before importing, allowing you to limit the data pulled from ServiceNow, which can enhance performance by reducing data volume.

### Error when fetching tables <a href="#h_75ec14a143" id="h_75ec14a143"></a>

Verify that the HTTP response time and size is adequate for the number of records being imported. Increase the limit if you get a fetch error.

### Establishing a connection using a custom domain <a href="#h_154282f9b4" id="h_154282f9b4"></a>

Configure the gateway on port `443` to make sure there are no egress/outgoing traffic issues or the connection will be rejected.

### ​Why is my ServiceNow integration failing with an `An error occurred when fetching tables. Please try again and contact support if the issue persists` error even though my credentials are correct?

This error can sometimes occur due to conflicting "Inbound Authentication Profiles" in ServiceNow. If a secondary authentication profile overrides the default one used by Ardoq, it can prevent Ardoq from authenticating correctly. Try disabling or deleting any conflicting profiles in your ServiceNow configuration and retest the integration. If the issue persists, contact your ServiceNow administrator for assistance.

## OAuth Configuration between Ardoq and ServiceNow <a href="#h_14c4467c47" id="h_14c4467c47"></a>

{% hint style="info" %}
**Note**: You will need ServiceNow admin permissions to modify OAuth settings.
{% endhint %}

In this example, we'll be using the OAuth 2.0 Client Credentials (ServiceNow) connection between Ardoq and ServiceNow.

Our first step will be creating a new inbound integration in ServiceNow.

1. From the main menu in ServiceNow, navigate to **System OAuth** > **Inbound Integrations**
2. Click **New integration**
3. Select **OAuth — Client credentials grant**
4. Give your connection a name and assign an OAuth application user
   1. The OAuth application user should have the relevant permissions to access the necessary ServiceNow tables.
5. Copy the **Client ID** and **Client secret** for use later.

Next, we'll need to add a property to the ServiceNow instance to allow OAuth client credential grants to work.

The ServiceNow admin should go to the `sys_properties.list` and add a new property called `glide.oauth.inbound.client.credential.grant_type.enabled` and set its value to `true`.

Finally, we can create a ServiceNow connection in Ardoq. In Ardoq, use the main menu to go to Imports & Integrations and select ServiceNow from the list of all integrations. Go to the Connections tab and click Create new connection.

In the dialog that opens, give your connection a name, input your base URL, select the OAuth 2.0 Client Credentials (ServiceNow) option, and input your client ID and client secret. You should be able to create the connection at this point. If everything went successfully, you can create a new import and see if your connection can retrieve your ServiceNow tables.