Scope definition

The Scope definition screen has been redesigned. You may encounter small discrepancies between the content of this page and the actual state of the app. The changes don't have a functional impact.

Less frequently used settings have been hidden under "Advanced configuration".

A defined collection of tasks makes up the Box Scope. Tasks can be added to the scope manually or automatically synchronized with Jira or connected tools such as Trello.

In the Scope definition, you can specify what range of tasks is included in the scope of a given Box (or a sub-Box) - those are the tasks you will be able to work on in the Application (visualize them on a Gantt chart, manage Risks, distribute workload, etc.). The App gives you a lot of flexibility; you can include multiple Jira projects, simultaneously include tasks from different external tools (such as Trello and Jira), or include only some tasks that meet your particular specifications. The flexibility of the setup ensures that a Box can be configured to contain exactly the tasks you need to fit your work.

Box Types - different kinds of scope

A "Box type" contains the default settings applicable to multiple Boxes (all Boxes of a given type). Those settings are adjusted in Box type administration. Boxes can be created with different types of scope - those settings determine how a Box can be configured and what can be done when defining a scope.
There are three different options:
- Own-scope - the Box scope has a separate task structure and serves as a scope base for sub-scopes. Automatic rules can sync it. Use it when you want to define and extend the scope of a Box by selecting tasks from Jira and connected tools.
- Sub-scope - the Box scope is always a subset of the scope already defined at an upper-level of the Box hierarchy (the upper-level Box must have Own scope). It can be automatically synced with a value of a selected field.
- None - the Box scope cannot be defined. Currently, you can use such a Box to calculate respective aggregates in the Box hierarchy only (visible in the Overview module). Use this setting to organize Boxes into portfolios, programs, etc. The scope is always a sum of the scopes of the sub-Boxes in the Box hierarchy.
Box configuration refers to the settings of a single, individual Box. They are dependent on the "Box type" settings.

Security and access

The scope of an individual Box can be edited by:

a Box admin
Jira admin (every Jira admin has full access to the App and can edit the configuration of Boxes)
BigPicture admin (the role of App admin is granted in the App's drop-down > Administration > Security - every App admin can access and edit all Boxes in the App

Method 1: Box Configuration

Go to Box Configuration > Tasks > Scope definition.

Method 2: Gantt module

Add task > Manage scope definition

Method 3: Scope module

Add task > Manage scope definition

Method 4: Risk module

Add risk > Manage scope definition.

Depending on the Box hierarchy and the scope type of a given Box, the sections on the Scope definition page will differ (remember that every Box type has a Scope definition (Box types) settings). A Box with two levels of sub-Boxes will show all possible sections.

For example, the PI planning Box consists of three Program Increment sub-Boxes, which consist of Iteration sub-Boxes:

The tree levels in the Box hierarchy are reflected on the Scope definition page:

As the Program Increment Box type has the Scope type set to 'Sub-scope,' the Box admin can not define the scope for the sub-Box, and the screen shows the Iteration synchronization section only:

Scope definition elements

Scope of the context Box

The scope of the Box you're configuring can be managed at the top part of the page.

If the Box you're configuring has scope set to "own," you can define its elements at the top part of the page.

If the Box you're configuring has scope set to "sub-scope" at the top of the page, you will be able only to set synchronization rules.

Scope of the sub-Boxes

Scope information of Boxes nested under the Box you are currently configuring can be found at the bottom part of the page:

Depending on the scope type of a child Box, you will see:

When a child Box is set to be a "sub-scope," you will see synchronization rules
When a child Box has its "own" scope, you will be informed about it. The link in the message will take you directly to the configuration page for the relevant Box scope.
When a child Box functions as a portfolio and has a scope set to "none," you will see the following message:

Switching between levels of child Boxes

Using the arrows, you can switch between viewing the level of children and grandchildren of a given Box.

Basic info and status of child Boxes

You can check basic information about a sub-Box and change its status directly from the scope configuration page of a Box.

Own scope

Box admins can define the automatic rules to pull in tasks (from Jira or connected tools) or view and erase them from the scope manually. The quickest way to set up the scope is to use the automatic rules.

Automatic rules

Scope Owner

A Box can contain only the items the Scope Owner can access (viewing access is sufficient). If you try to add items the Scope Owner doesn't have access to, you won't save the scope successfully.

Scope Owner is listed as the first field in the "Automatic rules" section.

A Scope Owner doesn't have to be an actual user added to the Box in any capacity (doesn't have to be a Box Admin, Editor, or Viewer). Permissions of the Scope Owner user account within the external tool are the basis for the sync of tasks. Tasks will be pulled into the scope of a Box only if the Scope Owner can access them (at least as a viewer). For example, Angela is the Scope Owner in the BigPicture demo (Jira server instance name) and selected the PI Planning project as the scope of the "PI Planning (Smart house project)" Box. If there are tasks that Angela is not allowed to view in that project, those tasks can't be added to the scope of the Box.

