Jira Azure DevOps Integration Guide
Learn how to set up a bi-directional Jira Azure DevOps integration in ZigiOps. Configure system instances, entity pairs, field mappings, and filters step by step.
This guide explains how to configure a bi-directional integration between Jira and Azure DevOps 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 Jira and Azure DevOps integration page on the ZigiWave website.
Overview
The Jira-Azure DevOps integration synchronizes work items and tasks between Azure DevOps and Jira automatically. When a record is created or updated in one system, ZigiOps reflects the change in the other system based on the workflow configuration.
Most common supported entity pairs:
Work Item (Task)
Task
Bi-directional
Work Item (Bug)
Bug
Bi-directional
Work Item (Story)
Story
Bi-directional
Work Item (Epic)
Epic
Bi-directional
Comment
Comment
Configurable
Attachment
Attachment
Configurable
State
Status (text transition)
Mapped with conditions
Priority
Priority
Mapped with conditions
ZigiOps supports all Azure DevOps work item types. Contact support for entity types not listed above or for more complex use cases: support@zigiwave.com.
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 below.
Jira: a dedicated integration user account with API token access and project-level permissions.
Custom fields: correlation fields must exist in both systems before configuring the workflow. See the Correlation section below.
License: the ZigiOps license must include the Jira-Azure DevOps system pair.
Step 1: Add System Instances
A system instance defines the connection between ZigiOps and a specific Azure DevOps or Jira environment. You must add one instance for each system before configuring a workflow.
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
Sign in to Azure DevOps
Sign in to your Azure DevOps organization (for example, https://dev.azure.com/{yourOrganization}).
Open Personal Access Tokens
Open your user settings, select Personal Access Tokens, and click + New Token.
Configure the token
Name your token, select the organization where you want to use it, and set an expiration date.
Set token scope
Set the token scope to Work Items (Read & Write). Limit the scope to the minimum permissions required for your integration.
Copy the token
Copy the generated token immediately. It will not be shown again after you leave the page.
Add the Azure DevOps system instance in ZigiOps:
Log in to ZigiOps
Log into your ZigiOps instance.
Open the Azure DevOps system form
Navigate to Connected Systems > Add New System > Azure DevOps.
Enter 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.
Save the system instance
Click Save.
Test the connection
Click Test Connection to verify that ZigiOps can reach the Azure DevOps API. If the test succeeds, available work item types and fields are downloaded automatically.
Required Azure DevOps permissions per action:
Create Jira Task (from Azure DevOps)
Work Items: Read
Update Jira Task (from Azure DevOps)
Work Items: Read
Update Azure DevOps Work Item
Work Items: Read, Write
Add a Jira System Instance
Log in to ZigiOps
Log into your ZigiOps instance.
Open the Jira system form
Navigate to Connected Systems > Add New System > Jira.
Enter connection parameters
Enter the following connection parameters:
Server URL: the base URL of your Jira environment (for example,
https://yourcompany.atlassian.net).Username: the Jira user account ZigiOps will use for API calls.
API Token: generated in your Atlassian account settings under Security > API tokens.
Project Key: scopes the integration to the correct Jira project.
Proxy Settings: configure if your environment requires routing traffic through a proxy.
Save the system instance
Click Save.
Test the connection
Click Test Connection to verify connectivity. Available fields and projects are downloaded automatically on success.
Required Jira permissions per action:
Create Jira Task
Browse Projects, Create Issues, Assign Issues
Update Jira Task
Edit Issues, Assign Issues, Resolve Issues, Transition Issues, Add Comments, Create Attachments
Update Azure DevOps Work Item
Browse Projects
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 Jira-Azure DevOps use cases. A template includes pre-configured field mappings for title, description, and priority, 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
Navigate to Configurator > Workflows > Add New Workflow.
Select Load from Template.
Locate the relevant Jira-Azure DevOps template. Commonly used templates include:
Azure DevOps Tasks to Jira Tasks
Jira Tasks to Azure DevOps Work Items
Click Load and adjust the configuration as needed.
Option B: Create a Custom Workflow
Navigate to Configurator > Workflows > Add New Workflow.
Select Custom Integration.
Assign a name to the workflow and proceed to configure each section as described in the steps below.
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.
Cross-team task synchronization
Work Item (Task)
Task
Bug tracking across development teams
Work Item (Bug)
Bug
Story-level planning alignment
Work Item (Story)
Story
Portfolio and program management
Work Item (Epic)
Epic
For a fully bi-directional synchronization, configure at least two actions within the workflow: one to create and update Jira records from Azure DevOps work items, and one to update Azure DevOps work items when Jira records change.
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:
Jira custom field (for example, "Azure DevOps ID"): stores the Azure DevOps work item ID of the linked record.
Azure DevOps custom field (for example, "Jira Reference"): stores the Jira issue key (for example,
OPS-4512).
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 supports one-to-one correlation by default. Each Jira record maps to exactly one Azure DevOps work item. This prevents duplicate creation even if an event is processed more than once.
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
Title
summary
Direct text mapping
Description
description
Direct text mapping
Priority
priority
Requires conditional mapping if label names differ
State
status (text transition)
Requires conditional mapping with Jira transition IDs
Comment
comment.body
Configure via Related Records. Apply author filter to prevent echo loops.
Assigned To
assignee
Map based on team structure
ID (Work Item ID)
Custom field: Azure DevOps ID
Used for correlation. Not displayed to end users.
Work Item ID
Custom field: ADO Reference
Human-readable cross-reference
State Mapping
Azure DevOps uses a text-based State field, with values that vary by work item type and process template (Agile, Scrum, CMMI). Jira uses a Status field governed by workflow transitions. These must be mapped conditionally, not as a direct value copy.
New
To Do
Direct mapping
Active
In Progress
Direct mapping
Resolved
In Review / Done
Map based on your Jira workflow
Closed
Done
Terminal state. Do not reopen via integration.
Removed
Cancelled
Map to a custom Jira status if available
Azure DevOps state names differ by process template (Agile, Scrum, or CMMI). Verify the exact state labels used in your Azure DevOps project before configuring these mappings. When mapping to Jira Done, use the Jira transition ID rather than setting the status field directly to ensure workflow validators and required fields are respected.
Priority Mapping
Azure DevOps uses a numeric priority field (1 to 4, where 1 is highest). Jira uses text-based priorities. Map values conditionally to ensure business impact is accurately represented.
1
Highest
Direct conditional mapping
2
High
Direct conditional mapping
3
Medium
Direct conditional mapping
4
Low
Direct conditional mapping
Verify the exact priority label names used in your Jira instance before configuring these mappings. Label names vary between Jira Cloud and Jira Data Center, and may differ per project.
Comment and Attachment Synchronization
Both Azure DevOps and Jira support comments and attachments. Syncing all comments without filtering may create echo loops if the integration user's own writes are collected on the next cycle.
Recommended comment and attachment mapping:
Azure DevOps Comment to Jira Comment: sync comments relevant to the Jira team.
Jira Comment to Azure DevOps Comment: map updates back to keep the Azure DevOps team informed.
Author filter: exclude comments authored by the integration user to prevent echo loops.
Last Time expression: use
{lasttimecomment}to collect only comments created after the last successful run.Attachments: configure attachment sync via the Related Records section. Apply the same Last Time filter to avoid re-syncing existing attachments.
Configure comment and attachment 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.
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, work item 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.
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 Jira-Azure DevOps 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.Environment scope: exclude work items from test or sandbox Azure DevOps projects.
Priority threshold: sync Priority 1 and Priority 2 work items in real time; batch-sync lower priorities.
Author exclusion: filter out comments authored by the integration user to prevent duplicate comment loops.
Work item type scope: optionally restrict collection to specific work item types (for example, only sync Bugs and Tasks, not 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.
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.
Date and Time Format
Converts epoch timestamps to a human-readable string
Convert Azure DevOps System.CreatedDate to a readable format for a Jira custom field
First N Characters
Extracts the first N characters of a field value
Truncate long Azure DevOps titles to fit Jira's 255-character summary limit
Pattern (RegEx)
Extracts a value matching a regular expression. Group 1 is returned if a capturing group is defined.
Extract a sprint name or area path component from an Azure DevOps field value
Replace Text
Replaces a specific substring with another value
Replace internal team prefixes with display names before syncing to Jira
Replace Pattern (RegEx)
Replaces all matches of a RegEx pattern
Remove HTML tags from Azure DevOps rich-text description fields
Build Array
Combines multiple values into a comma-separated array
Aggregate multiple Azure DevOps tags into a Jira label 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
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.
To activate the workflow:
Run a test
Run the workflow in test mode against a non-production record.
Verify the result
Verify that the target record is created with the correct field values.
Check the Activity Log
Check the Activity Log for any errors or unexpected field values.
Activate the workflow
Once results are confirmed, set the workflow status to Active.
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.
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
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 comment and attachment sync rules
Internal notes may be exposed to unauthorized teams if filters are missing
Use conditional mapping and author filters to enforce data classification
Troubleshooting
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 Jira or Azure DevOps
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
Azure DevOps work item fails to update when Jira changes
The correlation field in Azure DevOps is empty or not correctly mapped
Verify that the Respond Mapping writes the Jira issue key to the Azure DevOps correlation field after record creation
Jira status does not update after an Azure DevOps state change
The mapping is setting the status field directly rather than using a Jira workflow transition ID
Replace the status field value with the correct Jira transition ID in the mapping configuration
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
Workflow saves but fails to activate
A mandatory configuration field is missing, or the license does not include the Jira-Azure DevOps 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
Related Resources
Last updated
Was this helpful?