Help with Workflow Scheme Draft Publish REST API

Jira Development Jira Cloud
1

I’m trying to modify workflow scheme via REST API.

First I create a draft with:
/rest/api/3/workflowscheme/10033/createdraft
(no POST data)
Which is successful.

Then I tried to publish it (without changing anything):
/rest/api/3/workflowscheme/10033/draft/publish
POST data:
{
“statusMappings”: []
}

Which returned 401. I’m using the same connection as create draft, so it’s not possible that I didn’t use the correct email/API token.

After the 401, I checked the web and noticed the draft is gone.

According to the documentation, 401 should only be returned for authentication errors. What’s happening here?

2

Hello @KCWongIGSL

The POST request to the Publish draft workflow scheme endpoint failed because the request Body was invalid.

You didn’t provide values for the required issueTypeId, newStatusId and statusId parameters inside the statusMappings array.

Refer to the documentation.

3

But shouldn’t that be 400 according to the documentation, and why does the draft disappear afterwards?

I’m trying to restore a workflow scheme from a custom-made backup. It’ll be difficult to come up with the mappings programmatically…

I can instead create a brand new workflow scheme, and I notice the REST API to change a project’s workflow scheme (/rest/api/3/workflowscheme/project) doesn’t seem to need a status mapping… how’d that work?

4

But shouldn’t that be 400 according to the documentation, and why does the draft disappear afterwards?

I have no idea why.

Why not just fix the mistake in the request first, see if it works as expected, then worry about why the endpoint gave you an error message that doesn’t match the context.

5

Mainly because I don’t have a solution to come up with the status mappings yet.

6

Hey just, want to add that you are better off using the Update workflow scheme API to update a scheme. This API doesn’t need drafts. There’s also an API that goes with it that gives you info for the required mappings. I recommend having an explore of those APIs.

8

I see that API now. Though it is still difficult to make that decision automatically for users. I will most likely just create a draft and have the user publish it and perform the status mapping manually.

BTW, a complaint: the REST APIs have split personalities.

The site backup XML contains three identifiers for a workflow: id (numeric), name (text) and entity_id (UUID-like).

The old APIs (like /rest/api/3/workflow) only give you the name, no id, no entity id.

The new APIs (like /rest/api/3/workflows/search) give you the name and “id” which is entity id.

The update wf scheme API (/rest/api/3/workflowscheme/update) you told me about, wants “workflowId” which is entity id.

But the API to get the mappings (/rest/api/3/workflowscheme/update/mappings)? It wants “workflowId” which is the numeric id.

Edit2:

The get mappings API just keep giving me 400. It only says invalid but not what is invalid, kinda hard to debug this way.
Payload:

{
“id”: “10033”,
“defaultWorkflow”: “10133”,
“workflowsForIssueTypes”: [
{
“issueTypeIds”: [“10006”],
“workflowId”: “10133”
}
]
}

Edit 3:

The API wants workflow entity id, the documentation is wrong. And I have to omit defaultWorkflow, and include all issue type IDs (this one it will tell you about in the error message).

1 Like
9

Oh, I appreciate the complaint. Time is our enemy around most of this stuff.

Looking at those docs we should have used better ‘example’ values.

We’ve only got through:

One day we’ll get time to make the rest consistent for workflow schemes.

With the site backup XML, there’s a programme to deprecate it. The XML is mostly for debugging and the new get/create/update workflow APIs should be better for most workflow management needs.

On workflows APIs we put out notice for deprecation on a bunch of them recently so we can make them more consistent there at least. We’ve got a few left to do.

10

Oh, Just to add with default workflow.

For team managed projects (TMP) we don’t allow it. For company managed projects (CMP) it is optional.

You use default workflows to specify which workflow will be used if you don’t have a specific mapping. So if someone slaps in a new issue-type into a project and doesn’t setup their scheme it will use that. If it isn’t set the system uses the default ‘jira’ workflow.

If you change any workflow mapping you need to supply mappings IF there’s any situation where the status ids end up being removed. That is regardless of whether you have issue or not. That’s to ensure that we have instructions to correctly update issues that might be created or transitioned while the process is running using a temporary workflow.

11

More inconsistencies:

Get workflow scheme (/rest/api/3/workflowscheme/{id}) does not give you a version (DocumentVersion).
Update workflow scheme (/rest/api/3/workflowscheme/update) requires version.
Only bulk get workflow schemes (/rest/api/3/workflowscheme/read) will give you the version.

Others problems I observed before:

Dashboard REST APIs do not have the ability to change dashboard layout (1/2/3-column). They all get defaulted to 2.

1 Like
12

Hit a new problem using workflow scheme update API (/rest/api/3/workflowscheme/update)…

The documentation says only these are required:
id
name
description
version

I’m trying to update a scheme’s name and description, so I send exactly that:

{
“name”: “Jira Service Management IT Support Workflow Scheme generated for Project UT2 (migrated)”,
“description”: “This Jira Service Management IT Support Workflow Scheme was generated for Project UT2 (Migrated on 6 Sep 2024 08:38 UTC)”,
“id”: “10033”,
“version”: {
“versionNumber”: 100,
“id”: “83bc697b-6868-4430-af02-6cb4ba23646d”
}
}

Version is from /rest/api/3/workflowscheme/read.

But server responded 400. I’m guessing it wants the status mappings too.

13

Ahhh, the API is declarative, so you need to pass in the full scheme. This is one of the other main differences with this API.

You might wonder why. It’s because we’re trying to move away from this pattern of having lots of little API’s for these config entities that update one field. That often leads to race conditions.

So you get the scheme, typically mutate the payload, then post it back. If the version changes you will get a conflict. If something else is already running a long running scheme update you’ll get a conflict too.

There’s a migrationId inside the workflow scheme response that you can use against the Task API to track progress too.