Product Settings | Integration Import

Each product has one saved query that decides which Jira work items make up its backlog. Once the query is saved, matching items import automatically and keep syncing. New issues created in Jira that match the query appear on their own. Every roadmap in the product draws from that backlog. This article covers how to write a query that brings in exactly what you need.

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 Jira Cloud 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 Jira 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:

The project scope — project in ( … ) AND. Choose one or more mapped projects from the picker. This part is required, and it is always applied.
Your filter — everything you type below the scope line. It narrows the items within those projects.

ProductPlan combines the two into a single Jira 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.

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

Go to Product Settings > Integrations.
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.
Choose how you want to write your filter:
- JQL — type Jira Query Language directly. Best if you already have a filter in Jira you want to reuse.
- Natural Language — describe what you want in plain words, such as open epics and stories labeled XYZ, and ProductPlan writes the JQL for you. Review the generated query before you save.
Select Run & Preview to check the results.
Select Save Query. Matching items begin importing into the product's backlog.

JQL building blocks

Your filter is standard Jira Cloud JQL, minus the project clause. These are the pieces most roadmap queries are built from:

To import…	Add this to your filter
Only certain levels	`issuetype in (Initiative, Epic)`
Only open work	`statusCategory != Done`
Work that isn't resolved	`resolution = Unresolved`
Items with a label	`labels = roadmap`
Items in a component	`component = "Payments"`
Items in a release	`fixVersion in ("2026.4", "2027.1")` or `fixVersion in unreleasedVersions()`
Items owned by a team	`"Team[Team]" = "Growth"`
Children of specific parents	`parent in (PAY-120, PAY-121)`
A custom field value	`"Product Area[Dropdown]" = "Checkout"`
Recently created items	`created >= -90d`

Combine conditions with AND, OR and NOT.

Recipes

Copy any of these into the filter box and adjust the values.

Everything still in flight, at the epic and initiative level	`issuetype in (Initiative, Epic) AND statusCategory != Done`
The full tree for open work, stories included	`issuetype in (Initiative, Epic, Story, Task, Bug) AND statusCategory != Done`
Only items your team has flagged for the roadmap	`labels = roadmap AND statusCategory != Done`
Everything planned for upcoming releases	`fixVersion in unreleasedVersions()`
Open work, plus anything finished in the last quarter	`(statusCategory != Done OR resolved >= -90d)`

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 Jira rejects the query, the card turns red and shows Jira's own error message, with a link to Jira's syntax reference. Fix the query and run it again.

What you see in the preview is what imports.

What imports

Roadmaps have three levels, and Jira items land on them by their Jira hierarchy level:

Jira hierarchy level	Typical Jira issue types	ProductPlan level
Level 2	Initiative	Initiative
Level 1	Epic	Epic
Level 0	Story, Task, Bug	Story
Subtask level	Subtask, and any custom subtask type	Not imported

Parent and child relationships come across with the items. Levels above initiative (custom Jira Premium levels 3+) aren't supported.

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.

Getting what you need from Jira

The fastest way to a good query is to build it in Jira first, where autocomplete shows you the exact field names and values.

Open Jira's issue search. In Jira, go to Filters > Search work items (or Issues > Search, depending on your Jira version).
Build and test your filter, using Basic or JQL. Start typing a field name and Jira suggests matching fields and values. Check that the results look right.
Reuse a saved filter. If your team already has a Jira filter for its roadmap, open it and switch to JQL to see the query behind it.
Copy the query into ProductPlan without the project clause. Remove project = … or project in (…) from the start, and select those projects in the ProductPlan picker instead.

Troubleshooting

What you see	Why, and what to do
A project is missing from the picker	Only mapped projects are listed. Select Manage Project Mappings, or ask an admin to map it.
Run & Preview is disabled	Select at least one project.
The query card turns red with an invalid syntax message	Jira couldn't run the query. Read Jira's message below the card, fix the JQL and run it again. Testing it in Jira's issue search first often helps.
An error says the request failed	The query may be fine. ProductPlan couldn't reach Jira, so try again shortly.
Subtasks aren't coming in	Expected. Roadmaps go three levels deep, and subtasks sit below story level.
Tasks or bugs are coming in	Expected when your query matches them. They import at story level. Add `issuetype in (…)` to leave them out.
Items came in without dates	Check the date field mappings for that project in Manage Project Mappings.
An item you unlinked doesn't come back	Unlinked items go on the product's exclusion list, in Product Settings > Integrations, so sync doesn't bring them back. Remove a single item from the list, or select Remove All, and it returns on the next sync if it still matches.
An item is in the backlog but not on a roadmap	The backlog feeds roadmaps, but each roadmap chooses what it shows. Add the item from the roadmap's Backlog Items drawer, or adjust the roadmap's Data Selection.

FAQ

Can I import from more than one Jira project? Yes. Select as many mapped projects as you need in the picker.

Can the same Jira item be on more than one roadmap? Yes. Items belong to the product, and every roadmap in the product can use them.

Can I import into a roadmap directly? No. Imports now happen once per product, through this query, rather than per roadmap.

Who can unlink an item from Jira? Only the account owner. Unlinking leaves the Jira issue untouched.