> For the complete documentation index, see [llms.txt](https://msplannertojira.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://msplannertojira.gitbook.io/docs/basics/field-mapping.md). # Field mapping In this step, you decide how **Microsoft Planner fields** map to **Jira fields**.
*** ### Issue Type (required) * You must select the **Jira issue type** to use for newly created issues. * All new tasks from Planner will be created as this issue type. *** ### Date Fields * **Start Date** and **Due Date** from Planner can be mapped to Jira date or custom date fields. * Make sure your selected Jira project has the necessary custom fields available. #### Planner Premium: dates and the project calendar Planner Premium uses a **Monday–Friday project calendar**. This affects how dates are handled: * If a Jira due date falls on a **Saturday or Sunday**, Planner Premium automatically adjusts it to the **previous Friday**. * If a Jira start date falls on a weekend, Planner Premium adjusts it to the **next Monday**. * The connector detects these calendar adjustments and **does not sync them back to Jira** — your original Jira dates are preserved. * When a weekend date is sent to Planner Premium, a `[MS-SYNC]` comment is posted on the Jira issue to let you know the date was adjusted on the Planner side. #### Planner Premium: clearing dates Planner Premium does not support clearing start or due dates once they are set. If you remove a date in Jira: * The Planner task **keeps its original date** (Planner Premium silently ignores the change). * A `[MS-SYNC]` comment is posted on the Jira issue explaining that the date could not be cleared. *** ### Bucket * Planner buckets can be mapped to Jira **select list custom fields**. * Tip: Create a custom select field in Jira (e.g. “Planner Bucket”) if you want to keep bucket info in sync. * To use buckets as workflow stages, choose **Map to Jira Status**. See **Status Mapping** below. *** ### Priority Priority sync is optional and works with both Basic and Premium Planner plans. Planner uses four priority bands: | Band | Planner values | Value written to Planner | | ------------- | -------------: | -----------------------: | | **Urgent** | 0–1 | 1 | | **Important** | 2–4 | 3 | | **Medium** | 5–7 | 5 | | **Low** | 8–10 | 9 | Jira projects can have more or fewer than four priority values. When Jira is the target, the setup wizard uses the values allowed for the selected project and issue type. For a Jira → Planner sync, it combines the values exposed by all of the project's issue types, including subtasks, so priorities used only there can still be mapped: * **Planner → Jira:** Choose the Jira priority written for each Planner band. In a one-way sync, the same Jira priority can be used for more than one band. * **Jira → Planner:** Assign every available Jira priority to exactly one Planner band. * **Bidirectional:** Assign every Jira priority to one Planner band. When a band contains one Jira priority, the wizard automatically uses it for changes coming back from Planner. When a band contains several Jira priorities, choose which one Planner writes back. The four outbound priorities must be distinct, so a bidirectional mapping needs at least four available Jira priorities. A valid mapped Planner priority overrides a configured Jira Priority default when a Jira issue is created. Disabling Priority sync suppresses the mapped Priority write, but a separately configured Jira creation default may still set Priority on newly created issues. If Jira is the source and its Priority ID is missing, malformed, or not present in the saved mapping, Planner is left unchanged. Turning Priority sync on or changing its mapping does not rewrite existing paired tasks and issues. The new mapping applies after Priority itself changes on the configured source side. Planner → Jira targets are saved Jira IDs. The sync does not reload Jira's priority scheme on every cycle, so it cannot know that an administrator removed or disallowed a saved target after setup. Jira may reject that create or update until you edit the sync and choose a currently allowed target. If you change the Jira project, issue type, sync direction, or Planner plan, review the Priority section again. The wizard reloads the available Jira priorities and removes selections that no longer apply. It never guesses a replacement from a priority's name or display order. *** ### Status Mapping There are two ways to sync status between Planner and Jira: For **From Planner** and **Two-way sync**, status choices come from the selected Jira issue type. **To Planner** includes statuses from all issue types in the project. When editing, a saved status that is no longer available stays marked **(unavailable)** until you replace it or remove its mapping; the wizard prevents saving that invalid mapping. #### Option 1: Progress-based (Default) Progress-based status mapping uses three categories: **Not Started (0%)**, **In Progress (50%)**, and **Completed (100%)**. * You select which **Jira status** should be set when syncing from Planner. * When syncing back to Planner, mapped Jira statuses set the chosen progress category. Unmapped statuses fall back to Jira **status categories**: * **Gray (To Do category)** → Not Started * **Blue (In Progress category)** → In Progress * **Green (Done category)** → Completed This means multiple Jira statuses can map into the same Planner progress value. #### Option 2: Bucket-based If your Jira workflow has more than three statuses and you need finer control, you can map **Jira statuses directly to Planner buckets** instead of using progress percentages. * Select **one or more buckets** for each Jira status. The first selected bucket is the **default**; click another selected bucket to move it first. * On Jira → Planner updates, a task already in any selected bucket stays there. Otherwise it moves to the default. Newly created Planner tasks use the default. * Moving a Planner task into any selected bucket sets the corresponding Jira status. * Assign each bucket to one Jira status. Leaving a status with no selected buckets leaves it unmapped. This approach works well when your Planner buckets represent workflow stages (e.g., "To Do", "In Review", "QA", "Done") that align with your Jira statuses. #### Numeric progress from Jira For **Jira → Planner** and **bidirectional** syncs, choose **Jira Number field** in the **Progress** row, then select an existing Jira **Number custom field** with values from 0 to 100. The connector reads that field; it does not calculate progress. This works with both Basic and Premium Planner, including alongside bucket-based status mapping. Premium Planner shows the numeric value in **% Complete**. Basic Planner receives the same percentage, but its task view shows a progress category: for example, `42%` appears as **In progress**, without the number. * Jira supplies the percentage. Planner changes are never written back to this field, and the field cannot be set through the connector's Jira creation defaults. * Values must be numbers from **0 to 100**. Fractions round to the nearest whole percent: `42.1` becomes `42%`, and `42.5` becomes `43%`. * Empty, missing, nonnumeric or out-of-range values leave Planner progress unchanged. * Each Planner task has **one completion percentage**. Choose the Jira field that should supply it; separate completion measures cannot be stored as separate Planner progress values. New Planner tasks receive the current valid source value. Enabling numeric progress or choosing a different source field for existing linked tasks establishes a starting point without changing their progress. Later changes to that Jira number are synchronized. Unrelated configuration edits do not suppress a genuine source-value change. If you manually change Planner progress while the Jira number stays unchanged, the manual value remains until the Jira source changes. A source change such as `42.1 → 42.2` is detected even though both values round to `42%`. For calculated fields, ensure Jira or the field's app refreshes the value before expecting it in Planner. The connector reads the number Jira returns; it does not calculate percentages or run Jira formulas. When the sync can create Jira issues, a required Number progress source must have a **default configured in Jira**. Otherwise, make the field optional or choose **Jira → Planner**. The connector cannot fill this required field because it only reads it. This requirement does not apply to a recurring bidirectional sync with **Jira** selected as the source of new tasks: it updates existing Jira issues but never creates them. Switching the source of new tasks to **Planner** or **Both** requires a Jira default again. *** ### Assignee You can sync assignees between Planner and Jira using one of the following methods: #### Option 1: Automatic matching by name * Enable user mapping and select **"Match by full name"**. * The app will automatically match users across systems based on their display names (case-insensitive). * Works well when users have the same name in both Planner and Jira. #### Option 2: Manual user mapping * For users with different names across systems, you can create **explicit mappings** between Planner users and Jira accounts. * These direct mappings take priority over automatic name matching. #### Option 3: Description embedding * If you prefer not to map users directly, assignee information can be included in the **description** instead. * Example: A Planner task synced into Jira will have its original assignee listed in the issue description. *** ### Labels Enable **Sync labels** in field mapping to keep labels in sync. Label filters choose which tasks participate; they do not enable label synchronization. * Only existing Planner labels are matched. Matching Jira labels add or remove Planner labels; other Jira labels are kept in Jira. * New **Basic Planner** syncs include unnamed color labels. Older Basic syncs keep named-only behavior. To include colors in an older sync, clear **Only sync named labels** and save. You can change your choice before saving; after saving with colors enabled, this compatibility option is no longer shown when you reopen the sync. * In **Premium Planner**, label synchronization is off until you enable it. In both plan types, custom names take precedence; unnamed labels use verified English color names, such as **Pink**. Jira receives ordinary text labels, not Planner color styling. No new Planner labels are created. * Spaces become underscores in Jira: **Light blue → Light\_blue**. * If multiple Planner labels would use the same Jira name, resolve the duplicate names before syncing labels from Jira. * When syncing to Jira, renaming a Planner label updates its Jira label and preserves Jira-only labels. *** ### Sub-tasks and hierarchy The connector syncs tasks as **flat items**: * **Jira sub-tasks** are synced as regular tasks in Planner — the parent-child relationship is not preserved. * **Planner Premium indent/outdent:** Planner Premium supports indenting tasks to create sub-tasks. These relationships are not synced — indented sub-tasks are treated as independent tasks, the same as top-level tasks. *** ### Cross-links Cross-links create **clickable URLs** between synced Planner tasks and Jira issues, so you can quickly jump from one system to the other. * Enable cross-links in the field mapping step when setting up your sync. #### Where the link appears — Jira side You choose one of two modes: * **Description** — the Planner task URL is appended to the Jira issue description. * **Custom field** — the Planner task URL is written into a Jira custom field of your choice (text, textarea, or URL field types are supported). #### Where the link appears — Planner side * The Jira issue URL is always added to the **Planner task description** (Planner does not support custom fields). #### Notes * Cross-links are written once and are idempotent — if the link is already present, it won’t be duplicated. * If you enable cross-links on an existing sync, links will be added to all previously synced items on the next sync cycle. *** ✅ Once you’ve mapped the fields you need, click **Next** to review and launch your sync.
### Defaults for new Jira issues Use **Defaults for new Jira issues** to set Jira values when the sync creates an issue from Planner. Required fields appear automatically. Choose **Add field** to add a supported optional field, then choose or enter its value. You can remove optional defaults at any time. Available fields depend on the selected Jira project and issue type. Supported editors include text, paragraphs, numbers, dates, single and multiple choices, components, versions, labels, and Parent. Fields managed by the connector, such as the project, issue type, title, description and cross-link fields, cannot be overridden here. Field types without a supported editor are not offered. For **Parent**, choose an existing issue at the Epic hierarchy level in the same Jira project. The type can be Epic or another type at that level, such as Initiative. The selected child must be a standard issue type. Types at the same hierarchy level are peers and cannot be parents of each other. This setting does not create parent issues, configure higher-level hierarchies, or place issues under parents in other projects. The connector verifies the choice when you save. If the parent becomes unavailable later, Jira creation reports an error; the connector does not silently create the issue without its selected parent. Mapped Planner values take precedence over scalar defaults, including intentional clearing. Labels are combined: the new issue receives both mapped Planner labels and your configured Jira labels without duplicates. For a marker such as `created-from-planner`, use a name different from Planner label names. Names matching current or previous Planner labels follow normal label synchronization. A distinct marker is preserved by subsequent Planner label updates, but a marker manually removed in Jira is not automatically restored. Jira creation labels also work with Premium plans; they do not enable the separate **Sync labels** option. Changing defaults affects **future issue creation only**. Existing linked issues are not moved to another parent or updated with the new defaults. Source selection and filters still decide which tasks may create issues. Changing the Jira project or issue type clears context-specific defaults. Review them before saving. Saved fields or options that are no longer available remain visible so you can correct or remove them. If Jira access or field metadata cannot be verified, retry the check before saving. Jira may still reject a configured value if its permissions or field configuration change after setup.