Work Item Type Mapping

The most significant structural difference between Azure DevOps and Jira is hierarchy depth. ADO supports four levels; Jira Cloud natively supports two.

Default Type Mappings

All mappings can be overridden. If your Jira project uses custom issue types, Migrayt detects them automatically and offers them as mapping targets.

The Hierarchy Problem

ADO's process templates (Agile, Scrum, CMMI) all support four hierarchy levels:

Epic
  └── Feature
        └── User Story / Story
              └── Task / Bug

Jira Cloud's native hierarchy supports two levels:

Epic
  └── Story / Task / Bug

When a four-level hierarchy is migrated to a two-level system, the intermediate Feature level must be collapsed.

How Migrayt handles this

During Phase 3 (Type Mapping), if Migrayt detects Features in your ADO project, it presents you with three options:

Option A — Collapse (recommended for most projects)

Feature → Epic in Jira. Original ADO Epics become a label (ado-epic) on their child items. The Feature becomes the highest-level container in Jira.

Before (ADO):          After (Jira):
Epic "Q3 Platform"     Epic "Mobile Payments Feature"  [label: ado-epic:Q3-Platform]
  └── Feature             └── Story "Add card input"
        "Mobile Payments"  └── Story "Handle 3DS auth"
              └── Story "Add card input"
              └── Story "Handle 3DS auth"

Option B — Flatten

Features and Stories both become Stories in Jira. Parent-child links are preserved as Jira issue links (relates to).

Option C — Manual

You assign each ADO type to any Jira issue type manually. Suitable for projects with non-standard ADO configurations.

Parent-Child Resolution

After type mapping is confirmed, Migrayt resolves parent-child relationships by walking up the ADO hierarchy to find the nearest valid Epic ancestor. Items with no Epic ancestor are created without a parent.

For example, an ADO Sub-Task whose parent chain is Sub-Task → Task → Story → Feature → Epic will have its Jira Epic Link set to the mapped Epic, with the Story correctly nested under it.

Custom Issue Types

If your Jira project has custom issue types configured (from apps like Structure, Advanced Roadmaps, or custom configurations), Migrayt detects them during the Phase 1 connection and makes them available as mapping targets.

Custom Jira issue types that are unavailable on the project's create screen are automatically stripped from the payload and the item falls back to the next valid type (Story → Task → Bug).

Provenance Labels

Every item created by Migrayt receives two labels:

• migrated-from-ado — identifies all Migrayt-migrated items
• ado-id-{N} — unique identifier linking the Jira issue back to the original ADO work item ID

These labels are used for idempotency (preventing duplicate creates on re-runs) and for audit purposes. Do not remove them if you plan to run incremental migrations in the future.