--- title: Product Settings | Azure DevOps Integration Import description: Import your product backlog from Jira --- [Skip to content](https://support.productplan.com/roadmap-data-source-import-ado#main-content) English Show submenu for translations [![ProductPlan\_Logo\_Positive 1](https://support.productplan.com/hubfs/ProductPlan_Logo_Positive%201.svg)](https://www.productplan.com/) Open main navigation Close main navigation - English Show submenu for translations - [https://www.productplan.com/](https://www.productplan.com/) [https://www.productplan.com/](https://www.productplan.com/) Find best practices and answers to common questions in ProductPlan - There are no suggestions because the search field is empty. 1. [Support Center](https://support.productplan.com/?hsLang=en) 2. [Roadmapping](https://support.productplan.com/roadmapping?hsLang=en) 3. [Integrations](https://support.productplan.com/roadmapping?hsLang=en#integrations) # Product Settings | Azure DevOps Integration Import ## Import your product backlog from Azure DevOps. Each product has one saved query that decides which Azure DevOps work items make up its backlog. Once the query is saved, matching items import automatically and keep syncing. New issues created in Azure DevOps that match the query appear on their own. Every roadmap in the product draws from that backlog. ![](https://support.productplan.com/hs-fs/hubfs/image-png-Oct-20-2026-09-36-49-6894-PM.png?width=1588&height=550&name=image-png-Oct-20-2026-09-36-49-6894-PM.png) ### Before you start - **You need access to the product.** Admins with access to Manage Products are able to write and update saved query searches in Product \> Integrations. - **An admin must connect Azure DevOps first.** Only account admins can create, edit or delete the integration, from Manage Products \> Integrations. - **The projects you want must be mapped.** A query can only search Azure DevOps projects that an admin has added to the integration and mapped fields for. If a project is missing from the project picker, select **Manage Project Mappings**. ### How the query works Every query has two parts, read top to bottom in the query card: 1. **The project scope** — `project in ( … ) AND`. Choose one or more mapped projects from the picker. This part is required, and it is always applied. 2. **Your filter** — everything you type below the scope line. It narrows the items within those projects. ProductPlan combines the two into a single Azure DevOps query. You never need to write `project = …` yourself, and naming a project in your filter that isn't selected in the picker won't bring its items in. ![](https://support.productplan.com/hs-fs/hubfs/image-png-Oct-20-2026-09-33-55-3967-PM.png?width=686&height=294&name=image-png-Oct-20-2026-09-33-55-3967-PM.png) Leave your filter empty to import every supported item in the selected projects. ProductPlan asks you to confirm before saving an unfiltered query. #### Build your query 1. Go to **Product Settings \> Integrations**. 2. Under **Roadmap Data Source**, choose at least one project from the **Select projects** picker. Run & Preview and Save stay disabled until a project is selected. 3. Choose how you want to write your filter: - **WIQL** — type Azure DevOps Query Language directly. Best if you already have a filter in Azure DevOps you want to reuse. - **Natural Language** — describe what you want in plain words, such as *open epics and features labeled XYZ*, and ProductPlan writes the WIQL for you. Review the generated query before you save. 4. Select **Run & Preview** to check the results. 5. Select **Save Query**. Matching items begin importing into the product's backlog. ![](https://support.productplan.com/hs-fs/hubfs/image-png-Oct-20-2026-09-34-34-7735-PM.png?width=670&height=590&name=image-png-Oct-20-2026-09-34-34-7735-PM.png) #### Check your results with Run & Preview The preview shows what will import before anything changes: - **The match count** ("N out of M matches") counts every matching item, even though only the first 100 rows are shown. Select **Load Full Table** to see more. - **Each row shows its roadmap level** — initiative, epic or story — and you can expand parents to see their children. - **If Azure DevOps rejects the query**, the card turns red and shows Azure DevOps's own error message, with a link to Azure DevOps's syntax reference. Fix the query and run it again. What you see in the preview is what imports. ### What imports Roadmaps have three hierarchy levels: initiatives, epics, and stories. Imported Azure DevOps items map to the hierarchy levels as displayed in the table below. | **ADO Process** | **Initiative** | **Epic** | **Story** | | --- | --- | --- | --- | | Agile | Epic | Feature | Story | | Scrum | Epic | Feature | Product Backlog Item | | CMMI | Epic | Feature | Requirement | | Basic | N/A | Epic | Issue | Parent and child relationships come across with the items. Levels beyond three layers of hierarchy are not supported, and tasks are excluded. ### Tips for reliable queries - **Wrap `OR` conditions in parentheses.** Your filter is joined to the project scope with `AND`, so `(labels = roadmap OR labels = q4)` keeps the logic unambiguous. - **Include children if you want progress to roll up.** An epic's percent complete is calculated only from the stories your query imports. If you import epics but not their stories, the epic's progress won't reflect them. - **Keep an epic and its stories in the same product.** Stories belong to their epic's product. Initiatives can have children across products. - **Leave out `ORDER BY`.** Sort order doesn't affect what imports, and roadmaps have their own sorting and grouping. ### Troubleshooting | **What you see** | **Likely cause** | **What to do** | | --- | --- | --- | | Not receiving updates on the integration | The connecting admin isn't a Project Administrator, or Azure DevOps put the hook on probation or disabled it | Reconnect as a Project Administrator. Check Project settings \> Service hooks in Azure DevOps. | | "Your organization's admin needs to approve this" at sign-in | The Microsoft tenant requires admin consent | A Microsoft tenant admin approves ProductPlan. | | No organizations found when connecting | The tenant blocks profile access, or the user belongs to no organization | Use Manual Entry with the organization URL. | | An existing product imports nothing after the release | No project is selected on the query | Select one or more projects on the query. | | The preview refuses the query | The query type is Work items and direct links or Tree of work items | Switch to Flat list of work items. To get a parent's children, filter on \[System.Parent\] = \. | | The preview shows an Azure DevOps error instead of a count | The query matches more than 20,000 work items | Narrow the query. | | Items disappeared after editing a query | Narrowing a query removes the imported items it no longer matches | Widen the query. Items created in ProductPlan aren't affected. | | Can't change State, Description or Iteration | These fields sync one way | Change them in Azure DevOps. | | A mapped field is read-only on some items | That work item type doesn't have the field | Map a field the type has, or leave it read-only. | | Some items have no dates and can't be placed on the roadmap | The item's work item type doesn't have the Azure DevOps field mapped to Start Date or End Date, for example a Scrum Product Backlog Item | Add the mapped date field to that work item type in Azure DevOps (Organization settings \> Boards \> Process, on an inherited process). | | "Azure DevOps didn't let you create the tag" | The user lacks Create tag definition | Ask a project admin for the permission, or pick an existing tag. | | A value is refused on save | Azure DevOps doesn't allow that value for the work item type | Pick an allowed value and check the value mapping. | | A value mapping stopped working | The value was renamed in Azure DevOps | Re-map the renamed value. | | An item shows no parent though Azure DevOps has one | The parent isn't exactly one level up | Fix the link in Azure DevOps. | | Can't pick a parent in ProductPlan | The parent must be exactly one level up and linked through the same integration | Choose a parent on the level above. | | An item became Not Synced after its type changed | It was changed to a type ProductPlan doesn't sync, such as Task | Change the type back to re-link it on the next sync, or keep it as ProductPlan-only. | | Can't push an initiative in a Basic project | Basic has no initiative level, so Epic is the top level and Issue is the story level | Expected. Push at the levels the process has. | | Bugs don't import | The team's Working with bugs setting is tasks or off | Set bugs to show with requirements in Azure DevOps. | | Dates show one day early | A script or import wrote the date at local midnight | Edit the date in ProductPlan or in Azure DevOps' date picker. | | An edit prompts Authorize | The user hasn't connected their own Microsoft account | Authorize once. Edits are then made as that user. | | An older connection can't search people | It was connected before people search was added | Reconnect the integration. | | A change in Azure DevOps didn't arrive | The event was dropped while the hook was on probation | Use Pull from integration on the item, or Refresh all in the product's query settingsre-save the query. | ### FAQ **Does the integration support server / on-prem versions of ADO?** Not in this release. The integration connects to Azure DevOps Services, the cloud version of Azure DevOps. **Does every editor need to set up the integration?** Editors don't configure anything, but each one authorizes their own Microsoft account once, the first time they edit a synced field or push an item. Their edits then reach Azure DevOps as them. Viewing synced items doesn't require a sign-in. **Can we connect both Jira and Azure DevOps?** Not in this release. Each account can connect one integration, either Jira or Azure DevOps, and one Azure DevOps organization. **Do we need to configure service hooks in Azure DevOps?** No. ProductPlan creates them when a project is mapped, as long as the connecting admin is a Project Administrator on that project. If a hook is disabled by hand, re-enable it in Azure DevOps under Project settings \> Service hooks. **Why don't tasks appear on the roadmap?** The roadmap has three levels: initiatives, epics, and stories. Tasks sit below the requirement level in Azure DevOps, so they aren't imported. **Which fields can't be changed from ProductPlan?** State, Description, Area Path, Iteration Path, Work Item Type, Team Project, and fields Azure DevOps sets itself, such as Reason. Change them in Azure DevOps and the roadmap updates to match. A mapped field is also read-only on items whose work item type doesn't have it. **Do comments sync?** No. Comments stay in the tool where they were written. **What happens when a work item is deleted in Azure DevOps or no longer matches the query?** A work item deleted in Azure DevOps is removed from ProductPlan once it reaches the Azure DevOps recycle bin, and if it is restored, items created in ProductPlan are re-linked while items created in Azure DevOps return as new items.and comes back if it is restored. A work item that no longer matches the query is removed from ProductPlan, unless it was created in ProductPlan and pushed. A work item changed to a type ProductPlan doesn't sync is disconnected and kept as Not Synced. - [Platform Updates & Events](https://support.productplan.com/platform-updates-events?hsLang=en#main-content) - [Product Updates](https://support.productplan.com/platform-updates-events?hsLang=en#product-updates) - [Webinars + Trainings](https://support.productplan.com/platform-updates-events?hsLang=en#webinars-trainings) - [Product Intelligence](https://support.productplan.com/product-intelligence?hsLang=en#main-content) - [Products](https://support.productplan.com/product-intelligence?hsLang=en#products) - [Research Surveys + Feedback Forms](https://support.productplan.com/product-intelligence?hsLang=en#research-surveys-feedback-forms) - [Ideas + Signals](https://support.productplan.com/product-intelligence?hsLang=en#ideas-signals) - [Strategy](https://support.productplan.com/strategy?hsLang=en#main-content) - [Objectives & Key Results](https://support.productplan.com/strategy?hsLang=en#objectives-key-results) - [Video Guides](https://support.productplan.com/strategy?hsLang=en#video-guides) - [\[Legacy\] Roadmapping](https://support.productplan.com/legacy-roadmapping?hsLang=en#main-content) - [Getting Started](https://support.productplan.com/legacy-roadmapping?hsLang=en#getting-started) - [Integrations](https://support.productplan.com/legacy-roadmapping?hsLang=en#integrations) - [Standardization](https://support.productplan.com/legacy-roadmapping?hsLang=en#standardization) - [Roadmap Features](https://support.productplan.com/legacy-roadmapping?hsLang=en#roadmap-features) - [Strategic Portfolio](https://support.productplan.com/legacy-roadmapping?hsLang=en#strategic-portfolio) - [Sharing](https://support.productplan.com/legacy-roadmapping?hsLang=en#sharing) - [Frequently Asked Questions](https://support.productplan.com/legacy-roadmapping?hsLang=en#frequently-asked-questions) - [Roadmapping](https://support.productplan.com/roadmapping?hsLang=en#main-content) - [Integrations](https://support.productplan.com/roadmapping?hsLang=en#integrations) - [Launch](https://support.productplan.com/launch?hsLang=en#main-content) - [Video Guides](https://support.productplan.com/launch?hsLang=en#video-guides) - [Initiatives](https://support.productplan.com/initiatives?hsLang=en) - [Account Setup & Security Settings](https://support.productplan.com/account-setup-security-settings?hsLang=en#main-content) - [Getting Started](https://support.productplan.com/account-setup-security-settings?hsLang=en#getting-started) - [Single Sign On](https://support.productplan.com/account-setup-security-settings?hsLang=en#single-sign-on) - [User Permissions](https://support.productplan.com/account-setup-security-settings?hsLang=en#user-permissions) - [Notifications](https://support.productplan.com/account-setup-security-settings?hsLang=en#notifications) - [AI](https://support.productplan.com/account-setup-security-settings?hsLang=en#ai) - [Licenses + Payment](https://support.productplan.com/account-setup-security-settings?hsLang=en#licenses-payment) - [Security + Privacy](https://support.productplan.com/account-setup-security-settings?hsLang=en#security-privacy) - [FAQ](https://support.productplan.com/faq?hsLang=en) [![ProductPlan\_Logo](https://support.productplan.com/hubfs/ProductPlan_Logo_Negative%201.svg "ProductPlan_Logo")](https://support.productplan.com/?hsLang=en) Copyright © 2026, ProductPlan