Scope definition
- Anna Ciepłota
- Piotr Koszela
- Magdalena Żaczek
Introduction
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 App (visualize them on a Gantt chart manage risks, distribute workload, etc.). 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.
Less frequently used settings have been hidden under "Advanced configuration".
Box types
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.
Box configuration refers to the settings of a single, individual box. They are dependent on the "Box type" settings.
There are three different options:
Own scope - the box scope has a separate task structure and is 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.
Example: A sub-scope box may be a parent when the box type is SAFe® Agile Release Train (ART). This box type comprises three levels of boxes, and the following structure is possible:
First-level box: own scope
Second-level box: sub-scope
Third-level box: sub-scope
The second-level sub-scope box is a parent for the third-level box, but the first-level box is always set to own scope).None - the box scope cannot be defined. Currently, you can only use such a box to calculate respective aggregates in the box hierarchy (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.
You can’t manage the scope definition in portfolio boxes (none scope boxes). The Manage scope definition feature and the Scope definition page in the box configuration are unavailable.
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, the sections on the Scope definition page will differ (remember that every box type has a scope definition settings). A box with two levels of sub-boxes will show all possible sections.
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 modify the scope definition details at the top of the page.
If the box you're configuring has scope set to "sub-scope", you can modify the 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:
Switch 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.
Manually added tasks
This option displays tasks that exist in the box but were not included by the automatic rules outlined in the previous section. These task might have been added manually or they are present here unintentionally. If you would rather to keep in the box only tasks chosen by automatic rules, you can:
move the tasks from this section to the right project (chosen in the previous section)
modify the automatic rules in the previous section to also include the tasks from the manually added task
click the x next to a specific task to exclude it from the scope.
Save the scope
The App validates the scope. Saving the scope fails if errors occur.
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.)
Private filters are used - the App doesn’t detect private filters.
The total number of tasks exceeds the task limit set for boxes.
Update the scope
When you update the scope definition, the synchronization will be performed in the background. You can track the progress once you click on the box icon in the top left corner.
In a new window, you can see the synchronization status in detail. To implement changes, click "Manage scope definition".
Once you save changes, the synchronization stops and starts again from the beginning for the new scope.
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 the manually added task now fits the filtering criteria).
Refresh search list
The "Refresh search list" option on the scope definition page is available only on Jira Cloud.
The "Refresh search list" option is useful when you cannot find the project, board, or quick filters on the scope definition page. After pressing the "Refresh search list" 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 Scope Misconfiguration - Corrupted Scope 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
A scope owner no longer has permission to access at least one of the scope elements.
A scope owner is no longer active (the user account in the connected tool has been disabled)