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

Integration points

Scope definition

JQL Search Extensions helps to define a precise scope of BigPicture boxes.

You can source issues with:

• filters

• a narrowing JQL

It’s possible, for example, to have a box with a subset of initiatives or epics and their children.

Open

You will typically create the Extended Search filter for the board and reuse it in the box.

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

1. Create a filter in Extended Search

2. Wait for BigPicture to sync the filters list (see the note below)

3. Use the filter in BigPicture’s box configuration: Task → Scope Definition → Automatic Rules

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

Quick filters

You can use JQL Search Extensions aliases and filters in your BigPicture quick filters.

Create a quick filter that uses the JQL extensions:

Open

Use the quick filter that highlights the matching issues:

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

Quick search bar

You can use JQL Search Extensions aliases and filters in the quick search bar.

1. In the box view, click on the search loupe icon 🔍

2. Make sure the search is in the JQL mode - click on the ABC on the left to change the mode to JQL

3. Enter your JQL query

TIP: In JQL, You can refer to filters with filter="Your filter name".

External use

It’s a common requirement to access the contents of a box outside of BigPicture, 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 box.

You can create a box 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 Extended Search 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 box with selected initiatives and all their children.

Depending on how Initiatives are configured, you can use the following methods to source a subset of initiatives.

Parent Link (Advanced roadmaps)

If you use the Parent Link then go with 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'")

Link based hierarchy

If your initiatives are link based, go with the linkedIssuesOfQuery function and a nested filter:

1. Create an Extended Search filter:
   key in (INT-2, INT-5, INT-8) OR issue in linkedIssuesOfQuery("key in (INT-2, INT-5, INT-8)", "your initiative link name")
   and call it “My initiatives and epics”

2. Create another filter that is nesting a filter created in step 1:
   filter="My initiatives and epics" OR issue in childrenOfIssuesInQueryRecursive("filter='My initiatives and epics'")
   This filter matches:

   1. the selected initiatives and the linked issues (epics)

   2. all levels of children of the linked epics

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

Source issues linked to your project

You may want to create a box 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 Extended Searchfilter:

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 Extended Search 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 box configuration

Highlight the blocked tasks

Create a quick filter:

linkType="is blocked by"

You can now see what tasks are blocked by other tasks.

Highlight the tasks with a high number of dependencies

Create a quick filter with JQL:

linksCount>2

You can see the tasks that have a specific number of links. In this example, all the tasks with more than 2 links are going to be highlighted.

Highlight finished epics that have outstanding tasks

Create a quick filter with JQL:

type=Epic and status=Done and issuesInEpicToDoCount>0 or issuesInEpicInProgressCount>0

You can now see all the finished epics with tasks that need to be looked at.