Field Mapping
Standard Field Mappings
These fields are mapped automatically with high confidence. You will see them pre-ticked in the mapping UI.
| ADO Field | Jira Field | Notes |
|---|---|---|
System.Title | summary | Truncated to 255 characters if longer |
System.Description | description | HTML → Atlassian Document Format (ADF) conversion |
System.State | status | Via workflow transition (see State Mapping below) |
Microsoft.VSTS.Common.Priority | priority | Numeric (1–4) → Named (Highest, High, Medium, Low) |
Microsoft.VSTS.Scheduling.StoryPoints | story_points (customfield_10016) | Numeric |
Microsoft.VSTS.Scheduling.Effort | story_points | Fallback if StoryPoints not set |
System.AssignedTo | assignee | Matched by email address |
System.CreatedBy | reporter | Matched by email address |
System.Tags | labels | Semicolon-separated in ADO → space-replaced labels in Jira |
System.AreaPath | components | Last segment of area path → Jira component |
System.IterationPath | Sprint (customfield_10020) | Via pre-created Jira sprint |
Microsoft.VSTS.Common.AcceptanceCriteria | Appended to description | Rendered as a section in the ADF body |
Microsoft.VSTS.TCM.ReproSteps | Appended to description | For Bug type; rendered as "Steps to Reproduce" |
Microsoft.VSTS.TCM.SystemInfo | Appended to description | Rendered as "Environment" section |
Priority Mapping
| ADO Priority | Jira Priority |
|---|---|
| 1 | Highest |
| 2 | High |
| 3 | Medium |
| 4 | Low |
| (not set) | Medium |
State Mapping
ADO states vary by process template (Agile, Scrum, CMMI). Migrayt maps them to Jira status names and then transitions each issue to the correct state after creation.
| ADO State | Jira Status |
|---|---|
| New | To Do |
| Active | In Progress |
| In Progress | In Progress |
| Committed | In Progress |
| Resolved | Done |
| Closed | Done |
| Done | Done |
| Approved | To Do |
| Proposed | To Do |
| Ready | To Do |
| Backlog | Backlog |
| In Review | In Review |
| Testing | In Review |
| Investigating | In Progress |
| Removed | Cancelled |
| Cancelled | Cancelled |
| On Hold | Blocked |
| Blocked | Blocked |
If your Jira project workflow does not have a "Cancelled" or "Blocked" status, Migrayt skips the transition and the item remains in its default creation status ("To Do"). This is flagged in the post-migration report.
Custom state overrides can be passed in the migration options:
"state_overrides": {
"Resolved": "In Review",
"Custom State": "In Progress"
}Custom Field Mapping
Custom fields in ADO are detected during the scan phase and presented in the field mapping UI. For each custom field, Migrayt:
- Searches for an exact-name-match custom field in your Jira project
- If not found, searches for a fuzzy name match with the same field type
- If no match, marks the field as unmapped — the data will not be carried over
Supported custom field types
| ADO Field Type | Jira Field Type |
|---|---|
| String / Text | Text field (single-line or multi-line) |
| Integer | Number field |
| Double | Number field |
| DateTime | Date field |
| Boolean | Checkbox field |
| Picklist (string) | Select list (single-choice) |
| Picklist (integer) | Select list (single-choice) |
| Identity (user) | User picker |
Picklist value mapping
For picklist (dropdown) fields, Migrayt also maps the individual values. For example, if ADO has a "Region" field with values North, South, East, West, and Jira has a "Region" field with Northern, Southern, Eastern, Western, the AI suggests value-level mappings.
You can override these in the mapping UI before the migration starts.
Description Conversion (HTML → ADF)
ADO stores descriptions as HTML. Jira Cloud's REST API v3 uses Atlassian Document Format (ADF), a structured JSON format. Migrayt converts the following HTML constructs:
| HTML | ADF Node |
|---|---|
<p> | paragraph |
<h1>–<h6> | heading with correct level |
<ul>, <li> | bulletList → listItem |
<ol>, <li> | orderedList → listItem |
<pre>, <code> | codeBlock |
<strong>, <b> | strong mark |
<em>, <i> | em mark |
<a href> | link mark |
<img src> | Inline image (URL rewritten after attachment upload) |
| HTML entities | Unescaped to Unicode |
Constructs that cannot be converted (such as complex tables) are preserved as plain text paragraphs.
Fields That Cannot Be Migrated
The following fields have no direct Jira equivalent and are not migrated:
| ADO Field | Reason |
|---|---|
System.CreatedDate | Jira Cloud does not allow setting created on issues via API |
System.ChangedDate | Read-only on Jira issues |
System.BoardColumn | Board configuration is not part of issue data |
Microsoft.VSTS.Common.ActivatedDate | No equivalent |
Microsoft.VSTS.Common.ResolvedDate | No equivalent |
Microsoft.VSTS.CMMI.Blocked | Represented via status transition to "Blocked" |
All unmapped fields are listed in the pre-migration review screen and in the post-migration report.
Reporter Attribution
Jira Cloud API does not allow setting reporter to an arbitrary user unless the calling account is a site admin. If the migration service account is not a site admin, the reporter is set to the migration service account and the original ADO createdBy is prepended to the description:
[Originally created by: alice@company.com on 2024-01-15]
[Original description follows]
...