How the ServiceNow Integration Works
This page explains how the ServiceNow integration behaves under the hood — 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:
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
The current release supports one-way synchronization from Qualytics to ServiceNow.
| Direction | Action | Result | Status |
|---|---|---|---|
| Qualytics → ServiceNow | Create ticket from anomaly | New incident created with anomaly details | |
| Qualytics → ServiceNow | Acknowledge anomaly | Work note added to incident with status change | |
| Qualytics → ServiceNow | Archive anomaly (resolve) | Work note added to incident with resolution status | |
| Qualytics → ServiceNow | Add comment to anomaly | Comment pushed to incident as a work note | |
| Qualytics → ServiceNow | Link existing ticket | Anomaly details appended to incident description; work note added with linkage info | |
| ServiceNow → Qualytics | Change incident state | Not reflected — anomaly status unchanged | |
| ServiceNow → Qualytics | Add work notes or comments | Not reflected — comments do not appear in Qualytics | |
| ServiceNow → Qualytics | Close or resolve incident | Not reflected — anomaly remains in current state |
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 and Add Connection guides for the full setup flow.
ServiceNow State Mappings
ServiceNow uses numeric state values for incidents. Understanding these states helps when working with the integration:
| State Code | State Name | Description |
|---|---|---|
| 1 | New | Incident has been created but not yet worked on |
| 2 | In Progress | Work is actively being done on the incident |
| 3 | On Hold | Incident is waiting for external input or resources |
| 4 | Awaiting User Info | Incident is paused awaiting input from the requester |
| 5 | Awaiting Problem | Incident is awaiting resolution of a related problem |
| 6 | Resolved | The issue has been fixed/addressed |
| 7 | Closed | Incident is complete and verified |
| 8 | Canceled | Incident was canceled without resolution |
One-Way State Updates
Qualytics does not automatically update anomaly status based on ServiceNow state changes. This design prevents synchronization loops and maintains clear ownership: ServiceNow is the "ticket of record" while Qualytics is the "anomaly of record."
Field Mapping Reference
Incident Fields Supported
When creating a ticket from Qualytics, the following ServiceNow Incident fields can be populated:
| Field Name | ServiceNow Field | Required | Notes |
|---|---|---|---|
| Short Description | short_description |
Yes | Brief summary of the issue |
| Description | description |
No | Detailed description; auto-populated with anomaly details |
| Priority | priority |
No | Values: Critical, High, Moderate, Low, Planning |
| Urgency | urgency |
No | Standard ServiceNow urgency values |
| Impact | impact |
No | Standard ServiceNow impact values |
| Category | category |
No | Must match exact category name in ServiceNow |
| Subcategory | subcategory |
No | Must match exact subcategory name |
| Assignment Group | assignment_group |
No | Requires sys_id of the group (not name) |
| Assigned To | assigned_to |
No | Username of the assignee |
Auto-Populated Fields
The following fields are automatically populated by Qualytics when creating a ticket:
| Field | Auto-Populated Value |
|---|---|
| Description (body) | Anomaly ID, type, status at detection, field/check message, failed checks, hyperlink back to Qualytics anomaly |
| Caller | Currently uses service account (user-based caller not yet supported) |
| Work Notes (on updates) | Status changes (acknowledge, archive) and comments from Qualytics with timestamps |
Key Integration Operations
Create Ticket
Creates a ServiceNow incident from a Qualytics anomaly with:
- Required fields:
short_description - Optional fields:
caller_id,category,subcategory,assignment_group,impact,urgency,description,comments - Auto-included: Anomaly ID, status, type, failed checks, and hyperlink back to the Qualytics anomaly (appended to the description)
Link Existing Ticket
Links an existing ServiceNow incident to an anomaly:
- Appends anomaly details to the existing description
- Adds a work note about the linkage
Sync Anomaly Status
When anomaly status changes in Qualytics:
- Adds a timestamped work note to the linked ServiceNow incident
- Example:
[2024-01-15 10:30:00 UTC] Qualytics Anomaly Status: Acknowledged
Note
Status changes add work notes but do not change the incident's state. This preserves ITSM workflow control.
Sync Comments
When comments are added to anomalies in Qualytics:
- The comment text is synced to linked tickets as work notes
- Example:
Comment from Qualytics: <user's comment>
Supported Features & Capabilities
Current Release Features
| Feature | Status |
|---|---|
| Create Incident from anomaly | |
| Link existing Incident to anomaly | |
| Link multiple tickets to one anomaly | |
| Sync anomaly acknowledge to ServiceNow | |
| Sync anomaly archive (resolve) to ServiceNow | |
| Push comments to ServiceNow work notes | |
| Hyperlink from ServiceNow back to Qualytics anomaly | |
| Basic Authentication (username/password) | |
| Search existing ServiceNow tickets |
Known Limitations
| Feature | Status |
|---|---|
| Two-way sync (ServiceNow → Qualytics) | |
| See ServiceNow ticket state changes in Qualytics | |
| Drop-down fields populated from ServiceNow | |
| Multiple ServiceNow instances | |
| Ticket types other than Incident (Defect, Enhancement, etc.) | |
| Auto-populate caller from logged-in user | |
| OAuth 2.0 authentication | |
| HashiCorp Vault credential storage | |
| Automatic ticket creation from Flows |