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.

Environment

Jira Align

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:

https://<instance>.jiraalign.com/rest/align/api/2/Epics/<id>/editmeta

Sample 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, 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 are null 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:

[
    {
        "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:

[
    {
        "op": "replace",
        "path": "customfields/3",
        "value":
        {
            "customfield_90779":
            [
                {
                    "value": "Test Update with PATCH"
                }
            ]
        }
    }
]

Or:

[
    {
        "op": "replace",
        "path": "customFields/3/customfield_90779/",
        "value": [
            {
                "value": "Custom field text goes here"
            }
        ]
    }
]

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 :

[
    {
        "op": "replace",
        "path": "customfields/1",
        "value":
        {
            "customfield_90763":
            [
                {
                    "id": 3
                }
            ]
        }
    }
]

For a multi-select dropdown custom field, it's possible to specify multiple IDs:

[
    {
        "op": "replace",
        "path": "customFields/1/customfield_90763/",
        "value": [
            {
                "id": 2
            },
            {
                "id": 3
            }
        ]
    }
]