> For the complete documentation index, see [llms.txt](https://docs.zigiwave.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zigiwave.com/integration-guides/azure-devops-servicenow-integration-guide.md). # Azure DevOps ServiceNow Integration Guide This guide explains how to configure a bi-directional integration between Azure DevOps and ServiceNow using ZigiOps. It covers adding system instances, selecting entity pairs, configuring correlation, building field mappings, applying filters, and testing the workflow. No scripting or coding is required at any stage. For a full overview of the sync capabilities between the two platforms, see the [Azure DevOps and ServiceNow integration page](https://www.zigiwave.com/integrations/servicenow-azure-devops-integration) on the ZigiWave website. *** ### Overview The Azure DevOps-ServiceNow integration synchronizes work items and ITSM records automatically. When a record is created or updated in one system, ZigiOps reflects the change in the other system based on the workflow configuration. This eliminates manual handoffs between development and operations teams, reduces resolution times, and keeps both teams aligned throughout the full incident and development lifecycle. {% embed url="" %} **Most common supported entity pairs:** | Azure DevOps Entity | ServiceNow Entity | Sync Direction | | ----------------------- | ------------------------------ | ---------------------- | | Work Item (Bug / Issue) | Incident | Bi-directional | | Work Item (Task) | Problem | Bi-directional | | Work Item (Task) | Change Request | Bi-directional | | Comment | Work Note / Additional Comment | Configurable | | Attachment | Attachment | Configurable | | State | State (numeric) | Mapped with conditions | | Priority (numeric 1-4) | Priority (numeric 1-4) | Mapped with conditions | > **Note:** ZigiOps supports all Azure DevOps work item types and all ServiceNow entities. Contact support for entities not listed above or for more complex use cases: . *** ### Prerequisites Before configuring this integration, confirm that the following requirements are met: * **ZigiOps instance:** installed and running. See the Installation guide. * **Azure DevOps:** a user account with a Personal Access Token (PAT) and the required work item permissions. See the [Azure DevOps system instance section](#add-an-azure-devops-system-instance) below. * **ServiceNow:** a dedicated integration user with read and write permissions on the Incident, Problem, or Change Request tables. See the [ServiceNow system instance section](#add-a-servicenow-system-instance) below. * **Custom fields:** correlation fields must exist in both systems before configuring the workflow. See the [Correlation section](#step-4-configure-correlation) below. * **License:** the ZigiOps license must include the Azure DevOps-ServiceNow system pair. *** ### Step 1: Add System Instances A system instance defines the connection between ZigiOps and a specific Azure DevOps or ServiceNow environment. You must add one instance for each system before configuring a workflow. #### Add a ServiceNow System Instance {% stepper %} {% step %} **Log into ZigiOps and open the ServiceNow connection form** * Log into your ZigiOps instance. * Navigate to **Connected Systems** > **Add New System** > **ServiceNow**. {% endstep %} {% step %} **Enter the connection parameters** Enter the following connection parameters: * **Server URL:** the base URL of your ServiceNow instance (for example, `https://yourinstance.service-now.com`). * **Username:** the ServiceNow integration user account. * **Password:** the password for the integration user. * **Proxy Settings:** configure if your environment requires routing traffic through a proxy. {% endstep %} {% step %} **Save and test the connection** * Click **Save** * Click **Test Connection** to verify that ZigiOps can reach the ServiceNow API. If the test succeeds, available tables and fields are downloaded automatically. {% endstep %} {% endstepper %}

ZigiOps UI - Adding ServiceNow as a Connected System.

> **Note:** The ServiceNow integration user must have read and write permissions on the `incident`, `problem`, and `change_request` tables, as well as permission to read and write `sys_journal_field` entries for work note synchronization. #### Add an Azure DevOps System Instance Azure DevOps authenticates via a Personal Access Token (PAT). Before adding the system instance in ZigiOps, generate a PAT in your Azure DevOps organization. **How to Create a Personal Access Token in Azure DevOps** {% stepper %} {% step %} **Sign in and open Personal Access Tokens** * Sign in to your Azure DevOps organization (for example, `https://dev.azure.com/{yourOrganization}`). * Open your user settings, select **Personal Access Tokens**, and click **+ New Token**. {% endstep %} {% step %} **Configure the token** * Name your token, select the organization where you want to use it, and set an expiration date. * Set the token scope to **Work Items (Read & Write)**. Limit the scope to the minimum permissions required for your integration. {% endstep %} {% step %} **Copy the token** * Copy the generated token immediately. It will not be shown again after you leave the page. {% endstep %} {% endstepper %} **Add the Azure DevOps system instance in ZigiOps:** {% stepper %} {% step %} **Open the Azure DevOps system form** * Log into your ZigiOps instance. * Navigate to **Connected Systems** > **Add New System** > **Azure DevOps**. {% endstep %} {% step %} **Enter the connection parameters** Enter the following connection parameters: * **Server URL:** the base URL of your Azure DevOps environment (for example, `https://dev.azure.com`). * **Instance Type:** select the type of your Azure DevOps instance (Cloud or Server). * **Organization / Collection:** the name of your Azure DevOps organization or collection. * **Username:** the Azure DevOps user account ZigiOps will use for API calls. * **Private Access Token:** the PAT generated in the steps above. * **Proxy Settings:** configure if your environment requires routing traffic through a proxy. {% endstep %} {% step %} **Save and test the connection** * Click **Save**. * Click **Test Connection** to verify connectivity. Available work item types and fields are downloaded automatically on success. {% endstep %} {% endstepper %}

ZigiOps UI - Adding Azure DevOps as a Connected System.

**Required permissions per action:** | Action | Azure DevOps Permission | ServiceNow Permission | | --------------------------------------------- | ----------------------- | ---------------------- | | Create ServiceNow record from Azure DevOps | Work Items: Read | Create on target table | | Update ServiceNow record from Azure DevOps | Work Items: Read | Write on target table | | Create Azure DevOps work item from ServiceNow | Work Items: Read, Write | Read on source table | | Update Azure DevOps work item from ServiceNow | Work Items: Read, Write | Read on source table | > **Note:** If the Test Connection fails for either system, verify that the integration user has the required API permissions and that the instance URL does not include a trailing slash. *** ### Step 2: Create or Load a Workflow A workflow defines the complete configuration for your integration, including the entity pair, triggers, field mappings, filters, and correlation logic. ZigiOps provides pre-built workflow templates for the most common Azure DevOps-ServiceNow use cases. A template includes pre-configured field mappings for title or description, priority, and state, as well as basic correlation and trigger settings. You can load a template and adjust it to match your environment, or create a custom workflow from scratch. #### Option A: Load a Workflow Template {% stepper %} {% step %} **Open the workflow template selection** * Navigate to **Configurator** > **Workflows** > **Add New Workflow**. * Select **Load from Template**. {% endstep %} {% step %} **Choose and load the template** Locate the relevant Azure DevOps-ServiceNow template. Commonly used templates include: * Azure DevOps Work Items to ServiceNow Incidents * ServiceNow Incidents to Azure DevOps Issues Click **Load** and adjust the configuration as needed.

ZigiOps UI - Workflow template selection screen.

{% endstep %} {% endstepper %} #### Option B: Create a Custom Workflow {% stepper %} {% step %} **Open the workflow creation screen** * Navigate to **Configurator** > **Workflows** > **Add New Workflow**. * Select **Custom Integration**. {% endstep %} {% step %} **Name and continue** * Assign a name to the workflow and proceed to configure each section as described in the steps below. {% endstep %} {% endstepper %} *** ### Step 3: Select the Entity Pair The entity pair defines which record types in each system will be synchronized. Select the combination that matches your use case. | Use Case | Azure DevOps Entity | ServiceNow Entity | | ------------------------------------------------------ | ----------------------- | ----------------- | | Escalating a dev issue to ITSM for incident tracking | Work Item (Bug / Issue) | Incident | | Syncing root cause analysis across teams | Work Item (Task) | Problem | | Coordinating production deployments with ITSM approval | Work Item (Task) | Change Request | For a fully bi-directional synchronization, configure at least two actions within the workflow: one to create and update ServiceNow records from Azure DevOps work items, and one to update Azure DevOps work items when ServiceNow records change.

ZigiOps UI - Entity pair selection screen.

*** ### Step 4: Configure Correlation Correlation is the mechanism ZigiOps uses to match existing records across systems during update cycles. It stores only unique identifiers, not business data. Without correlation, every sync cycle would create new records rather than updating existing ones. You define which field in each system stores the unique identifier of its counterpart. Common patterns are: * **ServiceNow field (for example, `correlation_id` or a custom field "Azure DevOps ID"):** stores the Azure DevOps work item ID of the linked record. * **Azure DevOps custom field (for example, "ServiceNow Reference"):** stores the ServiceNow incident number (for example, `INC0012345`) or `sys_id`. Create the required custom fields in each system **before** configuring correlation in ZigiOps. Once the fields exist, map them in the Correlation section of the workflow.

ZigiOps UI - Correlation configuration screen.

> **Note:** ZigiOps supports one-to-one correlation by default. Each Azure DevOps work item maps to exactly one ServiceNow record. This prevents duplicate creation even if an event is processed more than once. If the correlation key is missing or modified, ZigiOps can re-establish or update correlation safely, preventing data drift. *** ### Step 5: Configure Field Mappings Field mappings define which fields are synchronized between the two systems and how their values are transformed. Mappings are configured separately for each action direction. #### Minimum Required Field Mappings | Azure DevOps Field | ServiceNow Field | Notes | | -------------------- | ------------------------------------ | ----------------------------------------------------------------------------------- | | `Title` | `short_description` | Direct text mapping | | `Description` | `description` | Direct text mapping | | `Priority` (numeric) | `priority` (numeric) | Requires conditional mapping; both systems use numeric values but scales may differ | | `State` | `state` (numeric) | Requires conditional mapping with ServiceNow state machine values | | `Comment` | `work_notes` | Configure via Related Records. Apply author filter to prevent echo loops. | | `Assigned To` | `assigned_to` | Map based on team structure | | `ID` (Work Item ID) | `correlation_id` or custom field | Used for correlation. Not displayed to end users. | | `Work Item ID` | Custom field: Azure DevOps Reference | Human-readable cross-reference |

ZigiOps UI - Field Mapping table.

#### State Mapping Azure DevOps uses text-based state values (which vary by process template). ServiceNow uses a numeric State field governed by an ITIL-compliant state machine. These must be mapped conditionally in both directions. | Azure DevOps State | ServiceNow State (numeric) | ServiceNow Label | Notes | | ------------------ | -------------------------- | ---------------- | --------------------------------------------------------------- | | New | 1 | New | Direct mapping | | Active | 2 | In Progress | Direct mapping | | Resolved | 6 | Resolved | Send `close_code` and `close_notes` when mapping to Resolved | | Closed | 7 | Closed | Terminal state. Do not reopen via integration. | | Removed | 8 | Cancelled | Map if Cancelled state is available in your ServiceNow workflow | > **Note:** Closing a ServiceNow incident requires both `close_code` and `close_notes`. If these fields are not included in the mapping when the Azure DevOps work item state is set to Resolved or Closed, the ServiceNow API call will fail. Add a conditional mapping: when Azure DevOps State = Resolved, send `close_code` = `'Closed/Resolved by Caller'` and `close_notes` = `'Resolved by Azure DevOps integration'`.

ZigiOps UI - State conditional mapping.

#### Priority Mapping Azure DevOps uses a numeric priority field (1 to 4, where 1 is highest). ServiceNow also uses a numeric priority field (1 to 4, where 1 is Critical). The scales align, but ServiceNow derives priority from a combination of Impact and Urgency. Verify the priority matrix in your ServiceNow instance and map values conditionally. | Azure DevOps Priority | ServiceNow Priority (numeric) | ServiceNow Label | Notes | | --------------------- | ----------------------------- | ---------------- | -------------------------- | | 1 | 1 | Critical | Direct conditional mapping | | 2 | 2 | High | Direct conditional mapping | | 3 | 3 | Moderate | Direct conditional mapping | | 4 | 4 | Low | Direct conditional mapping | #### Comment and Work Note Synchronization ServiceNow distinguishes between Work Notes (internal) and Additional Comments (customer-visible). Azure DevOps uses a single Comment entity. Syncing all notes without filtering may expose internal ITSM information to development teams, or vice versa. Recommended comment mapping: * **ServiceNow Work Note to Azure DevOps Comment:** sync only work notes that are relevant to the development team. * **Azure DevOps Comment to ServiceNow Work Note:** map developer updates back as internal work notes. * **Author filter:** exclude comments authored by the integration user to prevent echo loops. * **Last Time expression:** use `{lasttimecomment}` to collect only entries created after the last successful run. Configure comment synchronization via the Related Records section of the field mapping configuration in ZigiOps. *** ### Step 6: Configure Triggers Triggers define when ZigiOps collects data from the source system. ZigiOps supports two trigger types, which can be used together for the most reliable coverage. | Trigger Type | Mechanism | Recommended Use | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Poller | ZigiOps queries the source system API on a configurable schedule (default: every 1 minute). | SLA monitoring, controlled sync cycles, systems without webhook support | | Web Listener | ZigiOps registers an HTTP endpoint and waits for the source system to push data via webhook. Activated when the action is enabled. | Real-time status updates, incident creation alerts, near-instant synchronization | Using both trigger types in combination is the recommended approach for production deployments. The Poller provides complete coverage; the Web Listener reduces latency for time-critical events. For critical Priority 1 incidents, configure a Web Listener trigger to minimize response time.

ZigiOps UI - Trigger configuration.

*** ### Step 7: Add Filters and Conditions Filters control which records are collected and when. Without proper filtering, the integration may process records that should be excluded or miss records that need to be synced. Common filter configurations for Azure DevOps-ServiceNow workflows: * **Last Time expression:** collect only records created or updated since the previous run. Use the `{lasttime}` expression in the filter condition. * **Last changelog expression:** use `{lasttimechangelog}` to collect change history entries created after the last run. * **Last comment expression:** use `{lasttimecomment}` to collect only comments created after the last successful run. * **Priority threshold:** sync Priority 1 and Priority 2 records in real time; batch-sync lower priorities. * **Author exclusion:** filter out comments authored by the integration user to prevent duplicate comment loops. * **Assignment group scope:** restrict ServiceNow collection to incidents assigned to specific groups that require development involvement. * **Work item type scope:** optionally restrict Azure DevOps collection to specific work item types (for example, only sync Bugs, not Tasks or Epics). ZigiOps supports AND and OR logic, with operators including: is, is not, is one of, is not one of, is empty, is not empty, contains, does not contain, less than, greater than, and equals. Conditions can be applied to any field available from the connected system.

ZigiOps UI - Filter and Condition Builder.

*** ### Step 8: Use Expressions for Data Transformation (Optional) Expressions apply transformations to field values after data is collected from the source and before it is delivered to the target. They are configured in the Source and Target tabs of the workflow action and do not require any scripting. | Expression | What It Does | Azure DevOps-ServiceNow Example | | ----------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Date and Time Format | Converts epoch timestamps to a human-readable string | Convert ServiceNow `sys_created_on` to a readable format for an Azure DevOps custom field | | First N Characters | Extracts the first N characters of a field value | Truncate long ServiceNow descriptions to fit Azure DevOps title character limits | | Pattern (RegEx) | Extracts a value matching a regular expression. Group 1 is returned if a capturing group is defined. | Extract an environment name or CI reference from a ServiceNow incident description | | Replace Text | Replaces a specific substring with another value | Replace internal assignment group codes with display names before syncing to Azure DevOps | | Replace Pattern (RegEx) | Replaces all matches of a RegEx pattern | Remove HTML tags from ServiceNow rich-text description fields | | Build Array | Combines multiple values into a comma-separated array | Aggregate multiple ServiceNow categories into an Azure DevOps tag array | | Last Time | Stores the timestamp of the last successful run; auto-increments on each execution | Collect only records updated after `{lasttime}` to prevent duplication | | To Lower Case / To Upper Case | Normalizes text casing | Align state or priority values that differ only in casing between systems |

ZigiOps UI - Expression configuration.

*** ### Step 9: Test and Activate the Workflow Before activating the workflow in production, test each action individually using the built-in troubleshooting tools. #### Testing Tools Available in ZigiOps * **Real-time operation logs:** show every record collected, processed, and delivered. * **Payload inspector:** displays the raw data sent to and received from each system, useful for debugging field mapping issues. * **HTTP request and response data:** provides API-level details for connectivity troubleshooting. * **Error classification:** distinguishes between mapping errors, connectivity issues, and API rejections. **Pre-activation checklist:** * Confirm Azure DevOps PAT permissions include all required scopes for work items, comments, and attachments. * Verify ServiceNow integration user roles include the necessary permissions for the target tables. * Ensure all required correlation fields exist in both systems and are accessible via API. * Validate state mappings across all possible transitions, including terminal states. * Test end-to-end synchronization including comments, attachments, state changes, and closures. **To activate the workflow:** {% stepper %} {% step %} **Run a test** * Run the workflow in **test mode** against a non-production record. {% endstep %} {% step %} **Verify the result** * Verify that the target record is created with the correct field values. * Check the **Activity Log** for any errors or unexpected field values. {% endstep %} {% step %} **Activate the workflow** * Once results are confirmed, set the workflow status to **Active**. {% endstep %} {% endstepper %}

ZigiOps Dashboard - Monitoring view.

*** ### Advanced: Governance and Reliability The following practices apply to production deployments and regulated environments. #### Idempotency via Correlation Lookup Before any write operation, ZigiOps checks whether a correlated record already exists in the target system. If one exists, it performs an update. If none exists, it creates a new record. This two-path logic prevents duplicate records when events are reprocessed after a failure or retry. If the correlation key is missing or modified, ZigiOps can re-establish correlation automatically based on configurable matching rules. #### Retry Logic Failed operations caused by transient API errors (rate limits, maintenance windows, network interruptions) are retried automatically. ZigiOps distinguishes between transient failures (retried) and permanent failures (logged and surfaced in the Activity Log). Retries do not create duplicate records due to the correlation lookup described above. #### Governance Recommendations | Practice | Why It Matters | How ZigiOps Supports It | | ----------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | | Define integration ownership | Someone must be accountable for mapping logic and change testing | ZigiOps provides user-level access control and admin roles | | Test changes in staging first | Untested mapping changes can silently misbehave in production | ZigiOps supports multiple environments; test before activating | | Export and version integration templates | Integration configurations should be treated like production code | Export templates and store in a version control system | | Monitor operational health continuously | Silent failures are as damaging as loud ones | ZigiOps provides dashboards with real-time error tracking and operation metrics | | Audit Work Note and attachment sync rules | Internal ITSM notes may be exposed to development teams if filters are missing | Use conditional mapping and author filters to enforce data classification | *** ### Troubleshooting | Issue | Likely Cause | Resolution | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Fields are missing from mapping suggestions | The system schema was not refreshed after new fields were added | Navigate to Connected Systems, select the system, and click Save to re-download the schema | | Duplicate comments appear in Azure DevOps or ServiceNow | Integration user exclusion filter is missing, or `{lasttimecomment}` expression is not configured | Add a trigger condition excluding the integration user as comment author; configure the `{lasttimecomment}` filter | | ServiceNow incident fails to resolve when Azure DevOps work item closes | `close_code` and `close_notes` are required by ServiceNow but are not included in the mapping | Add conditional mappings: send `close_code` and `close_notes` only when Azure DevOps State = Resolved or Closed | | Azure DevOps work item state does not update after a ServiceNow change | The state transition is not permitted by the Azure DevOps workflow from the current state | Configure intermediate state transitions in the ZigiOps workflow mapping, or adjust Azure DevOps workflow rules to allow the required transitions | | ServiceNow record fails to update when Azure DevOps changes | The correlation field in ServiceNow is empty or not correctly mapped | Verify that the Respond Mapping writes the Azure DevOps work item ID to the ServiceNow correlation field after record creation | | Workflow saves but fails to activate | A mandatory configuration field is missing, or the license does not include the Azure DevOps-ServiceNow pair | Review the error message in the UI; verify the license status under Admin > About | | PAT authentication fails on Azure DevOps connection | The Personal Access Token has expired, or the token scope does not include Work Items (Read & Write) | Generate a new PAT in Azure DevOps with the correct scopes and update the system instance in ZigiOps | | State values do not match between systems | Azure DevOps state names differ by process template (Agile, Scrum, CMMI) | Verify the exact state label names in your Azure DevOps project and update conditional mappings accordingly | *** ### Related Resources * [Integration Catalog - Azure DevOps ServiceNow Integrations](/integration-catalog/servicenow-azure-devops-integration.md) * [Building Integrations - Data Mapping Fundamentals](/design-and-mappings/data-mapping-fundamentals.md) * [Building Integrations - Filters and Conditions](/design-and-mappings/filters-and-conditions.md) * [Building Integrations - Transformations and Expressions](/design-and-mappings/transformations-and-expressions.md) * [Building Integrations - Comments and Attachment Sync](/design-and-mappings/attachments-and-comments.md) * [Troubleshooting - Mapping Issues](/operations-and-monitoring/troubleshooting.md) * [ZigiOps System Requirements](/integration-platform/system-requirements.md) --- # 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.zigiwave.com/integration-guides/azure-devops-servicenow-integration-guide.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.