# How the ServiceNow Integration Works

Source: https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/deep-dive/how-it-works/

This page explains how the ServiceNow integration behaves internally: how data flows between Qualytics and ServiceNow, what is synced, state mappings, and how fields are mapped.

## Integration Flow Diagram

The following diagram illustrates how data flows from Qualytics to ServiceNow:

```mermaid
flowchart TB
    subgraph Qualytics["Qualytics Platform"]
        A[Anomaly Detected] --> B{User Action}
        B -->|Create Ticket| C[Create Ticket Request]
        B -->|Acknowledge| D[Status Change Event]
        B -->|Add Comment| E[Comment Event]
        B -->|Archive/Resolve| F[Resolution Event]
    end

    subgraph Background["Background Processing"]
        C --> G[Qualytics API]
        D --> H[Sync Worker]
        E --> I[Sync Worker]
        F --> J[Sync Worker]
    end

    subgraph ServiceNow["ServiceNow Instance"]
        G -->|POST /incident| K[New Incident Created]
        H -->|PATCH /incident| L[Work Note Added]
        I -->|PATCH /incident| L
        J -->|PATCH /incident| M[Resolution Work Note]
    end

    K --> N[Ticket Link Stored]
    N --> O[Anomaly & Ticket Linked]
```

## What Gets Synced

Qualytics posts to ServiceNow and reads the incident's state and short description back on every sync. With **Anomaly status sync** on, the anomaly and its incidents follow the status mapping in both directions, the same way the [Jira integration](https://userguide.qualytics.io/settings/integrations/ticketing/jira/deep-dive/sync-behavior/#anomaly-status-sync) does. Work notes written in ServiceNow are not imported.

| Direction | Action | Result | Status |
| --- | --- | --- | --- |
| Qualytics → ServiceNow | Create ticket from anomaly | New incident created with anomaly details | Supported |
| Qualytics → ServiceNow | Acknowledge anomaly | Work note added to incident with status change. With status sync on, the incident also moves to the mapped state | Supported |
| Qualytics → ServiceNow | Archive anomaly (resolve) | Work note added to incident with resolution status. With status sync on, the incident also moves to the mapped state | Supported |
| Qualytics → ServiceNow | Add comment to anomaly (standalone, on a specific change, or a reply) | Comment pushed to incident as a work note | Supported |
| Qualytics → ServiceNow | Link existing ticket | Anomaly details appended to incident description; work note added with linkage info | Supported |
| Qualytics → ServiceNow | Update Ticket Status Flow action | Incident state set to the target status | Supported |
| ServiceNow → Qualytics | Change incident state | Shown on the linked ticket card. With status sync on, a mapped state also moves the anomaly | Supported |
| ServiceNow → Qualytics | Add work notes or comments | Not reflected, comments do not appear in Qualytics | Not supported |
| ServiceNow → Qualytics | Close or resolve incident | Shown on the linked ticket card. With status sync on, the anomaly is archived with the mapped status | Supported |

## Authentication

The ServiceNow integration uses **Basic Authentication** with a ServiceNow username and password. The credentials must belong to a dedicated service account with the `itil` role assigned, so Qualytics can create and update Incident records on its behalf.

See the [Configure ServiceNow](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/how-tos/configure-servicenow/) and [Add Connection](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/how-tos/connection/add-connection/) guides for the full setup flow.

## What Happens on Each Operation

Creating and linking incidents, what Qualytics appends to a new incident, the incident states, the two sync modes, the status mapping, and how comments travel are covered on their own page. See [ServiceNow Sync Behavior](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/deep-dive/sync-behavior/).

The form a person fills in when creating an incident, with every field it accepts and what ServiceNow stores each one as, is on [Create a ServiceNow Ticket](https://userguide.qualytics.io/anomalies/how-tos/ticket/servicenow/create-ticket/#fields).

## What the Integration Can Do

**Incidents**

- Create a ServiceNow incident from an anomaly, with the anomaly's context and a link back to Qualytics already in the description.
- Link an incident that already exists, found by number or by short description.
- Link several incidents to one anomaly, and the same incident to several anomalies.
- Open incidents automatically from a Flow, and move an existing linked incident with the **Update Ticket Status** action.

**Status**

- Post a work note to every two-way linked incident when the anomaly is acknowledged or archived.
- Read each incident's state and short description back onto its ticket card.
- Move incidents and anomalies together through a status mapping, which is off until an administrator turns it on.

**Comments**

- Push comments written on the anomaly onto the incident as work notes, naming their Qualytics author.

**Control**

- Set the whole integration, or one single linked incident, to read only.

## What It Does Not Do

- **Comments travel one way.** Work notes written in ServiceNow are not imported into Qualytics, and neither are edits or deletions of them. The [Jira integration](https://userguide.qualytics.io/settings/integrations/ticketing/jira/deep-dive/sync-behavior/#comments-from-jira) mirrors them in both directions.
- **No instant updates.** ServiceNow cannot notify Qualytics the moment an incident changes, so there is no webhook to register. Changes arrive when the anomaly is opened or on the scheduled read.
- **Incidents only.** The integration works on the Incident table. Other record types, such as Defect or Enhancement, cannot be created or linked.
- **The caller cannot be set.** Every incident is opened by the integration's service account.
- **Values are typed, not picked.** Category, subcategory, assignment group, and assigned user are entered by hand rather than chosen from a list read out of ServiceNow. See [Find ServiceNow Values](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/how-tos/find-servicenow-values/).
- **One ticketing integration at a time.** A deployment connects either ServiceNow or Jira, and a second one is refused until the first is disconnected.
- **One instance.** A single ServiceNow instance can be connected.
- **Basic authentication only.** The integration authenticates with a username and password. OAuth 2.0 is not supported.
- **Credentials live in Qualytics.** They are stored encrypted by the platform rather than read from an external secrets manager such as HashiCorp Vault.

## See Also

- **Sync Behavior**

  What happens on each operation: creating and linking incidents, the incident states, and the two sync modes.

  [Sync Behavior](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/deep-dive/sync-behavior/)
- **Requirements**

  The ServiceNow instance, the account Qualytics authenticates as, and what it must be allowed to do.

  [Requirements](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/deep-dive/requirements/)
- **Best Practices**

  Reading the Tickets panel, and the choices that keep incidents and anomalies in step.

  [Best Practices](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/deep-dive/best-practices/)
- **Permissions**

  The roles, team permissions, and ServiceNow-side permissions each action needs.

  [Permissions](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/deep-dive/permissions/)

*Last updated: September 20, 2026.*