Workflows are at the heart of Jira, governing everything that happens with issues. Over the last few months, we've been working hard to bring the full power of workflows to apps and integrations. This post provides an overview of all the new APIs that were recently added.
(Note that all of this applies only to workflows for classic projects. Next-gen projects will receive their own set of dedicated APIs in due time.)
New types of custom workflow rules
For a long time, Jira
But there is more. We've also created a new REST API for managing workflow rule configurations, to give apps full control over their extensions. You can now retrieve the configuration of all your rules added to workflows, and even update it at runtime, without any interaction on the user side required.
The new resources are (click the links to go to the documentation):
- GET /rest/api/2/workflow/rule/config (Get workflow transition rule configurations)
- PUT /rest/api/2/workflow/rule/config (Update workflow transition rule configurations)
(By the way, if you're wondering what a "workflow rule" is: we are using it as an umbrella term for different types of workflow elements: conditions, validators and post-functions.)
Retrieving workflows
Getting a list of transitions available for a given issue or project is a common requirement, however, for a long time it was not easily achievable. This changes now with the new workflow search resource, which allows you to retrieve any Jira workflow, along with its transitions, statuses, and even status properties (so that you can check if an issue is editable in the given status).
See the full documentation here: GET /rest/api/2/workflow/search (Get workflows paginated).
Finding workflows associated with projects
Even the best API for retrieving workflows would be useless if you couldn't connect workflows with associated projects and issues types. Hence, we prepared a new API to retrieve workflow schemes for a given set of projects.
Read about it here: GET /rest/api/2/workflowscheme/project (Get workflow scheme project associations).
Putting it all together
As an example, let's see how to get all transitions for a given issue.
First, get workflow schemes for the issue's project by calling:
GET /rest/api/2/workflowscheme/project?projectId=<projectId>
This returns a list of workflow schemes associated with the provided project, so in this case just one entry, for example:
{
"values": [
{
"projectIds": ["<projectId>"],
"workflowScheme": {
"id": 101010,
"name": "Example workflow scheme",
"description": "The description of the example workflow scheme.",
"defaultWorkflow": "jira",
"issueTypeMappings": {
"10000": "scrum workflow",
"10001": "builds workflow"
},
"self": "http://your-domain.atlassian.net/rest/api/2/workflowscheme/101010"
}
}
]
}
Now, we need to check what type our issue is, and get the correct workflow.
Let's say the type of our issue has ID 10000. We can see in the issueTypeMappings property value of the workflow scheme object, that the workflow used by the issue type is named "scrum workflow".
We can now retrieve this workflow along with its transitions by executing the following request:
GET /rest/api/2/workflow/search?workflowName=scrum workflow&expand=transitions
Have feedback?
We believe the new workflow API is already fully viable and has enough features to cater for most use cases, but we are still looking forward to hearing your feedback. This is why we keep the new resources marked as "experimental".
Let us know what you think on our community forum.