Does the JIRA REST API require submitting a transition ID when transitioning an issue?

Question

If I POST an issue transition like this:

{
    "fields" : {
        "resolution" : {
            "name" : "Fixed"
        }
    }
}

...I get this error:

{
    "errorMessages" : ["Missing 'transition' identifier"],
    "errors" : {}
}

This seems to imply that I need to include a transition ID along with my list of changed fields. https://stackoverflow.com/a/14642966/565869 seems to say the same. Fine.

However, transition IDs appear to be global. It's not enough to look up the highest transition ID for this issue and increment it; such an ID is probably in use elsewhere. At some expense, I could get the highest transaction ID used anywhere in the system; this might be 68,000 at this moment. But if I were then to use transaction ID 68,001 there's a real chance that a GUI user would attempt a transition of their own and use this ID before I could.

I could use transaction IDs in the range of 1,000,001 and up, but if the JIRA web GUI uses the highest previously used transaction ID when generating new IDs I'll just collide in this range instead of the 68,000 range. I could use 69,000 and trust that there won't be a thousand transitions in the length of time it takes to get the highest transaction ID.

These both seem terribly clumsy, however. Is there no way to post a transition and let JIRA generate its own unique ID? I don't need to retrieve the generated IDs, I just want to update issues' statuses and resolutions.

Solution

You're getting mixed up a bit. So lets see if I can explain it better for you.

To transition a JIRA Issue, you use the Transition ID to identify what transition to apply to the issue. You aren't specifying an ID for a transaction or a transition ID to identify that the transition occurred, JIRA takes care of this for you.

The easiest way to understand it is to see it.

So first you can look at what transitions are available to an Issue by doing a GET to the API Call:

/rest/api/2/issue/${issueIdOrKey}/transitions

Example:

/rest/api/2/issue/ABC-123/transitions

Which will show something like this:

{
    "expand": "transitions",
    "transitions": [
        {
            "id": "161",
            "name": "Resolve",
            "to": {
                "description": "A resolution has been taken, and it is awaiting verification by reporter. From here issues are either reopened, or are closed.",
                "iconUrl": "https://localhost:8080/images/icons/statuses/resolved.png",
                "id": "5",
                "name": "Resolved",
                "self": "https://localhost:8080/rest/api/2/status/5"
            }
        }
    ]
}

So you can see only 1 transition is available for issue ABC-123 and it has an ID of 161.

If you were to browse to that JIRA Issue through the GUI, you would see only 1 Transition available and it would match the API Call. In fact if you inspected the element you should see it having an a tag and in the href something like action=161

So should you want to transition this issue, you'll need to do a POST to the following URL:

/rest/api/2/issue/ABC-123/transitions

With JSON like this:

{
    "update": {
        "comment": [
            {
                "add": {
                    "body": "Bug has been fixed."
                }
            }
        ]
    },
    "fields": {
        "assignee": {
            "name": "bob"
        },
        "resolution": {
            "name": "Fixed"
        }
    },
    "transition": {
        "id": "161"
    }
}

Which uses the transition ID found from the call that shows all transitions. I also update the resolution and assignee and add comments at the same time.

That make a bit more sense?

Comments

[Admin]

That does make sense, and would make things much easier! I only hesitate because when I query the history of issues using expand=changelog the transaction IDs appear to be sequential and ever-growing, currently around 70,000. I haven't verified that they're not being reused, though.

[Admin]

Drr, "transition IDs".

[Welsh]

Yep. Transition vs Transaction. However, transitions ID's would also be ever growing, but at a much slower rate. Whenever you modify your workflow and add a new transition, that new transition will get the next available transition id.