/
How to prevent duplicate Epics in Azure DevOps when syncing with TFS4JIRA

How to prevent duplicate Epics in Azure DevOps when syncing with TFS4JIRA

Summary

This article addresses an issue in TFS4JIRA Self-Hosted where duplicate work items (specifically Epics) are created in Azure DevOps during synchronization with Jira Data Center.

This occurs because the custom field used to store the Azure DevOps work item ID is missing from the Jira screen scheme, preventing the synchronizer from linking the existing items.

Environment

  • Product: TFS4JIRA Self-Hosted

  • Platform: Jira Data Center

  • Integrations: Azure DevOps (On-premise)

  • App Version: v10.1.3 (or similar versions after migration)

Problem

Whenever a child issue (such as a Story) is created under an Epic in Jira, the synchronizer triggers a sync for the Epic. However, instead of updating the existing Epic in Azure DevOps, a duplicate Epic is created.

The following symptoms are typically observed:

  • Duplicate Epics in Azure DevOps share the same Jira issue key.

  • The Jira Epic does not show the associated Azure DevOps work item ID in the designated custom field (e.g., TFSWorkItemId).

  • Error logs may indicate issues accessing specific custom fields.

Cause

The duplication occurs because the synchronizer cannot find or update the mandatory custom field on the Jira issue that stores the Azure DevOps work item ID. If this field is missing from the Screen associated with the issue's current Screen Scheme, the app cannot record the ID.
Consequently, during the next sync cycle, the app assumes the Jira issue is not yet linked and creates a new work item in Azure DevOps.

This often happens after a Jira migration or app upgrade if screen configurations are not preserved or if the field was accidentally removed from the screen.

Solution

To resolve the duplication, ensure that the custom field used by TFS4JIRA to store the work item ID is correctly configured and visible on the relevant Jira screens.

  1. Identify the custom field used for the Azure DevOps work item ID (e.g., TFSWorkItemId).

  2. Navigate to Administration > Issues > Screens.

  3. Locate the screen(s) used by the affected project and issue type (Epic).

  4. Click Configure for the relevant screen.

  5. Check if the custom field (e.g., TFSWorkItemId) is present in the list of fields.

  6. If the field is missing, add it using the Select Field dropdown at the bottom of the page.

  7. Verify that the field is not hidden in the Field Configuration linked to the project.

  8. Perform a manual sync or create a new child issue to verify that the Epic now correctly links to the existing Azure DevOps work item instead of creating a duplicate.