When we see an item aging unnecessarily in the data, one of the first questions I ask is “is the issue even visible on the board?” If it isn’t then I think we immediately understand why we’re ignoring it. “Out of sight, out of mind” is a very real thing.
So you’re thinking “how can I tell if it’s visible on the board?” and that’s more complicated than you would think.
If you only care about whether it’s on the board right now then there’s an API for that.
GET /rest/agile/1.0/board/{boardId}/issue
Unfortunately, if you need historical data, as I do, it’s much messier.
Kanban board in a company-managed project
If we’re looking at a Kanban board in a company managed project then it’s pretty straightforward. We look at the board details to see all the visible columns and from there, we find the statuses mapped to each of those columns. If the issue is in one of those statuses, it’s visible.
The only gotcha here is that we have to look at status ids, not status names because we might have multiple “In Progress” statuses and the one mapped to the board may not be the one in the issue. I’ve seen cases where a single issue has historically been in four different statuses all called “In Progress”, and only one of those is mapped to the current board.
Scrum board in a company-managed project
For a scrum board in a company-managed project then the issue will be visible on the board if the statuses map in the same way as for kanban above AND this issue is in a currently active sprint. Not just “in a sprint”, it must be in a sprint that is currently active.
A team managed project with sprints enabled
If it’s in a sprint then it’s eligible to be on the board but still must be mapped to a status that’s on the board.
A team managed project with sprints not enabled
This is the case where the board behaves mostly but not entirely like a kanban board in a company managed project.
The status mappings are the same as the kanban described above. What’s different is that the issue must also have been moved to the board in the backlog view. It’s easy to tell in the UI if it’s been moved, but that information is not exposed in the API.
When you drag the issue upwards in the UI, we do get a Ranked higher entry put into the history, but that does not tell us if it was moved out of the backlog to the board or just higher in the backlog.
So how can we tell if it’s visible? We can’t.
In a team managed project with sprints not enabled, there is no way to tell if the issue had been visible. The best we can do is call the API at the top to see if it’s currently visible.
This is unfortunately not too surprising. Team-managed projects seem to consistently be an afterthought, and that’s one of the reasons I suggest that people avoid them.
Other articles about the Jira API:
See also the JiraMetrics tool, which is the reason I’ve had to learn the idiosyncrasies of the Jira API. If you just want access to the data then let JiraMetrics do it for you.