# Add ServiceNow Connection

Source: https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/how-tos/connection/add-connection/

Connect the ServiceNow integration in Qualytics using the instance URL and the service account credentials you set up in ServiceNow. The credentials are validated against your instance before anything is saved, so the connection is only created once ServiceNow accepts them.

> **Info: Prerequisites**
>
> Complete the [Configure ServiceNow](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/how-tos/configure-servicenow/) steps first to create the service account and gather the instance URL.

> **Info: Permissions**
>
> Users with the **Manager** or **Admin** role can connect the ServiceNow integration. See the [Permissions](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/deep-dive/permissions/) page for details.

## Field reference

The **Add ServiceNow Integration** modal is laid out in two groups.

### Connection Properties

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Instance URL** | Yes | Text | The full instance URL, for example `https://your-instance.service-now.com`. Do not include a trailing slash. |
| **Credentials** | Yes | Secret | The service account username and password joined by a colon, in the format `username:password`, for example `qualytics_integration:YourSecurePassword123`. The value is masked once saved. |

> **Note: Basic authentication only**
>
> The colon-separated pair is what Basic Authentication expects. OAuth 2.0 and credential storage in an external secrets manager are not supported. See [What It Does Not Do](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/deep-dive/how-it-works/#what-it-does-not-do).

### Sync Settings

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Two-way sync** | No | Toggle | On by default. Work notes and status notes are posted to every linked incident, and any single incident can still be set to read only from its card. Turn it off to make the whole integration read only, so incident state, title, and comments are still read back and nothing is written to ServiceNow. |
| **Anomaly status sync** | No | Toggle | Off by default. When on, anomaly statuses and incident states move together through the mapping below. When off, incident states are still read back and shown on the ticket cards, but neither side moves the other. |
| **Mapping** | No | Dialog | Pairs each anomaly status with an incident state. Available only while **Anomaly status sync** is on. |

The switch title names the state it is in, so **Two-way sync** reads **Read only** once it is off, and **Anomaly status sync** reads **Anomaly status not synced**. While status sync is on, a badge next to it names the direction the sync runs in, **Two-way** or **Read only**, set by the switch above it.

### Status Mapping

The **Mapping** row opens the **Status Mapping** dialog, with one row per anomaly status. Each row asks the same question: when an anomaly reaches this status, what state should its incidents sit in? The same pairing is read in reverse, so an incident arriving at that state moves the anomaly back.

| Anomaly status | What it means | What to pair it with in ServiceNow |
| --- | --- | --- |
| **Active** | Detected and awaiting triage. | **New**, the state an incident opens in. |
| **Acknowledged** | Reviewed by someone, still needs follow-up. | **In Progress**, or **On Hold** when the work is waiting on someone else. |
| **Resolved** | A real concern that has been addressed. | **Resolved**, or **Closed** when your process closes incidents outright. |
| **Duplicate** | The same issue as another anomaly. | A closing state. Pair it with the same one as Resolved unless your process tracks duplicates separately. |
| **Invalid** | Not a real data quality concern. | **Canceled**, when your process uses it, so a false positive is not counted as work delivered. |
| **Discarded** | No longer relevant or under review. | A closing state, the same choice as Invalid. |

ServiceNow fixes the incident states rather than letting each project define them, so the dialog always offers the same six: **New**, **In Progress**, **On Hold**, **Resolved**, **Closed**, and **Canceled**. There is no project to pick first, and the states load as soon as the connection properties are filled in. See [Incident States](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/deep-dive/sync-behavior/#incident-states) for what each one means.

The rows do not start empty. Turning **Anomaly status sync** on pairs Active with **New**, Acknowledged with **In Progress**, and each of the four archived statuses with **Resolved**. Four of the six statuses archive the anomaly, so in most processes they end up pointing at the same closing state. Splitting them is worth it only when your ServiceNow reports treat those outcomes differently.

Three rules apply while you fill the dialog:

- **A row can be left out.** Clearing it makes the field read **Leave unchanged**, and that anomaly status then moves no incident and is never moved by one. At least one row has to be paired, so saving with status sync on and nothing mapped is refused.
- **A state can be typed in.** The field keeps a name that is not in the list, which covers an instance with customized states. Qualytics recognizes only the six above by name, so anything else reads back on the card as `Unknown` with its code.
- **Reset starts the rows over.** The **Reset** button reloads the states from your instance and fills the rows with the defaults again, discarding the edits made since the dialog opened. It leaves the dialog open so you can check the result, and **Apply** is still what saves it. **Cancel** closes the dialog and leaves the saved mapping alone.

For what each sync mode writes and reads, see [Read only and two-way sync](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/deep-dive/sync-behavior/#read-only-and-two-way-sync) and [Anomaly status sync](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/deep-dive/sync-behavior/#anomaly-status-sync).

## What Happens When You Save

Qualytics tests the credentials against the instance before storing anything, by asking ServiceNow for a single incident. Nothing is saved when that call fails, so a refused connection leaves no half-configured integration behind.

Four things are worth checking when it is refused:

- The instance URL is complete, starts with `https://`, and has no trailing slash.
- The credentials are one string in the form `username:password`.
- The service account holds the `itil` role and is active.
- The deployment can reach the instance, and the instance allows the deployment's addresses through.

For what each failure looks like and how to resolve it, see [Troubleshooting](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/troubleshooting/#setup).

## Steps

**Step 1**: In the left side panel, click **Settings** .

**Step 2**: The **Connections** tab opens by default. Click the **Integrations** tab.

**Step 3**: Scroll to the **Ticketing** group, find the **ServiceNow** row, and click **Connect** . The **Add ServiceNow Integration** modal opens.

**Step 4**: Fill in the fields. See the [Field reference](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/how-tos/connection/add-connection/#fields) above for what each one holds and which are required.

**Step 5**: If you turned **Anomaly status sync** on, click the **Mapping** row to open the **Status Mapping** dialog, pair each anomaly status with an incident state, and click **Apply**.

**Step 6**: Click **Create**. Qualytics validates the credentials against your instance, and a success message appears with the **ServiceNow** row now showing **Connected** and your instance URL.

*Last updated: September 20, 2026.*