When connecting with tools such as Trello, you need to specify the Scope Owner for each connection. This means that you cannot change the Scope Owner once a connection is established.

Suppose you set up a Jira user account called "BigPicture," and this user has at least viewing access to all projects. In that case, you can easily always list them as the Scope Owner (there is no danger of Box users getting access to things they shouldn't see - if a user can't view an issue in Jira, the item will be greyed out in the App). Users will never get access to Jira items they shouldn't view and modify. Suppose a user can't view and modify an item in the connected tool (because of insufficient permissions). In that case, they won't be able to do it using the App - BigPicture allows users to perform only the actions they can perform in the connected tool.

In general, user permissions should match (a user should have the same permissions in the BigPicture Boxes/Programs as they do Jira). You can read more on matching permissions on this page.

Scope filters

If your tasks are already created in Jira, you can define the scope using the following filters:

Boards - select from the list created Jira Board (Kanban and Scrum board)
JQL filters - select from the list of previously saved JQL filters
Projects - select from the list of available projects.

If you connect with Trello, you can only select Trello Boards:

You can select multiple items, which will increase the number of issues within the scope, as the "OR" operator is used for Board, Filters, and Projects.

Narrow down

The "narrow down" field lets you exclude items from the scope.

To narrow the scope, use the JQL box, which uses the "AND" operator in relation to the items listed above. This option applies only to Jira as there is no JQL in Trello.

Example:
To exclude resolved tasks from the scope, you can use the narrow-down option.

Manually Added Tasks

Tasks that do not match the automatic rules of scope definition (project/ board/ filter) are listed in the "manually added tasks" section.

This section remains hidden until needed - it is visible only when it contains at least one task.

Manually added tasks are the ones that do not fit the scope filter. For example, a user adds a new task using the "+" button in Gantt but creates a task in Project A, while the Box scope is defined as Project B:

Another example, a Box has two sub-Boxes with the scope type set to "Own." Sub-Box1 has the scope defined as Board 1 and sub-Box2 as Board 2. When a user moves a task from sub-Box 1 to sub-Box 2 using the Board module, the task will be added to the list of manually added tasks in sub-Box2.

The Box Admin can erase all the tasks in this section by clicking the "Eraser" icon.

Earlier versions of the App had a "Remove tasks, not in filter" feature, and all the tasks which do not fit the scope filters will be added to the "manually added task" list on this page.

For example, let's add risk to the 'PI Planning (Smart house project)' Box using the create task dialog but instead of the PI Planning project, select a different one - Risk register:

As a result, the risk is added to the board and appears in the Manually added tasks section:

Manually Removed Tasks

Manually removed task → task moved from one Box with scope type set to "Own" to another with the scope type also set to "Own."

Retired in BigPicture 8.5 and higher.

Moving a task between different own scopes is not possible - drag and drop is disabled on the Board module.

The manually removed tasks section was removed from the scope definition screen. Existing manually removed tasks are still in effect).

Example

Boxes (type = "Program") can be nested in a tree under each other (Administration > Box types > General > Basisc > parent types)
Each of these "Program" type Boxes has an "Own" scope.
ALFA Box scope = ALFA Jira project
BETA Box scope = BETA Jira project
In the Board module of the "Program Box used as a portfolio" tasks have been moved between Boxes ALFA and BETA

Task types

You can select which elements will be displayed as tasks and, when possible, synchronized with a connected tool (such as Jira).

Task types are added automatically when respective structure builders are activated. For example, enabling the Sprint structure builder will add the Sprint task.

