> 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/configure-sync.md). # Configure sync In this step, you define the **scope of your sync**: which Jira issues and Microsoft Planner tasks should be included.
*** ## Which side can add new tasks? For an automated **two-way sync**, choose where new tasks can come from: **Both**, **Planner**, or **Jira**. | Choice | What gets added | | ----------- | -------------------------------------------------------------------------------------------------- | | **Both** | New Planner tasks in scope are synced to Jira, and new Jira issues in scope are synced to Planner. | | **Planner** | New Planner tasks in scope are synced to Jira. New Jira issues are not synced to Planner. | | **Jira** | New Jira issues in scope are synced to Planner. New Planner tasks are not synced to Jira. | This choice applies to unlinked items already in scope, items added later, and items that later enter scope. Syncing runs automatically on every cycle. Linked pairs continue syncing in both directions while they remain in scope. Planner wins conflicts. With **Planner**, only Planner bucket and date filters are available. With **Jira**, only Jira JQL is available. **Both** retains both kinds of filters. The other side is the selected destination plan or project. When changing this choice, any conflicting saved filter remains visible and must be explicitly removed before saving. Existing syncs without this setting retain **Both** behavior. Changing it preserves existing links and field mappings, applies on subsequent runs, and does not require **Start fresh** or rewrite unchanged fields. It does not undo or delete tasks created previously. Review the explanation before creating or updating your sync. Query result counts describe the source scope; they are not a preview of how many tasks will be created. *** ## Jira Scope * Select the **Jira project** to sync * (Optional) Enter a **JQL query** to further filter which issues are included ### JQL Filter JQL (Jira Query Language) lets you control exactly which Jira issues are included in the sync. For example, you can sync only issues with a specific label, status, issue type, or any combination of Jira fields. **How it works:** * The JQL filter is applied **every sync cycle** — it’s a live, ongoing filter, not a one-time snapshot * Only Jira issues matching your query are included in each sync run * If an issue stops matching the filter (e.g., someone changes its status or label), it will be **temporarily excluded** from the sync — but the link between the Jira issue and the Planner task is preserved * If the issue later matches the JQL again, syncing **resumes automatically** **Examples:** | Goal | JQL | | --------------------- | ------------------------------------------------------------------ | | Only sync bugs | `issuetype = Bug` | | Exclude done issues | `status != Done` | | Only a specific label | `labels = "planner-sync"` | | Combine conditions | `issuetype = Story AND status != Done AND labels = "planner-sync"` | > **Tip:** You can test your JQL query in Jira’s issue search before using it here to make sure it returns the right set of issues. *** ## Microsoft Planner Scope * Select the **Planner plan** you want to connect with the Jira project ### Live Planner Filters For an automated sync where Planner is a source, you can optionally: * Include tasks from one or more selected **Planner buckets** * Include only tasks that have **both a start date and a due date** These are live filters: they are checked again on every sync cycle. Selected buckets use **OR** logic, and the bucket and date filters combine with **AND**. For example, selecting “Backlog” and “In progress” plus the date option includes tasks from either bucket only when both dates are present. Microsoft may automatically schedule Premium tasks even when dates were not entered manually. The date filter uses the dates returned by Microsoft, so an auto-scheduled Premium task can match it. When a linked task moves out of scope, the connector pauses updates for that pair but keeps its link. If the task matches again later, syncing resumes with the same Jira issue instead of creating a duplicate. If a selected bucket is later deleted or is no longer available, it remains visible as **Unavailable bucket** and continues to exclude tasks until you remove or replace it. This prevents a saved narrow filter from silently expanding to all tasks. ### Skip Completed Tasks * If enabled, completed Planner tasks that have not already been linked are excluded and **not synced to Jira** * This is useful if your Planner plan already has many closed tasks you don’t want cluttering your Jira project **How it works:** * When you create the sync, the connector takes a snapshot of tasks already marked as 100% complete; those tasks remain excluded even if reopened later * On later cycles, newly completed tasks that have not been linked yet are also excluded * Tasks that are already linked continue syncing so completion and reopening changes reach Jira * This setting is locked after the sync is created — you cannot change it later for that sync Unlike the bucket and date options above, Skip Completed is a lifetime rule for avoiding unwanted initial creation, not an editable live scope filter. ### Start Fresh * Shown only when **creating a new recurring sync** * If enabled, the new sync **ignores task links created by previous syncs** of the same plan and Jira project — it connects them as if they had never been synced before **How it works:** * Normally, when you create a sync for a plan and project that were synced before, the connector **reuses the stored links** between Planner tasks and Jira issues — already-linked pairs keep syncing as one item instead of being duplicated * With **Start fresh**, the new sync starts a new generation of links and does not see any links made by earlier syncs of this plan * On the first sync cycle, every task and issue in scope is treated as **not yet linked** — depending on the sync direction, the connector creates fresh counterparts for them * Links from previous syncs are **not deleted** — other existing syncs keep working with their own links **When to use it:** * A task or issue was **deleted while synced** and you want it recreated from the surviving side — without Start fresh, a new sync remembers the old link and skips recreation * You want to reconnect a plan from a clean slate after earlier experiments ⚠️ **Duplicates warning:** if both the plan and the project still contain the items that were previously linked, Start fresh will create new counterparts for them — resulting in duplicates. Use it when one side was cleaned up, or when recreating missing items is exactly what you want. * This choice is only available at creation time — it cannot be toggled later for an existing sync *** ✅ Once you’ve defined your scope, click **Next** to continue to field mapping.