> 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/jira-azure-devops-integration-guide.md). # Jira Azure DevOps Integration Guide 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](https://www.zigiwave.com/integrations/jira-azure-devops-integration) 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. {% embed url="" %} **Most common supported entity pairs:** | Azure DevOps Entity | Jira Entity | Sync Direction | | ------------------- | ------------------------ | ---------------------- | | 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 | {% hint style="info" %} ZigiOps supports all Azure DevOps work item types. Contact support for entity types not listed above or for more complex use cases: . {% endhint %} *** ### 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. * **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](#step-4-configure-correlation) 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** {% stepper %} {% step %} **Sign in to Azure DevOps** Sign in to your Azure DevOps organization (for example, `https://dev.azure.com/{yourOrganization}`). {% endstep %} {% step %} **Open Personal Access Tokens** 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. {% endstep %} {% step %} **Set token scope** 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 %} **Log in to ZigiOps** Log into your ZigiOps instance. {% endstep %} {% step %} **Open the Azure DevOps system form** Navigate to **Connected Systems** > **Add New System** > **Azure DevOps**. {% endstep %} {% step %} **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. {% endstep %} {% step %} **Save the system instance** Click **Save**. {% endstep %} {% step %} **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. {% endstep %} {% endstepper %}

ZigiOps UI - Adding Azure DevOps as a Connected System.

**Required Azure DevOps permissions per action:** | Action | Required Permission | | ------------------------------------ | ----------------------- | | 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 {% stepper %} {% step %} **Log in to ZigiOps** Log into your ZigiOps instance. {% endstep %} {% step %} **Open the Jira system form** Navigate to **Connected Systems** > **Add New System** > **Jira**. {% endstep %} {% step %} **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. {% endstep %} {% step %} **Save the system instance** Click **Save**. {% endstep %} {% step %} **Test the connection** Click **Test Connection** to verify connectivity. Available fields and projects are downloaded automatically on success. {% endstep %} {% endstepper %}

ZigiOps UI - Adding Jira as a Connected System.

**Required Jira permissions per action:** | Action | Required Permissions | | ----------------------------- | ----------------------------------------------------------------------------------------------- | | 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 | {% hint style="info" %} 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. {% endhint %} *** ### 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 1. Navigate to **Configurator** > **Workflows** > **Add New Workflow**. 2. Select **Load from Template**. 3. Locate the relevant Jira-Azure DevOps template. Commonly used templates include: * Azure DevOps Tasks to Jira Tasks * Jira Tasks to Azure DevOps Work Items 4. Click **Load** and adjust the configuration as needed.

ZigiOps UI - Workflow template selection screen.

#### Option B: Create a Custom Workflow 1. Navigate to **Configurator** > **Workflows** > **Add New Workflow**. 2. Select **Custom Integration**. 3. 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. | Use Case | Azure DevOps Entity | Jira Entity | | ------------------------------------- | ------------------- | ----------- | | 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.

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: * **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 UI - Correlation configuration screen.

{% hint style="info" %} 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. {% endhint %} *** ### 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 | Jira Field | Notes | | ------------------- | ----------------------------- | ------------------------------------------------------------------------- | | `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 |

ZigiOps UI - Field Mapping table.

#### 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. | Azure DevOps State (Agile / Scrum) | Jira Status | Notes | | ---------------------------------- | ---------------- | ---------------------------------------------- | | 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 | {% hint style="info" %} 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. {% endhint %}

ZigiOps UI - State conditional mapping.

#### 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. | Azure DevOps Priority | Jira Priority | Notes | | --------------------- | ------------- | -------------------------- | | 1 | Highest | Direct conditional mapping | | 2 | High | Direct conditional mapping | | 3 | Medium | Direct conditional mapping | | 4 | Low | Direct conditional mapping | {% hint style="info" %} 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. {% endhint %} #### 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. | 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, 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.

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 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.

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 | Jira-Azure DevOps Example | | ----------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | 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 |

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. **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. {% endstep %} {% step %} **Check the Activity Log** 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. #### 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 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 | 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 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 * [Integration Catalog - Azure DevOps Jira Integrations](/integration-catalog/jira-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/jira-azure-devops-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.