Make work flow with the new Jira Cloud workflow APIs

Reading Time: 2 minutes

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 Cloud enabled apps to provide custom workflow post-functions, but that was the only extensible part of workflows. We’ve now launched two new Connect modules for other types of workflow rules to let apps unleash the full power of Jira workflows. The following set of workflow extension modules are now available:

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):

(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.