New Workflow REST APIs in Jira Cloud

Hi everyone,

I’m happy to announce that we’ve recently introduced two long-awaited REST resources for retrieving information about Jira Workflows, namely:

Read more about these two and the use cases they enable in our developer blog: Make work flow with the new Jira Cloud workflow APIs.

Looking forward to hearing your feedback. If you would like to see more features related to workflows, feel free to create new ACJIRA issues or describe it here.

8 Likes

Hi @kkercz,
this is great, thanks!
I have created [ACJIRA-1919] - Ecosystem Jira for an improvement: be able to get draft workflows as well.

2 Likes

Thanks for your suggestion, David. We will get to returning drafts eventually :slight_smile:

Meanwhile, we just added a new feature: a possibility to retrieve all rules (validators, conditions and post-functions) along with workflow transitions.

GET /rest/api/2/workflow/search?expand=transitions.rules

Example response:

{
  "maxResults": 50,
  "startAt": 0,
  "total": 1,
  "isLast": true,
  "values": [
    {
      "id": {
        "name": "Builds Workflow"
      },
      "description": "Builds Workflow",
      "transitions": [
        {
          "id": "701",
          "name": "Close Issue",
          "description": "Closing an issue indicates there is no more work to be done on it, and it has been verified as complete.",
          "from": [
            "5"
          ],
          "to": "6",
          "type": "directed",
          "rules": {
            "conditions": [
              {
                "type": "PermissionCondition",
                "configuration": {
                  "permissionKey": "CLOSE_ISSUES"
                }
              }
            ],
            "validators": [
              {
                "type": "connect.app.key__validator_key",
                "configuration": {
                  "value": "config as stored by the app",
                  "id": "UUID"
                }
              }
            ],
            "postFunctions": [
              {
                "type": "UpdateIssueStatusFunction"
              },
              {
                "type": "CreateCommentFunction"
              },
              {
                "type": "GenerateChangeHistoryFunction"
              },
              {
                "type": "IssueReindexFunction"
              },
              {
                "type": "FireIssueEventFunction"
              }
            ]
          }
        }]}
]}

Not all rules are fully supported in the initial release, which means for some we won’t be returning any configuration, just the type (which should still be fairly useful).

Fully supported rules at this time are:

  • All connect conditions, validators and post-functions
  • FieldRequiredValidator
  • PermissionValidator
  • UserPermissionValidator
  • PermissionCondition

Let us know if you would like to be able to retrieve full configuration of any other type of rules.

3 Likes

@kkercz why workflow search requires ADMIN app scope and not READ?

The very next set of endpoints is what I would expect:

https://developer.atlassian.com/cloud/jira/platform/rest/v2/#api-group-Workflow-transition-rules
GET /rest/api/2/workflow/rule/config (READ)
PUT /rest/api/2/workflow/rule/config (ADMIN)

I would prefer to avoid elevating app permissions just for read operations.

Another aspect that I find inconsistent, workflow statuses endpoint does not return any information about the workflow.

Hi @kkercz, would it be possible to return the configuration for all conditions, validators, and post-functions? I need to be able to export workflows and their rules into a human readable form outside of Jira. Currently all of this data is contained in the XML file but is a pain to deal with. If you could extend the GET /rest/api/2/workflow/search?expand=transitions.rules to include configuration for all the rules that would be wonderful. Otherwise is there another way to access the configurations of workflow rules via REST API for a single workflow?

Hi @kkercz, please can I request that the Step ID is also included in the response payload? We would like to create deep URL links from our addon UI into the Jira Workflow UI and we need a valid Step ID in order to do that.

Each transition may be associated with one or more steps in the workflow, see screenshot below.

Hi @jbevan, Thanks for the suggestion, we will consider adding this feature.
I created an ACJIRA issue, so it is possible to track the status of the request.
https://ecosystem.atlassian.net/browse/ACJIRA-2076

3 Likes

I’m afraid not. The thing with configuration is that it is implementation detail that we don’t want to expose just like that. The fact you can get it from the exported XML is an unintended side-effect of some legacy Jira functionality.

We might in time add support for more workflow rule configurations to the REST API response, but each rule’s configuration has to be manually reviewed and its shape carefully designed so that it becomes a proper API.

Hence, if you have any particular rules you would be interested in getting configuration of, do let us know and we will definitely prioritise them.

We consistently get a 403 response with errorMessage “Only Jira administrators can access workflow scheme associations” for one of our customers when calling /rest/api/2/workflowscheme/project. Our app has admin scope and the API call works for all the other customers (~1000).

Any ideas what might be causing this?

I am Jira server user, how to get the same jira workflow properties as in Jira cloud to the Jira server?
I need to get workflow id but this api doesn’t give me that. thanks

Dear @kkercz

We need standard workflow rules fully supported. For example the following rules only returns the type but we need the its configuration:

Postfunctions
{“type”:“UpdateIssueCustomFieldPostFunction”}
{“type”:“FireIssueEventFunction”}
{“type”:“CopyValueFromOtherFieldPostFunction”}

Conditions
{“type”:“InAnyProjectRoleCondition”}
{“type”:“ValueFieldCondition”}
{“type”:“InProjectRoleCondition”}
{“type”:“PreviousStatusCondition”}
{“type”:“InGroupCFCondition”}
{“type”:“UserInGroupCondition”}
{“type”:“SubTaskBlockingCondition”}

Validators
{“type”:“ParentStatusValidator”}

Could you implement this?

Thank you

1 Like

Hi @Eisonesoft.
Perfect timing to ask such a question. :grin:
I have a piece of good news for you. We are currently working on extending workflow API, so you can expect that it would be implemented during incoming weeks.

Hope you enjoy the update.
Regards,
Beata

4 Likes