> 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. 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 that works across all ServiceNow instances. To set up the connection: 1. Open the ServiceNow integration settings and start a new connection. 2. Enter your ServiceNow **instance URL**. 3. Enter your service account **username** and **password**. 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 automatically checks whether your service account has the three roles it needs to operate correctly: * `itil` * `catalog_admin` * `sn_interaction.admin` If any roles are missing, a warning banner appears in the integration settings showing exactly which roles are present and which need to be added. A direct link to the ServiceNow role assignment page is included so you can resolve the issue quickly. #### OAuth You can also connect using OAuth. The setup wizard handles OAuth app creation automatically as part of the connection flow. * A **Setup Outbound App** step in the integration wizard dynamically creates or updates the Descope outbound app for your ServiceNow instance during OAuth setup. Each tenant and instance gets its own dedicated app configuration - no static provisioning required. * OAuth callbacks are automatically routed to the correct provider during the connection flow. **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. The following capabilities are checked during connection: * **Inbound ticket sync** - syncing tickets from ServiceNow into Harmony * **Outbound ticket sync** - pushing updates from Harmony back to ServiceNow * **Catalog** - accessing your ServiceNow service catalog 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. **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: Solved remotely, Known error, Solved by workaround, Duplicate, Not reproducible, Solved by caller), 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 Ticket** - automatically open a new incident in ServiceNow from within a workflow * **Create Service Request** - submit a service request directly to ServiceNow's service catalog * **Make Authenticated API Calls** - send any authenticated request to ServiceNow's REST API for more advanced or custom operations * **Trigger Flow Designer Flows** - kick off existing Flow Designer automations in ServiceNow from a Harmony workflow *** ### Syncing Harmony Conversations to ServiceNow Harmony now supports bidirectional conversation sync with ServiceNow. When a user opens a conversation in Harmony that originated from or is linked to a ServiceNow incident, Harmony can automatically push updates back to ServiceNow - keeping both systems aligned without manual effort from your team. ### How It Works When a conversation is created or updated in Harmony and a matching ServiceNow incident exists, Harmony syncs the relevant data across. This includes conversation status changes, notes, and resolution updates. The sync is triggered automatically based on your integration settings, so your ServiceNow records stay current as your team works in Harmony. ### Enabling Conversation Sync To enable conversation syncing with ServiceNow: 1. Navigate to **Settings > Integrations** in Harmony. 2. Open your existing **ServiceNow** integration. 3. Locate the **Conversation Sync** option and enable it. 4. Save your changes. Once enabled, Harmony will begin syncing conversations to the corresponding ServiceNow incidents automatically. ### What Gets Synced The following information is synced from Harmony conversations to ServiceNow: * Conversation status and resolution state * Agent notes and internal updates * Customer messages and replies * Conversation closure and re-opening events ### Requirements * An active ServiceNow integration configured in Harmony. * Sufficient permissions in ServiceNow to update incidents via the API. * ServiceNow incidents must be linked to the corresponding Harmony conversations (this can happen automatically during ticket import or manually via the conversation detail view). ### Notes * Sync is unidirectional by default (Harmony to ServiceNow). Updates made directly in ServiceNow are not automatically reflected in Harmony unless the standard ticket sync is also enabled. * If a matching ServiceNow incident cannot be found for a conversation, the sync is skipped and logged for review. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.harmony.io/integrations/it-service-management/servicenow.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.