/
Configure multiple TFS4JIRA profiles for the same Jira project

Configure multiple TFS4JIRA profiles for the same Jira project

This article provides a generic, reusable guide for configuring multiple TFS4JIRA Cloud Native synchronization profiles that target the same Jira project while handling different item types or scopes, for example, epics, stories, or bugs. The article avoids customer-specific details and can be applied in any environment. It includes the design rationale, step-by-step setup, validation, and troubleshooting, as well as important limitations and restrictions to consider before rollout.

When to use multiple profiles for one Jira project

Using separate profiles to synchronize distinct item types or scopes into the same Jira project helps you:

  • Isolate mappings and workflows for each item type, for example, States in ADO, or bugs and stories in Jira.

  • Apply different filters, directions, and field mappings without side effects between item types.

  • Debug faster: failures in one profile don’t block other item types.

This is a generic guidance article intended for any customer environment. It deliberately avoids environment-specific IDs, projects, users, and configurations. Adapt item types, filters, and mappings to your own Jira and Azure DevOps setup.

Reference example architecture

Assume a single Jira project, DEV, and one Azure DevOps project. In this example, two Cloud Native profiles are created:

  • Profile A – Epics only:

    • One-way or two-way sync for ADO Epics ↔ Jira Epics

    • Dedicated field and status mappings

    • A hierarchy is enabled so that Stories link to Epics.

  • Profile B – Stories and Bugs:

    • Two-way sync for ADO Stories and Bugs to Jira Stories and Bugs

    • Status mappings tuned for team boards

    • Separate filters to avoid Epics.

Step-by-step configuration

1) Create Profile A – Epics

  1. Create a new synchronization profile (Cloud Native) and give it a meaningful name, for example:

    1. DEV – Epics (CN)

  2. Connections: Select your Jira Cloud and ADO connections used for this program.

  3. Item Types: Map ADO Epic ↔ Jira Epic only. Exclude other types.

  4. Filters / Scope: Add a filter to include only Epics on both sides. This avoids cross-picking Stories/Bugs. For example:

    1. ADO WIQL or area path filter

    2. Jira JQL targeting issuetype=Epic in project=DEV).

  5. Field Mappings: Map the ADO Title to Jira fields used by Epics. If you use Jira’s Epic Name, map ADO Title → Jira Epic Name and ADO Title → Jira Summary as needed. Ensure the Epic name mapping persists after UI changes by saving and rechecking.

  6. Workflow / Status Mapping: Map ADO Epic states to Jira Epic statuses. Keep transitions simple; only reflect real transitions supported by Jira workflows.

  7. Hierarchy: Enable hierarchy and verify the Jira parent link type for Epic → Story relationships is set correctly. See internal notes below if a misconfiguration causes long initial runs.

2) Create Profile B – Stories and Bugs

  1. Create another profile or clone Profile A and make the applicable edits. Name it:

    1. DEV – Stories and Bugs (CN) to signal its scope.

  2. Item Types: Map ADO Story ↔ Jira Story and ADO Bug ↔ Jira Bug (or Task). To keep scores separate, do not include Epic.

  3. Filters / Scope: Target only Stories and Bugs and exclude Epics explicitly via WIQL/JQL. Keep the same Jira project (DEV).

  4. Field Mappings: Map core fields, including Summary, Description, Priority, Assignee, and any custom fields required for delivery teams. Keep Story/Bug mappings independent from the Epic profile.

  5. Workflow / Status Mapping: Map commonly used delivery states, for example, To Do, In Progress, Verify, Done, to ADO states such as New, Active, Resolved, Closed. Account for the resolution setting on Done if Jira requires it.

  6. Hierarchy and Links: Keep hierarchy enabled if you need parent Epic relations. Because Epics are managed by Profile A, ensure your Story/Bug profile only consumes the parent linkage and that it should not attempt to create Epic items if those are out of scope.

Best practice: Keep profiles small and focused. Separate Epics from Stories/Bugs when workflows and field semantics differ, or when you need distinct filters or sync directions.

Avoiding conflicts and overlaps

  • No duplicate type coverage:

    • Ensure a given item type is mapped in only one profile targeting the same Jira project. Otherwise, two profiles can conflict over the same items.

  • Mutually exclusive filters:

    • Use precise WIQL/JQL so that Epic profiles never pick Stories/Bugs, and Story/Bug profiles never pick Epics.

  • Consistent hierarchy setup:

    • Both profiles must share the same hierarchy/link settings, so Stories and Bugs can pair with their parent Epics without triggering reprocessing or failures.

