Summary

Without being granted the correct project permissions, some Jira users will not be able to Manage a Sprint from an Agile board, meaning that they won't be able to perform the actions listed below:

• Creating sprints
• Starting sprints
• Completing sprints (=Closing sprints)
• Reopening sprints
• Reordering future sprints in the backlog
• Deleting future sprints from the backlog
• Editing sprint name and/or start/stop dates
• Moving the sprint footer

One of the consequences of this issue is that the Complete Sprint button will be greyed out for them, and when hovering over the button, the following message will pop up:

You need the "Manage Sprints" or "Start/complete sprints" permission for all projects in the origin board to manage this sprint.

Environment

Jira Software Server / Data Center on 7.0.0 and any higher version.

Context around this knowledge base article

As explained in the official documentation Using Manage Sprints permission for advanced cases, for a user to be able to complete sprints, this user needs to be granted the Manage Sprints permission within all the projects associated the board where the Sprint was originally created (this board will be referred to as the origin board).

The projects associated to the origin board are defined by the JQL query configured for the board in Board > Configure > General > Filter Query

• When a JQL query is simple and explicitly filters issues by projects, the board is able to determine which project(s) will be involved in that query (and therefore the board). In such case, all you have to do is ensure that the users are granted the Manage Sprints permission for all these projects.
• However, when a JQL query is too complex (or contains some OR conditions which don't specify specific projects), the board is no longer able to identify the list of projects involved. In such case, it will be required for the users to be granted the Manage sprints permission across all the projects within Jira.

The problem with the documentation is that it does not provide the exact steps on:

• how to identify the origin board of the Sprint that can't be completed and its JQL query
• ultimately, how to fix the Jira configuration (project permissions, JQL query...) when a user is unable to complete a Sprint

The purpose of this knowledge base article is to provide detailed steps to troubleshoot the most common scenarios where a user is unable to close a Sprint, their root causes and resolutions.

Diagnosis

Step 1 - Identify the origin board of the Sprint

First, we need to identify the board from which Sprint was created (referred to as the origin board). Since it is not possible to get this information from the Jira UI, we need to use the following SQL query:

PostgreSQL database:

select R."NAME" as BoardName, R."ID" as BoardID, S."NAME" as SprintName, S."ID" as SprintID
from "AO_60DB71_RAPIDVIEW" R
join "AO_60DB71_SPRINT" S on R."ID" = S."RAPID_VIEW_ID"
where S."NAME" = 'SPRINT_NAME';

Other database:

select R.NAME as BoardName, R.ID as BoardID, S.NAME as SprintName, S.ID as SprintID
from AO_60DB71_RAPIDVIEW R
join AO_60DB71_SPRINT S on R.ID = S.RAPID_VIEW_ID
where S.NAME = 'SPRINT_NAME';

 Notes:

• Make sure to replace <SPRINT_NAME> with the name of the Sprint
• The SQL query above was built and tested for a PostgreSQL database. If you are using any other type of database, you will need to remove all the double-quotes around the table and columns names, and you might also need to specify a schema (especially for MS SQL databases)

This SQL query will return the name and the ID of the board that the Sprint came from, as well as the name and the ID of the Sprint.

Example of SQL query and output below. This query is telling us that the sprint "Sprint with SCRUM1 issues" was originally created from the Board ID 7 with name "SCRUM1 board"

select R."NAME" as BoardName, R."ID" as BoardID, S."NAME" as SprintName, S."ID" as SprintID
from "AO_60DB71_RAPIDVIEW" R
join "AO_60DB71_SPRINT" S on R."ID" = S."RAPID_VIEW_ID"
where S."NAME" = 'Sprint with SCRUM1 issues';

  boardname   | boardid |        sprintname         | sprintid 
--------------+---------+---------------------------+----------
 SCRUM1 board |       7 | Sprint with SCRUM1 issues |        5
(1 row)

Step 2 - Identify the projects involved with the origin board

To identify for which projects the Manage Sprints permission needs to be granted to users (in order to complete the Sprint), we need to identify which projects are involved with the origin board.

To check which projects are involved in a board, you can go to the board configuration in the UI via the page Board > Configure > General and check the Projects in board field (which is calculated based on the JQL query defined in the Filter Query field). For example:

• if the JQL query explicitly filters issues by specific projects, then only these projects will be involved in that board:
  
• if the JQL query does not explicitly filter by specific projects or if the JQL is too complex, then the message The projects in this board cannot be listed because of the complexity of the board filter will be displayed, which means that all the projects in the entire Jira instance will be involved in that board:
  

Another way to get the JQL associated to the board by running the SQL query below:

select SR.* from searchrequest SR
join "AO_60DB71_RAPIDVIEW" R on SR.id = R."SAVED_FILTER_ID" 
where R."ID" = <BOARD_ID>;

 Notes:

• Make sure to replace <BOARD_ID> with the ID of the board found in the previous SQL query
• The SQL query above was built and tested for a PostgreSQL database. If you are using any other type of database, you will need to remove all the double-quotes around the table and columns names, and you might also need to specify a schema (especially for MS SQL databases)

Step 3 - Fix the JQL query associated to the board, or the project permissions

Once you have identified the projects involved in the origin board, then there are various ways to fix the issue, depending on the situation:

• If the origin board is using a simple JQL query which involves specific projects, then all you have to do is grant the Manage Sprints permission to the user who can't complete the Sprint in all these projects. You can refer to the documentation Managing Project Permissions for more information on how to do it
• If the origin board is using a complex JQL query (which does not filter specific projects), then you have 2 options:
  • Ideal option: simplify the JQL query, so that it only filters specific projects and then grant the Manage Sprints permission to the impacted users for these projects only
  • Less ideal option: leave the JQL query as is, and grant the Manage Sprints permission to the impacted users in all the Jira projects

Most common root causes

This section lists the most common scenarios where a user is unable to complete a Sprint.

Root Cause 1 - The origin board is different from the board where the Sprint is displayed

A very common scenario is the following:

• A sprint is showing in a board (let's call it SCRUM2 board)
• The board the sprint is showing in is using a JQL query involving 2 projects SCRUM1 and SCRUM2
  
• A user is unable to complete the sprint (the button is greyed out) even though this user has the Manage Sprints permission in both projects SCRUM1 and SCRUM2:
  
• When following the diagnosis steps from the Diagnosis section, it was identified that the Sprint actually came from a different board, which is associated to different projects (SCRUM1 and SCRUM3):
  

Root Cause 2 - The JQL query associated to the origin board is too complex

For this scenario, we have already identified the origin board and the JQL associated to it. Based on the JQL query, it "seems" that only specific projects should be associated to it and therefore the Manage Sprints permission "should only be necessary" for these projects. However, in the board configuration page, the Projects in Board field shows the following message:

The projects in this board cannot be listed because of the complexity of the board filter

Below is an example of JQL query considered complex, and triggering that message:

project = SCRUM1 AND issuetype = story OR priority = low ORDER BY Rank ASC

When a JQL query is using both the AND and OR operators, if no parenthesis is used, the AND operator takes priority over the OR operator. Taking the JQL query in the example above, it is basically equivalent to using the JQL query below (the parenthesis are implicitly surrounding the elements around the AND operator):

(project = SCRUM1 AND issuetype = story) OR priority = low ORDER BY Rank ASC

In other words, the JQL will look for:

• any issue from SCRUM1 project and from the story type
• any issue from any project in the entire Jira instance, which priority is low

In such case, the JQL query is considered as too complex, and the Manage Sprints permission will be required in all the projects of the entire Jira instance.

Root Cause 3 - the JQL query from the origin board is referring to a project which name is the same as the key of a different project

When a JQL query uses the syntax "project = ABC", such query will:

• look for issues coming from the project with key ABC as a priority
• if there is no project with key ABC, then the query will search for issues coming from the project with name ABC

Because of this search logic, if there is 1 project which key is ABC and 1 project which name is ABC, the JQL query will only search for issues coming from the project which key is ABC.

As a result, if you have multiple projects in Jira and 1 project has the key ABC and another project has the name ABC, using the JQL query "project = ABC" will lead to some unexpected behavior, since Jira will search for issues only in 1 of these 2 projects.

Let's assume that there are 2 projects in the Jira instance with "conflicting" names and keys:

• 1st project:
  • with name: "OS"
  • with key: OTHERSCRUM
• 2nd project:
  • with name: "OTHERSCRUM"
  • with key: OTH

When using the JQL query below, Jira will search for issues that belong to the 1st project, since it is the one which has the key OTHERSCRUM:

project = OTHERSCRUM

As a result, if such JQL query is associated to an Agile board, Jira will expect users to be granted the Manage Sprints permission in the 1st project, instead of the 2nd project, which will explain why some users can't complete sprints if such users were only granted the Manage Sprints permission in the 2nd project.

Root Cause 4 - the JQL query from the origin board is referring to an archived project

If the origin board of a particular Sprint is configured with an archived project, users will not be able to manage that Sprint from any board the Sprint is showing on (even if the users were granted the Manage Sprints permission within that project).

This behavior is caused by a bug which is described in details in the public bug JSWSERVER-21688 - Getting issue details... STATUS .

Solution

Solution for Root Cause 1

To fix the issue, you will need to grant the Manage Sprints permission to the user within the projects involved in the origin board.

Solution for Root Cause 2

• Solution 1 (ideal):
  • fix/simplify the JQL query, so that it only filters specific projects and then grants the Manage Sprints permission to the impacted users for these projects only

  • taking the JQL query from the example in Root Cause 2, one way to fix it so that it explicitly filters specific projects, it could be modified by adding parenthesis as shown below:

    project = SCRUM1 AND (issuetype = story OR priority = low) ORDER BY Rank ASC

• Solution 2 (less ideal):
  • leave the JQL query as is, and grant the Manage Sprints permission to the impacted users in all the Jira projects

Solution for Root Cause 3

To fix the issue, fix the JQL query to remove any ambiguity as to which project is actually used. To do that, make sure to specify the project key in the JQL query instead of the project name:

project = <PROJECT_KEY>

Solution for Root Cause 4

Please refer to the workarounds listed in the bug JSWSERVER-21688 - Getting issue details... STATUS .