Additional elements will be added as Basic tasks (since they don't exist as Jira issues/Trello Cards - they must be added in some form to be part of the task structure).

You can add the following Jira task types to the scope:

Project
Version (Start date and Release date can be synchronized)
Click here to expand...
Agile Backlog
Sprint (start date and end date of the Sprint can be synchronized)
Component

Note:
The 'Issues' Task Type is always automatically selected for Jira.

In the case of Trello, you can add the following:

Cards
Lists
Check Items
Boards
Check Lists

For example, you can display the Trello Lists just like any other task:

Columns (such as Icon, Key, Summary, etc.) display information based on selected field types. Make sure your column views have been configured to meet your business needs.

Sub-scope

The Boxes with sub-scope display the tasks already added to a higher-level Box with Own scope. Any task added to a Box with a sub-scope is automatically added to an upper-level Box with Own scope.

You can manually assign tasks to Boxes using the Board module.

You can use the field value synchronization to assign tasks to Boxes with a "Sub" scope. This means that when you add a new task while working with a sub-Box, you assign tasks to the upper-level Box.

There are three columns for each Box in the sub-Boxes section:

Name - this is the tool's name with source data, such as your Jira instance, or connected tool, such as Trello. Each instance consists of the unassigned and Team rows (Teams need to be allocated to a Box first).
Field - this is the field used to synchronize with Jira. You can use the following field types: String, Text, Select list (single choice) and Jira Epic Links.
Value - the field value used to identify a task in a given Box.

The only field types that can sync with a scope of a sub-Box are Sprint, Single-select, Epic Link and String fields.

When synchronizing with a "Sprint" field, the search only finds the given Sprint on the board where it was initially created. Remember to select the correct board using the filter before searching for a Sprint.

For example, the Iteration 2.1 sub-Box is configured to synchronize with the Sprint field, while Iteration 2.2 is not synchronized with any field.

Each Team can use a different Jira Board, and you can narrow the list of available sprint values by clicking on the 'funnel' button and selecting a Jira Board from the list:

Once the field value is selected, the Box is configured. Assigning a task to this Box will update the synchronized fields with the selected field value. Also, all tasks with that particular value will be added to the scope of that Box.

For example, Team Gamma uses a Scrum Board named "Team Gamma," and a sprint called (field value) 'Iteration 2.1 Team Gamma' is synchronized. When a task is assigned to Iteration 2.1, the sprint field is updated with the respective field value:

When the sprint values are changed to the next Sprint - 'Iteration 2.2 Team Gamma' (using the scrum Board or by editing the Sprint field directly) the PP-635 is moved to the next Iteration Box accordingly:

The PP-635 is now in Iteration 2.2:

Reusing a field value in multiple Boxes

You can reuse a field value (the same field value can be used for synchronization of more than one Box), but each time it should apply to a different set of tasks (see the example below).

Example:

There is a Jira project that contains a large number of tasks being handled by different teams. Teams have their respective Own scope Boxes in the App to organize work. The scopes of those Boxes were defined using filters → even though the tasks come from the same Jira project, the Boxes in the App don't overlap in their scope (tasks of each team are in their respective Boxes). Own scope Boxes have sub-Boxes. Those sub-Boxes are synced with a "Sprint" field - since sprints are created in Jira, it means that the same Sprint applies to all teams. The setup will work because even though the same "Sprint" field value is used multiple times (to sync sub-Boxes of different teams), different tasks are handled each time.

The warning message

When the App recognizes that the saved field values are already used in at least one sub-scope scope definition, you will see a warning message. If your setup meets the conditions above (different tasks are handled in each sub-Box), you can safely ignore the message. The sync will work typically.

If the App recognizes that a task is already in more than one Box with Own scope and there are "clashing" configurations within their Sub-scopes' definitions:

The sub-scope field sync is stopped for this task (existing values of sub-scope sync fields are not cleared);
A task cannot be replanned for another Box until the configuration is fixed (a task will be removed from the scope or a sub-scope mapping will be modified), and there is a respective warning displayed in the Board module for this task.

Limitations

You can't reuse a field value for "sub-scope" sub-Boxes of the same "own scope" Box. Otherwise, the App wouldn't be able to sort the tasks from "own scope" into sub-Boxes, because the same task can't be at the same time in multiple sub-Boxes.

Security roles in "Sub-scope" Boxes

Users of sub-Boxes with sub-scope can make any changes that match their permissions in a given sub-Box, even if they lack appropriate permissions to their own scope Box.

Those operations include:

Creating tasks
Adding tasks to own scope as manually added
Deleting tasks
Viewing tasks

For example:
If Angela is a Viewer in the Program-type Box ("Own" scope) but is an Admin in an Iteration sub-Box ("Sub" scope), she can execute all Admin operations on the Iteration tasks.

This means she effectively has Admin powers over some tasks from the Program-type Box.

Auto-configuration (next Timebox)

Timeboxes define consecutive timeframes used for work planning. It helps to think of them as, e.g., sprints, iterations, increments, or stages.

The toggle switch is visible only when the Sequentiality of a Box type = Sequential. When overlapping is allowed, the toggle switch doesn't appear.

Auto-configuration (the feature of BigPicture 7) no longer exists in its old form. The current simplified mechanism is described below.

You can configure each row separately, use the same value for each row or leave the fields empty.

Configuration of the next sequential sub-Box is based on its predecessor. No additional patterns are taken into account.

The App configures scope synchronization of sub-Boxes within a particular Box based on the last sequential, same-level sub-Box setup.

The "Next timebox template" toggle switch has to be activated.

Auto Sprint creation

When you create a new Timebox (such as Program Increment or Iteration), the App can create a corresponding sprint for you.

The auto-configuration option automatically configures the scope definition of newly added and existing but not configured Timeboxes and takes place once one of the following actions is performed:

a new Box is created,
a new team is allocated to a Box,
a Box sync field is updated, and a user saves settings

When the "Next Timebox template" is enabled, the only thing left is to create a new Box using the Overview module. To enable the auto-configuration, click the toggle button located on the sub-Box header:

And the new Box with the corresponding Sprint is created.

Sprint vs. Box duration

Sprint and Box periods are not synchronized or related in any way.

New Sprint vs. Existing Sprint Assignment

Synchronization of Sprints with Boxes works in two steps - if a Sprint already exists, it is synchronized with a newly created Box (a new Sprint is not created unless no matching Sprint has been found).

Toggle switch activation - when a new Timebox is created, the setup of the last existing Timebox will be used to create the next one:

1. The duration gets copied but is sequential (you can manually change it later)
2. The Box name is increased by +1
3. If the last Timebox was synchronized with a field, the App tries to find the next sequential one (for example, if the field was "Sprint" and the value was "Timebox Sprint 4" if the App finds "Timebox Sprint 5," it will automatically fill out the scope sync field).
  
  In the example, "Timebox Sprint 4" is already associated with "Program Increment5" (the last existing Timebox in the project). Two additional Sprints exist in Jira but haven't been associated with any Boxes yet.
  
  When a new Timebox is created ("Program Increment6"), "Timebox Sprint 5" will be automatically associated with it.
4. A new Sprint will be created if the App can't find the next Sprint (matching the previous Timebox).
  
  Note: This means that if you want to change the Sprint naming scheme, you have first to change a Sprint name in Jira and then associate it with the last Timebox. Otherwise, the App will ignore the existing Sprint with a name that doesn't match the previous Timebox, and a new Sprint that meets the specifications will be created.
  In the example below, "Sprint 7" existed in Jira, but didn't match the last Timebox Sprint field value, so the App created a new Sprint ("Timebox Sprint 7") that did.

Saving the scope

The App will validate the scope, and if errors occur, saving the scope will fail.

If you define the scope correctly (all tasks exist and the filters are not corrupted), the total number of tasks will be displayed.

You will not be able to save the scope if one of the following occurs:

at least one item in the scope definition is incorrect or doesn't exist (for example, JQL Query is incorrect, Scope Owner doesn't exist, added Project doesn't exist, etc.)

a total number of tasks is greater than the task limit set for Programs.

Duplicated Tasks

When a task is added manually and updated to fit the filter described in the Automatic rules section, it will be classified as a duplicate (alternatively, when the Automatic rules are updated and manually added task now fits the filtering criteria).

Refresh cache

The "Refresh cache" option on the scope definition page is available only on Jira Cloud.

The "Refresh cache" option is useful when you cannot find the project, board, or quick filters on the scope definition page. After pressing the "Refresh cache" button, the screen is disabled for 5 seconds. The option refreshes only projects, boards, and quick filters.

Scope Misconfiguration Errors and Warnings

While trying to save the scope, you might encounter the following warnings:

"X tasks in the scope. Synchronization may take a bit longer..."

The warning will appear if the task limit in Technical info is not defined or exceeds 25,000 tasks.

"Scope misconfiguration! A value with ID '10375' does not exist for the field 'id.' user: (...)."
In case of Scope Misconfiguration / Scope corruption, visit the following page for troubleshooting instructions.

The scope is corrupted:

a scope element (Jira project, filter, board) ceased to exist - JQL used to define Box scope leads to a deleted item
Scope Owner no longer has permission to access at least one of the scope elements.
Scope Owner is no longer active (the user account in the connected tool has been disabled)