> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/it-service-management/servicenow.md).

# ServiceNow

The ServiceNow integration connects Harmony to your ServiceNow instance, enabling bidirectional ticket sync, service catalog support, workflow automation, and richer agent context - all without leaving Harmony. This article covers how to connect, configure, and get the most out of the integration.

***

### Connecting to ServiceNow

Harmony offers two connection methods for ServiceNow: a service account (Basic Auth) and OAuth. In **Settings** > **Integrations**, both appear under **IT Service Management**, as **ServiceNow (Service Account)** and **ServiceNow (OAuth)**. Choose the method that best fits your environment.

#### Service Account (Basic Auth)

You can connect Harmony to ServiceNow using a service account, giving you a straightforward alternative to OAuth.

To set up the connection:

1. Go to **Settings** > **Integrations**, find **ServiceNow (Service Account)** under **IT Service Management**, and click its card.
2. Enter your **Instance URL** in the form `https://your-instance.service-now.com`. Both connection methods accept only a `service-now.com` address, not a custom domain.
3. Enter your service account **Username** and **Password**. Harmony validates the credentials once all three fields are filled in.
4. Click **Connect**.

A **Create a service account** link is provided directly in the setup form if you need help getting started. No OAuth app configuration or credential exchange is required.

Both inbound and outbound ticket sync are fully supported with service account connections.

**Required Roles**

Harmony checks the credentials when you connect by reading your instance's incident table. If ServiceNow denies access, the form shows an error. Make sure the service account has these roles:

* `itil`
* `catalog_admin`
* `interaction_agent` (for syncing conversations as interactions)

Assign the missing roles to the service account in ServiceNow, then enter the credentials again.

#### OAuth

You can also connect using OAuth. Go to **Settings** > **Integrations**, find **ServiceNow (OAuth)** under **IT Service Management**, and click its card. A setup wizard walks you through the connection:

