Ardoq’s ServiceNow integration allows you to:

Import your data as components or references into Ardoq so you can visualize the dependencies that exist between them and other components in your architecture such as applications, departments, people, etc.

With Ardoq’s ServiceNow integration, you can also automate imports by setting a daily or weekly interval schedule.

ServiceNow Setup

Install the Ardoq add-on on your ServiceNow instance

Navigate to the ServiceNow Store and install the Ardoq ServiceNow Add-on.

Note: You will need ServiceNow HI credentials to install add-ons. Contact your company ServiceNow admin if needed.

Log in to your ServiceNow instance and set up an 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.

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.

Ardoq Setup

From the main menu, navigate to Home > Import and integrations and select ServiceNow.
Select the Connections tab and click Create new connection
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.
Click Create connection to finalize your changes.

Importing Data from ServiceNow

With your connection ready, you can click Create new import from the ServiceNow integration page.

On the Select data tab, select the connection you just created and Ardoq will fetch the tables from your ServiceNow instance.
Note: Tables fetched from ServiceNow depend on the provided user's permissions.
Select the tables and the relevant fields you want to import into Ardoq.
Note: Reference fields will show two entries in the field list: the label of the reference and the ServiceNow sys-id of the referenced record. This will allow you to create references based on either the ID or name.
Proceed to the Configure data step when you're ready and map your ServiceNow fields into Ardoq using the standard configuration process.

Scheduling Your Import

After a successful test successful import, you can schedule Ardoq to perform daily or weekly imports of your configured tables.

When scheduling an import, you can choose to disable manual data changes in the workspace. Enabling this ensures your workspace mirrors the source data. For more details, read our article on data sync strategies on import.

ServiceNow Integration Permissions for Ardoq

Basic Permissions

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

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.

Refer to the ServiceNow documentation for a complete guide on setting up ACL rules: Access Control Rules and Creating an ACL Rule.

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

X_ardas_ardoq_int.rest: Core Ardoq integration role.
Sn_cmdb_user: Provides read access to specific CMDB tables, the CMDB class manager hierarchy, relationships, and service maps.
Service_viewer: Allows read access to every table in CMDB as all tables inherit from cmdb_ci.

FAQ

Does the Ardoq integration with Servicenow allow import of all tables or just CMDB tables?

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?

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?

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?

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 for guidance on creating these filters.

Where to Add the Query Filter:

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:

Navigate to the "Select data" step in the ServiceNow import setup.
Select your connection to your ServiceNow instance.
Under Select tables and fields, choose the table you wish to import data from (e.g., "Business Service").
Once the table is selected, a Query filter option will appear at the top of the field selection area.
Click on Query filter and enter your filter criteria using the sysparm_query syntax to narrow down the data fetched from ServiceNow.
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

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

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.