This article describes the integration points and possible use cases of JQL Search Extensions with Advanced Roadmaps.

Integration points

Scope definition

JQL Search Extensions helps to define a precise scope of an Advanced Roadmaps plan. You can source issues with additional JQL keywords and https://jqlsearchextensions.atlassian.net/wiki/spaces/SEARCH/pages/1428357149 filters.

It’s possible, for example, to have a plan with a subset of initiatives or epics and their children. You will typically create the https://jqlsearchextensions.atlassian.net/wiki/spaces/SEARCH/pages/1428357149 filter for the board and reuse it in the plan.

Open

The process of creating the filter from scratch looks like this:

1. Create a filter in https://jqlsearchextensions.atlassian.net/wiki/spaces/SEARCH/pages/1428357149.

2. Use the filter in the plan configuration: Configure → Issue sources

Make sure to check out the examples in the use cases section on this page.

External use

It’s a common requirement to access the contents of a plan outside of Advanced Roadmaps, for example, to create a report in a 3rd party app or tool.

If you define the scope with Jira filter, you can use this filter in:

• dashboard gadgets

• boards

• Jira search - simply use this syntax filter="Your filter name"

• 3rd party apps that accept filters and JQL

Examples of use cases

Source a subset of epics with their full hierarchy

You don’t need to add a whole Jira project to the scope of a plan.

You can create a plan with selected epics and their stories and subtasks.

If you have a list of specific epic keys that should be in scope, create the following filter and use it as a scope:

key in (EPIC-2, EPIC-5, EPIC-8) OR issue in childrenOfIssuesInQueryRecursive("key in (EPIC-2, EPIC-5, EPIC-8)")

You can also choose epics that specify some dynamic criteria, for example, the epics with labels:

(type=Epic and labels='myFeature') OR issue in childrenOfIssuesInQueryRecursive("type=Epic and labels='myFeature'")

The above query could be limited to one project or it can source the issues from multiple projects.

Source a subset of initiatives with their full hierarchy

This use case is similar to the previous use case with epics. You can create a plan with selected initiatives and all their children.

Use the childrenOfIssuesInQueryRecursive function:

key in (INT-2, INT-5, INT-8) OR issue in childrenOfIssuesInQueryRecursive("key in (INT-2, INT-5, INT-8)")

Or with more complex criteria:

(type=Initiative and labels='myVision') OR issue in childrenOfIssuesInQueryRecursive("type=Initiative and labels='myVision'")

Source issues linked to your project

You may want to create a plan with issues from your project and external issues that are linked to your project.

You can create a filter:

project=MYPROJ OR linksIssueProject=MYPROJ or linkedByIssueProject=MYPROJ

If you only want to include the issues linked with the particular link type, you can create an filter:

project=MYPROJ OR issue in linkedIssuesOfQuery("project=MYPROJ", "is blocked by")

You can also get a full hierarchy of the linked issues by creating a nested filter:

1. Create an filter:
   issue in linkedIssuesOfQuery("project=MYPROJ", "is blocked by")
   and call it “Blockers”

2. Create another filter that nests the first filter:
   project=MYPROJ OR filter="Blockers" OR issue in childrenOfIssuesInQueryRecursive("filter='Blockers'")

3. Use the filter as your scope in the plan configuration