1. **Instance** - Enter your **Instance URL** and click **Continue**.
2. **Connect** - In ServiceNow, open **System OAuth** > **Application Registry** (the wizard links to it; this needs the `oauth_admin` role), click **New**, and choose **Create an OAuth API endpoint for external clients**. Set its **Redirect URL** to the URL shown in the wizard and submit the form. Then copy the **Client ID** and **Client Secret** (click the lock icon to show the secret) into the wizard and click **Continue**. Click **Connect** and sign in to your instance as the integration account to grant access.
3. **Integrate** - Choose the capabilities you want to integrate and click **Validate access**.
4. **Validate** - Review the permission check and click **Finish setup**.
5. **Configure** - Choose the [integration settings](#integration-settings) and click **Complete Configuration**.

Each ServiceNow instance gets its own dedicated OAuth app configuration.

**Capability Validation at Connection Time**

When connecting via OAuth, Harmony probes your account's permissions in real time and immediately surfaces any missing access before any data flows. Each capability lists the ServiceNow role it needs:

* **Inbound ticket sync** (`itil`) - syncing tickets from ServiceNow into Harmony
* **Outbound sync** (`itil`) - pushing updates from Harmony back to ServiceNow
* **Service catalog** (`catalog_admin`) - reading catalog item variables on request items
* **Knowledge base** (`knowledge`) - reading knowledge articles linked to tickets

If a capability fails, grant the missing roles in ServiceNow and click **Validate again** - no reconnect is needed. Clicking **Cancel** finishes setup without the failed capabilities. After connecting, you can change the selection under **Integrated capabilities** in the integration settings and click **Validate & save**.

This means configuration issues are caught at setup time rather than surfacing as silent failures later.

***

### Configuration

#### Integration Settings

After connecting, you can configure the following options in the integration settings.

**Ticket Sync Settings**

* **Enable Data Migration** - pull inbound tickets from ServiceNow into Harmony.
* **Inbound assignment groups** - shown when **Enable Data Migration** is selected. Pull tickets only from the selected assignment groups; when none are selected, tickets are pulled from all groups.
* **Sync back changes in Harmony to their original ticket** - shown when **Enable Data Migration** is selected. Sync ticket updates from Harmony back to ServiceNow.

**Sync Conversations as Interactions**

The **Sync conversations as interactions** toggle is available in the extensions section of the ServiceNow OAuth integration settings, bringing it in line with the service account integration. Turning this option on or off and saving will persist your preference to the integration configuration. The **Save Changes** button appears as soon as you adjust the toggle so unsaved changes are always visible.

**Category and Sub-Category Fields**

You can configure Harmony to automatically populate the `category` and `subcategory` fields on outbound ServiceNow tickets, using your own ServiceNow taxonomy.

* **Your own category vocabulary**: Configure a list of valid category values from your ServiceNow instance at the integration level. All credentials sharing that integration use the same vocabulary.
* **AI-powered classification**: Harmony's classifier maps each ticket to the appropriate category and subcategory values from your configured list, so tickets created or updated by Harmony carry the category values your team already uses for routing, reporting, and metrics - no manual mapping tables required.

***

### Ticket Sync

#### Inbound Sync - Richer Ticket Context

Harmony pulls a significantly expanded set of fields from ServiceNow tickets, giving your team fuller context without needing to switch tools. Enriched ticket descriptions include:

* **All tickets:** category, subcategory, business service, location, impact, urgency, contact type, company, and department
* **Requests (RITMs):** quantity, stage, and due date
* **Change requests:** type and risk
* **Incidents:** severity and cause

Catalog item variables from RITM and service task records are automatically extracted and rendered as a formatted table within the ticket description. Reference-type fields - such as requested-for users, license selections, and linked records - are resolved to their human-readable display names rather than raw system IDs. Agents working on catalog-driven tickets see complete, meaningful variable data without navigating back to ServiceNow.

Audit history shows real user names instead of cryptic system IDs, and assignment group and custom fields are included in ticket details.

**Cleaner Ticket Data**

Noisy internal metadata - such as PO numbers, MAC addresses, and repair costs - is not pulled into ticket enrichment. User-submitted form data from catalog requests (RITMs) is still included, preserving the context that matters for resolving issues accurately.

Field audit history entries such as "assigned\_to changed from X to Y" are no longer synced as conversations, so ticket threads show only meaningful activity. The SLA Status section has been removed from enriched ticket descriptions, and the Custom Fields section displays as a clean table. The redundant "Catalog Variables" section heading has also been removed - the variables table is self-explanatory and displays without the unnecessary label.

#### Outbound Sync - Resolving Tickets

When a ticket is transitioned to a Resolved or Closed state, Harmony automatically supplies the fields ServiceNow requires to accept the status change. This means status updates sync reliably without manual intervention or failed transitions.

* **Resolution Code** - automatically populated with a valid default value (for example, Solution provided when an incident is resolved or closed), with support for passing a custom code when needed.

***

### Service Catalog

#### Submitting Catalog Requests

You can create ServiceNow Service Catalog requests directly from Harmony. When a catalog item is linked to a ServiceNow Service Catalog entry, Harmony automatically validates the required catalog fields and submits the order through ServiceNow's native catalog ordering flow.

* Catalog items can be configured with a ServiceNow catalog reference and field mappings.
* Harmony handles variable validation and submission automatically.
* Submitted orders are tracked as Request Items (RITMs).

#### Live Catalog Forms

Agents now render live, dynamic forms directly from ServiceNow instead of falling back to simplified text-only versions. Harmony fetches live variables and UI policies from ServiceNow and builds the request form from them, ensuring the form always reflects the latest variables and UI policies configured in your ServiceNow instance. This includes dropdowns populated from real ServiceNow data and user-picker fields.

#### User Picker in Catalog Forms

When a catalog item includes a user selection field, a live search is available directly within the form.

* **Single user fields** display a searchable dropdown (combobox) for picking one person at a time.
* **Multi-user fields** display a multi-select control, allowing you to add several users to a single request.

Search results are pulled in real time from your connected ServiceNow instance, so user data is always current.

#### Catalog Form Validation

Validation uses ServiceNow's variable metadata directly, so form fields are checked locally before any submission is attempted - rather than creating and deleting temporary cart entries in ServiceNow. This means validation no longer causes unintended side effects in your ServiceNow environment. The improved validation covers:

* **Mandatory field checks** - required fields are flagged before submission
* **Type validation** - field values are checked against the expected data type

***

### Task Support

You can manage ServiceNow tasks directly within Harmony, enabling full support for service catalog use cases. When a ServiceNow ticket has associated tasks, Harmony recognizes and syncs them, including the following task types:

* **Service catalog tasks** (`sc_task`)
* **Change tasks** (`change_task`)
* **Incident tasks** (`incident_task`)

Tasks are automatically linked to their parent records so you can see the full context of a request in one place. Status changes flow both ways: updating a task's status in Harmony pushes the correct state back to ServiceNow (Open, In Progress, Closed).

***

### Custom Workflows

You can connect Harmony Custom Workflows to ServiceNow, enabling agents to interact with your ServiceNow instance as part of automated support processes. The following ServiceNow actions are available as workflow blocks:

* **Create ServiceNow Ticket** - automatically open a new incident in ServiceNow from within a workflow
* **Create ServiceNow Service Request** - submit a service request directly to ServiceNow's service catalog
* **API Request** - send any authenticated request to ServiceNow's REST API for more advanced or custom operations
* **Run ServiceNow Flow** - kick off existing Flow Designer automations in ServiceNow from a Harmony workflow

***

### Syncing Harmony Conversations to ServiceNow

Harmony can record your Harmony conversations in ServiceNow as interaction records, so your ServiceNow instance keeps a history of the support conversations your team handles in Harmony.

### How It Works

When a conversation in Harmony goes idle, Harmony creates an interaction record in ServiceNow with the conversation transcript and then closes it. If the conversation continues later, the new messages are added to the same interaction record.

### Enabling Conversation Sync

To enable conversation syncing with ServiceNow:

1. Navigate to **Settings > Integrations** in Harmony.
2. Open your connected **ServiceNow (OAuth)** or **ServiceNow (Service Account)** integration.
3. Turn on **Sync conversations as interactions**.
4. Click **Save Changes**.

Once enabled, Harmony will begin syncing conversations to ServiceNow interactions automatically.

### What Gets Synced

The following information is synced from Harmony conversations to ServiceNow:

* The conversation title, as the interaction's short description
* The conversation transcript, as work notes
* The channel the conversation came from (Slack, Microsoft Teams, Portal, or Web Widget)
* The requester, matched to a ServiceNow user by work email
* When the conversation was opened and closed

### Requirements

* An active ServiceNow integration configured in Harmony.
* The interaction table must be available on your ServiceNow instance. It comes with the Interaction Logging, Routing, and Queueing plugin (`com.glide.interaction`).
* Sufficient permissions in ServiceNow to create and update interaction records via the API, such as the `interaction_agent` role.

### Notes

* Sync is one-way (Harmony to ServiceNow). Changes made to the interaction record in ServiceNow are not reflected in Harmony.
* Conversations with no messages are skipped.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/integrations/it-service-management/servicenow.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