Warning — Cross-profile linking limitation (Cloud Native)

In Cloud Native (CN), links and parent/child relationships are only maintained for items synchronized within the same profile. If related items, for example, an Epic and its child Stories, are handled by different profiles, the app will not create or preserve the parent/child links between them in the target system. This means that even though both items exist in the same Jira project, their hierarchy relationship will be lost.

This is a known limitation of Cloud Native. In Server/Hub (SH), the behavior is different, and cross-profile linking is supported.

Keep this in mind when deciding whether to split item types across profiles: if preserving parent/child links is critical, consider handling all related items in a single profile, or plan for manual link maintenance.

Validation checklist

  • Run an initial sync on a small, filtered set to verify mappings before full enablement.

    • For example, a single Epic or a few Stories/Bugs)

  • Confirm Epic creation/updates flow via Profile A and do not appear in Profile B overview.

  • Confirm Story/Bug creation/updates flow via Profile B, and do not appear in Profile A overview.

  • Check the hierarchy on a sample Story:

    • If the Jira issue shows the correct Epic link, then the Epic exists and is managed by Profile A.

Troubleshooting common pitfalls

Insights derived from investigations like SUPPORT-188493, where certain items showed synced successfully in the overview, but Jira did not reflect changes:

  • Synchronizer user changes are skipped: Edits performed by the dedicated synchronizer account in ADO are intentionally ignored to prevent loops. Re-test with a normal user account.

  • Epic Name mapping for Epics: If you rely on Jira Epic Name, ensure ADO Title → Jira Epic Name is explicitly mapped in the Epic-only profile. If UI shows an empty Azure field for Epic Name, remap and save, then retest by changing an Epic title in ADO.

  • Hierarchy misconfiguration on new profiles: For newly created profiles, verify hierarchy link types. A misconfigured hierarchy can cause long initial runs or failures. Adjust configuration or temporarily disable hierarchy to isolate the issue; then re-enable with proper link mapping.

  • Overlapping scopes: If two profiles target the same type or items, they may repeatedly resync or mask updates. Use explicit filters to enforce mutual exclusivity.

  • Status mapping mismatches: ADO statuses mapped to Jira statuses that aren't present in the target workflow can appear as successful syncs, but won’t change the status in Jira. Align transitions and, if needed, set resolutions when moving to Done/Closed.

Worked example

Below is an illustrative pairing showing how to keep scopes clean while targeting the same Jira project.

Profile

Jira Project

Item Types

Filters (Scope)

Key Mapping Notes

Profile

Jira Project

Item Types

Filters (Scope)

Key Mapping Notes

DEV – Epics (CN)

DEV

ADO Epic ↔ Jira Epic

Only Epics (exclude Stories/Bugs)

Map ADO Title → Jira Epic Name and Summary; verify hierarchy for Epic parentage.

DEV – Stories & Bugs (CN)

DEV

ADO Story/Bug ↔ Jira Story/Bug

Only Stories and Bugs (exclude Epics)

Status mapping aligns with team board; ensure parent Epic exists (managed by Epic profile).

Operational tips

  • Cloning profiles carefully: If you clone a profile to speed setup, immediately recheck Item Types, Filters, and critical field mappings, for example, Epic Name. UI updates or copy operations can leave fields blank until remapped.

  • Scoped initial runs: Start with tight filters or small date ranges to validate before expanding the scope.

  • Monitor overview vs. actual issues: If the overview shows Synced, but the Jira doesn’t change, open the Jira issue by its key and verify:

    • Parent link

    • Status validity

    • Whether the last change came from the synchronizer account

Related references

FAQ

Avoid it. Design profiles so each item type is owned by exactly one profile for a given Jira project.

Common causes: change was made by the synchronizer account (skipped), status mapped to a non-existent Jira transition/status, or parent hierarchy missing. Verify by opening the Jira issue and checking its history and workflow.

Enable hierarchy in both profiles and verify the Epic link type in Jira. The Stories/Bugs profile should consume the parent link; the Epic profile should own Epic creation/updates.