How to use PATCH on the Feature/Epic custom fields in the API v2 in Jira Align
Platform Notice: Cloud and Data Center - This article applies equally to both cloud and data center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
Jira Align supports Custom Fields for Epics and Features in the REST API v2. This article outlines how to update the values using the API PATCH command.
Solution
It is recommended to start by calling editmeta endpoint, as it will bring the information needed on the custom field and its type, which is necessary to be used on the PATCH. This endpoint can be found for Epics at:
1
https://<instance>.jiraalign.com/rest/align/api/2/Epics/<id>/editmetaSample Response:
The field customfields is an array that holds the position (and values) of all the customfield_xxxxx inside of it, to be able to access these elements individually, the position inside the array needs to be provided. Keep in mind that this array starts at position 0.
Using the editmeta output from the above example, the field customfield_70026 is on position 0 of array customfields, as customfield_70027 is on position 1.
Also, as this is a structure of JSON (so you have elements inside elements), the fields customfield_xxxxx can also be arrays themselves and will have their values inside of specific positions. Due to this, it is important to get the editmeta output to be able to understand its structure and how to manipulate it.
Additionally, when custom fields are not yet populated with a value (empty in the UI), their API values arenull and not a list.
Custom Field type Text
There are a couple of ways to perform a PATCH for a text field, in both we need to provide the position in the array inside the customfields (just notice that the array starts at 0 and not 1), and the field name that we want to update. In my example below I'm updating the field customfield_90779 that is on position 3:
1
2
3
4
5
6
7
[
{
"op": "replace",
"path": "customfields/3/customfield_90779/0/value",
"value": "Test Update with PATCH"
}
]However, this will not work if the field has not been populated yet. The custom field's value will be null, and you'll get an error when trying to access index 0. We recommend this approach instead:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[
{
"op": "replace",
"path": "customfields/3",
"value":
{
"customfield_90779":
[
{
"value": "Test Update with PATCH"
}
]
}
}
]Or:
1
2
3
4
5
6
7
8
9
10
11
[
{
"op": "replace",
"path": "customFields/3/customfield_90779/",
"value": [
{
"value": "Custom field text goes here"
}
]
}
]Updating the custom field's value as a list will overwrite the whole field value (rather than changing any existing values inside or appending), and the old data will be gone. This is particularly important for the multi-select dropdown custom field as the value array can have multiple options.
We recommend first fetching the existing values, checking fornull, and sending the full modified list back using the above pattern.
Custom Field type Dropdown
The PATCH for Dropdown fields is similar, with the difference that we need to add the id of the option as the value (this can be seen on the editmeta output as well), on this example the field updated is customfield_90763 that is in array position 1, and the value of the id for the Dropdown that we want to use is 3 :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[
{
"op": "replace",
"path": "customfields/1",
"value":
{
"customfield_90763":
[
{
"id": 3
}
]
}
}
]For a multi-select dropdown custom field, it's possible to specify multiple IDs:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
[
{
"op": "replace",
"path": "customFields/1/customfield_90763/",
"value": [
{
"id": 2
},
{
"id": 3
}
]
}
]Was this helpful?