Using REST to set fixVersions

[mrytikov]

I try to use REST API v2 to set a single specific fixVersion to an issue.

I used the example from here: https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-issueidorkey-put

>>> url = 'https://company.atlassian.net/rest/api/2/issue/ISSUE-123'
>>> auth = ('user@company.com', 'Token')
>>>
>>> headers = {
... "Accept": "application/json",
... "Content-Type": "application/json"
... }
>>>

Initial state:
>>> fix_versions = requests.get(url, auth=auth, headers=headers).json()['fields']['fixVersions']
>>> print([fv['name'] for fv in fix_versions])
['Future', '3.1_hotfix', '3.2']
>>>

Use set to update fixVersions; nothing happens:
>>> payload = json.dumps({'update': {'fixVersions': [{'set': [{'name': 'Future'}]}]}})
>>> requests.put(url, auth=auth, headers=headers, data=payload)
<Response [204]>
>>>
>>> fix_versions = requests.get(url, auth=auth, headers=headers).json()['fields']['fixVersions']
>>> print([fv['name'] for fv in fix_versions])
['Future', '3.1_hotfix', '3.2']
>>>

Remove another fixVersion; nothing happens:
>>> payload = json.dumps({'update': {'fixVersions': [{'remove': {'name': '3.1_hotfix'}}]}})
>>> requests.put(url, auth=auth, headers=headers, data=payload)
<Response [204]>
>>>
>>> fix_versions = requests.get(url, auth=auth, headers=headers).json()['fields']['fixVersions']
>>> print([fv['name'] for fv in fix_versions])
['Future', '3.1_hotfix', '3.2']
>>>

Set the fixVersion using 'fields' instead of 'update'; fixVersion is removed instead of set:
>>> payload = json.dumps({'fields': {'fixVersions': [{'set': [{'name': 'Future'}]}]}})
>>> requests.put(url, auth=auth, headers=headers, data=payload)
<Response [204]>
>>>
>>> fix_versions = requests.get(url, auth=auth, headers=headers).json()['fields']['fixVersions']
>>> print([fv['name'] for fv in fix_versions])
['3.1_hotfix', '3.2']

What am I doing wrong?

[Andy Heinzer · Accepted solution]

Hi @mrytikov 

I see that you are trying to use the REST API in Jira Cloud in order to add/remove/set fixVersions on an issue.  I took a closer look at your payloads here, and I think I found the problem.  First thing is that, in general, we use the 'fields' when creating the issue, the 'update' directive when updating the issue. The use of 'set' is expected to overwrite any other existing values in an array field like versions, labels, components, etc.  Also in your original post, it was not clear to me if you were using the POST directive (to create the issue) or the PUT directive, to update the issue.  Once the issue is created, you can just use the PUT directive to update that issue.

The next thing might be more environmental, but using the single quote versus double quotes can sometimes cause problems like this.  The json payload might accept it, but I have found it to sometimes be a source of problems.  It looks like you might be using python to do make these calls, and while I'm not an expert in python, I was able to recreate this same kind of response using curl.  I ran into the same problems when using your payloads.  I think you had an extra square bracket in your payload.  Here are my examples:

Add a specific version:

curl --request PUT \
--url 'https://[redacted].atlassian.net/rest/api/2/issue/SCRUM-11' \
--header 'Authorization: Basic [redacted]' \
--header 'Content-Type: application/json; charset=utf-8' \
--data '
{
"update": {
"fixVersions": [
{"add": 
{"name": "Version 3.0"}
}
]
}
}'

Remove a specific version:

curl --request PUT \
--url 'https://[redacted].atlassian.net/rest/api/2/issue/SCRUM-11' \
--header 'Authorization: Basic [redacted]' \
--header 'Content-Type: application/json; charset=utf-8' \
--data '
{
"update": {
"fixVersions": [
{"remove": 
{"name": "Version 3.0"}
}
]
}
}'

Or you can make one call to do both at the same time:

curl --request PUT \
--url 'https://[redacted].atlassian.net/rest/api/2/issue/SCRUM-11' \
--header 'Authorization: Basic [redacted]' \
--header 'Content-Type: application/json; charset=utf-8' \
--data '
{
"update": {
"fixVersions": [
{"remove": 
{"name": "Version 3.0"}
},
{"add":
{"name": "Version 2.0"}
}
]
}
}'

The link you cited of https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-issueidorkey-put is correct, but it doesn't exactly show you the syntax of fixVersion field precisely.  But that example does show a single REST call that adds and then removes a label, like so:

"labels": [
      {
        "add": "triaged"
      },
      {
        "remove": "blocker"
      }
    ]

I hope this helps.

Andy

[mrytikov]

Hi, Andy.

Thanks for the reply.

Unfortunately, it didn't work: PUT request with data

{    
"update": {
  "fixVersions": [
    {
      "remove": {
        "name": "3.1_hotfix"
      }
    }
  ]
}}

returned 204, but the fixVersion was not deleted.

I just found, that versions, that I'm unable to remove have parameters "archived" and "released" set to true, can it be the root of a problem? Maybe I just can't remove archived fixVersion or something like that?

[Andy Heinzer]

Ah, yes that is another possible cause of the problem here.  When a version has been archived in a project, you are no longer able to add that version or remove it from any issues.  It is intended to act as a historical snapshot of that version according to our documentation in Manage versions. 

You can see the same behavior within the web UI of Jira when an issue has a version that is archived:

It is not removable from there either.

A project administrator could un-archive that version.  If they were to do that, then you could add/remove that specific version to issues again.

[mrytikov]

So, that's the cause of the problem then. Thanks for your help!