Next we’ll look at the API to get information about a board. Boards are fundamentally broken, in my opinion, because they aren’t a real thing in Jira. They’re a view into issues at a point in time, which means that they don’t show up anywhere in the history. You can’t tell what board an issue was on when a status change happened, and you can’t assign an issue to a board.
It also makes it almost impossible to create a workflow where a single issue moves from one board to another unless you go out of your way to ensure that the statuses are unique on each board. While that is theoretically possible, it would be time consuming and tedious and I’ve never seen it on any of the hundreds (thousands?) of boards I’ve worked with. What I have seen fairly regularly is that teams will close an issue when it gets to the far right of one board and will then clone that ticket in order to move it to the next board. This simulates a single ticket moving across boards but adds extra overhead and now makes it harder to track the overall flow because we’re talking about different issues at different times.
Understanding all of that, when we look at the API, we need to lower our expectations. All it can return is some meta data about the board itself and can’t provide any information about history or which issues have moved through it.
This API is specific to the Agile portions of Jira, which means it will only work for a software (ie agile) project and not for a core project. Boards in core projects don’t have ids and cannot be found through the agile API’s.
Thanks to Oliver Oyston for helping me figure out the subtleties between core and software projects.
If you’re in a software project in Jira then the API is mostly obvious although as I’m sure you’ve learned by now, all Jira API’s have their own surprises.
This API will retrieve information about the board.
/rest/agile/1.0/board/<BOARD_ID>/configuration
Note that this is a v1 API. There is no equivalent in either the v2 (production) or v3 (beta) API’s. Does that imply that board access will be phased out? It’s unclear.
There are only a couple of things I care about from this call.
- Board name
- Board filter so I can execute the same query that this board would call.
- Board type (kanban or scrum) so I know whether to ask for sprint data and also how I treat backlog statuses (see below)
- Columns for both the names and statuses in each column.
- Sometimes it returns information about the project - see below.
There is some other information but largely I ignore all of that.
{
"name": "Scrum Team X",
"type": "scrum",
"location": {
"type": "project",
"key": "SP",
"id": "10000",
"name": "Sample Project"
},
"filter": {
"id": "10001",
},
"columnConfig": {
"columns": [
{
"name": "To Do",
"statuses": [
{
"id": "10000",
}
]
}
]
}
}
In this example, there can be multiple columns and multiple statuses under each column.
An interesting point is that unlike other API’s, all we have for status is the id and not the name. If we want to map that back to a status name, we have to call a different API. See the Status API
For a scrum board, every column that you see in the returned call will correspond to an actual column on the board. For a kanban board, there is one extra column inserted at the beginning that represents the backlog.
In the example below, the column called “Backlog” is fabricated and represents those statuses that are Backlog. While I can’t find this documented anywhere (meaning it could change without notice), that backlog column seems to always be called Backlog and is always the first column.
If you happen to have another visible column on your board that you have chosen to call Backlog then you’ll now have two Backlog columns and the only way to tell them apart is the position. If it’s the first column, then it’s the fabricated one and won’t be visible and if it’s anywhere else in the list, it’s yours and will be visible.
Again, this is unique to Kanban boards. If you’re calling this for a Scrum board, it will only return visible columns.
{
"type": "kanban",
"columnConfig": {
"columns": [
{
"name": "Backlog",
"statuses": [
{
"id": "10012",
}
]
},
{
"name": "To Do",
"statuses": [
{
"id": "10000",
}
]
}
]
}
}
As I’ve mentioned before, we often want to know when an issue was moving across a specific board but the data model doesn’t support that. There is no way to ask an issue what board it’s on or what board it had been on at a certain point. Since I often need to do that mapping, I’ve found a hacky way to establish that mapping.
From the board details above, I can get the board filter. From that, I can query against the filter to find out what issues are on that board right now filter = 2. Then as I download each issue, I track what board I had found it on and I use that as my mapping.
The complication is that multiple boards may return the same issue and there is no way of knowing when an issue has moved from one board to another. So it’s not perfect but is often useful enough.
As mentioned above, sometimes it will return a location section which gives us information about the project - most importantly the project id. My test instance in Cloud returns this and I’ve verified that at least one instance of Data Center does not so I can’t say conclusively when it will be present and when it won’t. Apparently location has been a mandatory field when creating boards since 2018. What little documentation I have found, says that location can either be a project or a user but I have no understanding of how a user makes sense in this context. Can I create a board for myself that doesn’t belong to a project?
{
"location": {
"type": "project",
"key": "SP",
"id": "10000",
"name": "Sample Project"
}
}
Other articles about the Jira API: