Field mapping determines which Craft.io fields pass data to Jira or Azure DevOps (ADO), and which fields sync back. Getting this right is what makes the integration useful day-to-day. Without it, your dev tool and your product backlog are two separate sources of truth rather than one connected view.

Understanding field types

Craft.io can only map fields of the same type across both tools. Before mapping a custom field, confirm the field type matches on both sides. For example:

Text maps to a text field in Jira or ADO
Single-select maps to a single-select or dropdown field in the dev tool
Numeric maps to a numeric field in the dev tool

Only corresponding fields of the same type will appear in the dropdown on the field mapping page.

Accessing the field mapping screen

To access your field mapping configuration for either tool:

Go to Workspace Settings > Integrations
Click the three-dot menu next to your integration
Select Field & type mapping
Scroll down to see the available fields in your connected project

❗Note, you need to be an Admin user in the Workspace to manage the integration.

Jira field mapping

Default fields

These fields sync automatically between Craft.io and Jira - no configuration needed:

Title
Description
Attachments
Importance
Dev Assignee
Sprint
Dependencies
Status (Jira to Craft.io only) > note, this requires status automations to be set up

❗Sprint sync requires a specific permission. The Jira account whose API token is used for the integration needs "Manage Sprints" permissions in Jira for sprint data to sync in both directions.

Optional fields

These fields are not mapped by default but can be enabled in your field mapping settings:

Sprint
Story Points
Dates (Start Date, Target Date)
Quarter (Fix Version)
Labels
Objective and Key Results
Value and Effort
Custom fields - any Craft.io custom field can be mapped to a Jira custom field as long as the field types match (text, single select, numeric, etc.)

❗Fields must be on the Jira Create screen to appear in Craft.io. If a field exists in your Jira project but is not showing up in Craft.io's mapping UI, check that it is added to the Create screen for that issue type in Jira. After making changes to fields in Jira, use the reload button in the mapping settings before expecting them to appear.

Azure DevOps field mapping

Default fields

These fields sync automatically between Craft.io and Azure DevOps - no configuration needed:

Title
Description
Priority (see note below)
Dev Assignee
Iteration Path (Sprint)
Dependencies
Status (ADO to Craft.io only)

❗Priority must be the system Priority field. If your ADO project uses a renamed or custom priority field, it will not map correctly - the integration requires ADO's built-in system Priority field specifically.

Optional fields

These fields are not mapped by default but can be enabled in your field mapping settings:

Start Date and Target Date
Story Points
Labels
Value / Effort
Custom fields - any Craft.io custom field can be mapped to an ADO custom field as long as the field types match

A note on Quarter: ADO has no native Quarter field. Quarter can only be mapped to a text field in ADO, which means it will not behave as a date range. If values sync from ADO back into Craft.io, Quarters are created without date context.

Common questions

A field isn't appearing in my mapping list
- If you recently added a field or made changes in your dev tool, click Reload at the top of the integrations panel to pull through the latest data. For Jira specifically, the field also needs to be on the Create screen for the relevant issue type - if it's not there, Craft.io cannot read it regardless of whether you reload.

Can I map OKRs, Timeframes, or Quarter fields?
- These are multi-select or date-range fields in Craft. ADO and Jira don't have equivalent field types, so they can only map to a text field. Sync is one-directional (Craft to dev tool) and values won't behave as date ranges on the dev tool side.

Does the Jira Assignee field map to the Craft Assignee field?
- No. Jira creates a separate "Jira Assignee" field in Craft. The Craft Assignee is your PM or product owner - the Jira Assignee tracks the developer. They stay separate by design.

Do date fields sync automatically?
- No. Date fields (Start Date, Target Date) must be explicitly mapped in your field mapping settings for both Jira and ADO. They are not included in the default mapping.

Will changing a status in Craft.io update the status in Jira or ADO?
- No. Updating a status in Craft.io does not push a change to Jira or ADO. However, if Status Automations are configured, any status change in your dev tool will automatically overwrite the status in Craft.io. You can still edit the status in Craft.io directly - it just won't sync back to the dev tool, and will be over-written when a status is changed for a synchronized item in Jira/ADO.

Can I control which direction a field syncs?
- Field mapping is bi-directional by default - changes in either tool update the other. The only directional control available is through Status Automations for status fields. Per-field sync direction is not configurable.

The description field is updating in ways I don't expect
- The description field is mapped by default and syncs both ways. This means edits made in Jira or ADO will overwrite the description in Craft.io, and vice versa. If your dev team edits descriptions in Jira, those changes will reflect in Craft.io automatically. There is no option to make the description field one-way.

Do comments sync between Craft.io and Jira or ADO?
- No. Comments are not synced in either direction for both tools. Only field-level data syncs.
How do Timeframe and Quarter fields map to Jira and ADO?
- In Jira, both fields can be mapped to Fix Version or a custom multi-select field. Fix Version must be on the Create screen for the relevant issue type before it appears in the mapping UI. Note that editing an existing value's name or dates in either tool creates a new value rather than updating the existing one.
- In ADO, there is no native multi-select or date-range field type. Timeframe and Quarter can only map to a plain text field, and sync is one-directional - Craft.io to ADO only.