> 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.
*** ## 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 ### Skip Completed Tasks * If enabled, all **completed tasks in Microsoft Planner** (at the time you set up the sync) will be 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 **one-time snapshot** of all tasks currently marked as 100% complete in Planner * Those specific tasks are permanently excluded from this sync * ⚠️ **This is not a live filter** — it only captures tasks that are completed at the moment you set up the sync: * Tasks that are completed **after** the sync is created will **continue to sync** normally * Tasks in the snapshot that are later marked incomplete will **remain excluded** * This setting is locked after the sync is created — you cannot change it later for that sync ### 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.