Advanced field editing using JSON
The More options additional fields should only be used if a field cannot be edited using Choose fields to set. This may be necessary for custom fields provided by other applications.
The following automation actions provide additional fields for advanced field editing:
To access these fields, select More options when configuring the action. These additional fields require you to specify a valid JSON object using the format specified by the Jira REST API. When configuring field updates, avoid setting fields to copy from themselves if they are empty, as this can result in no changes being applied. Instead, ensure the source field contains valid data or specify an alternate field with the desired values.
Format of the JSON
The JSON object can contain the attributes update or fields, for example:
{
"update": {
"description": {
"set": "a new description"
},
"labels": [{
"add": "test-label"
}]
},
"fields": {
"summary": "woohoo! a new summary"
}
}What's the difference between update and fields?
fields is a shortcut for calling update with the set operation. In the example above, calling set for the description field is the equivalent to including the description in the fields section like this: {"fields": {"description":"a new description"}}.
update can be useful for fields with multiple values, where you want to add and/or remove from the existing set. For example, when adding labels to a work item, using the set operation would overwrite all existing labels, while using update would add the label without removing any existing labels.
The same field should never appear in both update and fields sections in the JSON at the same time.
What problems may occur when editing fields?
Invalid JSON
This warning may occur if the JSON you entered was invalid. Check the syntax of your JSON and try again. If an automation rule fails to execute correctly, check the audit logs to ensure that the rule is triggering as expected. Common errors include:
Missing permissions for the rule actor. Ensure the automation rule actor has permissions to view or edit fields in the space.
Invalid configuration in the rule, such as referencing unavailable fields (verify `editmeta` and `createmeta`).
Incorrect syntax in the JSON for fields such as cascading selects or users.
Valid JSON but smart value can’t be validated
In this case, the JSON is valid, but the smart values you entered into the field can’t be validated. This is because smart values can only be validated once a rule is executed. Check the audit log once your rule runs to ensure the smart values have worked as you planned. If a rule runs successfully but expected updates are not applied, verify that all necessary steps (for example, Re-fetch work item data) are included and ensure fields are not set to copy values from themselves unless they contain valid data.
JSON entered via smart value which can’t be validated
This warning may occur if you’ve attempted to enter all of your JSON through a smart value, however we can’t validate smart values until a rule is executed. Check the audit log once your rule runs to ensure the smart values have worked as you planned. If a rule runs successfully but expected updates are not applied, verify that all necessary steps (for example, Re-fetch work item data) are included and ensure fields are not set to copy values from themselves unless they contain valid data.
Valid JSON with missing keys
In this case, the JSON is valid, but we are unable to parse the additional fields as the update or fields keys are missing. Add at least one of these keys to your entry and try again.
Referencing work item fields
You can reference custom fields by name rather than ID. For example, when referencing user fields such as the reporter, ensure you specify the desired subproperty. Instead of using just {{issue.reporter}}, you should include the subproperty like {{issue.reporter.displayName}} or {{issue.reporter.emailAddress}} to pull accurate and detailed reporter information.
{
"fields": {
"summary": "Reporter: {{issue.reporter.displayName}}"
}
}
In the example below, the same field is referenced by its ID and its name:
{
"fields": {
"customfield_10003": "the value I want to set",
"My Text Customfield": "this is the same field as above and using both causes an error"
}
}
When referencing by name, fields are case insensitive and you can replace spaces with underscores.
If there are custom fields with the same name, or a custom field has the same name as a system field, you will need to use the custom field ID.
Supported fields & operations
If you’re creating or editing work items, you can query a space’s createmeta or a work item's editmeta information to view supported fields and operations. Additionally, ensure automation rules involving updates after actions (for example, assigning a user) include the 'Re-fetch Work item data' step to fetch updated work items details before subsequent steps. This ensures the latest data is available for dependent actions, such as updating custom fields.
You can retrieve the metadata for both operations by visiting:
GET /rest/api/3/issue/createmeta?projectKeys=<string>&expand=projects.issuetypes.fields
GET /rest/api/3/issue/{issueIdOrKey}/editmeta
This JSON returns all fields that can be used in the Additional fields, including their possible operations and values.
Consider the following response for createmeta:
{
"expand": "projects",
"projects": [
{
"expand": "issuetypes",
"self": "https://jira.atlassian.com/rest/api/2/project/10240",
"id": "10240",
"key": "JRA",
"name": "Jira (including Jira Work Management)",
"avatarUrls": {
"48x48": "https://jira.atlassian.com/secure/projectavatar?pid=10240&avatarId=17294",
"24x24": "https://jira.atlassian.com/secure/projectavatar?size=small&pid=10240&avatarId=17294",
"16x16": "https://jira.atlassian.com/secure/projectavatar?size=xsmall&pid=10240&avatarId=17294",
"32x32": "https://jira.atlassian.com/secure/projectavatar?size=medium&pid=10240&avatarId=17294"
},
"issuetypes": [
{
"self": "https://jira.atlassian.com/rest/api/2/issuetype/10000",
"id": "10000",
"description": "",
"iconUrl": "https://jira.atlassian.com/secure/viewavatar?size=xsmall&avatarId=51505&avatarType=issuetype",
"name": "Suggestion",
"subtask": false,
"expand": "fields",
"fields": {
"summary": {
"required": true,
"schema": {
"type": "string",
"system": "summary"
},
"name": "Summary",
"hasDefaultValue": false,
"operations": [
"set"
]
},
// other fields removed for brevity...
"components": {
"required": false,
"schema": {
"type": "array",
"items": "component",
"system": "components"
},
"name": "Component/s",
"hasDefaultValue": false,
"operations": [
"add",
"set",
"remove"
],
"allowedValues": [
{
"self": "https://jira.atlassian.com/rest/api/2/component/36920",
"id": "36920",
"name": "System Administration - Support Tools"
},
{
"self": "https://jira.atlassian.com/rest/api/2/component/43995",
"id": "43995",
"name": "User Management - Delete User"
}
]
}
// other fields removed for brevity...
}
}
]
}
]
}The editmeta object allows you to search for the Single Select custom field and find its operations and values – only set and red, blue, green.
For example, to set the Single Select field to green during an edit, you can use the following JSON:
{
"update": {
"Single Select": [
{
"set": {"value": "green"}
}
]
}
}You can also use the meta information to look up the custom field ID for a particular custom field.
Why is my field not editable?
If you've retrieved the createmeta or editmeta for your space or work item, the field you're trying to edit may not show up in the resulting JSON. This means when a rule attempts to edit or create the work item, it will fail with an error in the audit log.
This will most likely be due to the field missing on the appropriate edit or create screen in your space. To address this, go to Jira settings > Work items > Screens and ensure the field you’re trying to update is on the appropriate edit or create screen.
Additionally, ensure that the automation rule actor has the right permissions to edit or create work items in your space.
Using smart values
Due to recent GDPR changes, referencing user fields such as reporter or assignee now require the property id to be set with a user's account ID rather than using name.
Advanced field values also support smart values. Check the audit logs after rule execution to confirm that values were correctly processed. Learn more about the JSON functions available as smart values.
Best practices
Always specify the property and, if applicable, the subproperty when referencing user fields in a smart value.
For example:
{{issue.reporter.displayName}}or{{issue.reporter.accountId}}
Use
.asJsonStringor.asJsonObjectwhere complex values need encoding for JSON.
For example, to copy a reporter's email address into a custom field, use:
{
"fields": {
"customfield_12345": "{{issue.reporter.emailAddress}}" }
}
}
And to change the current assignee to the user who initiated the event, use:
{
"fields": {
"assignee": { "id": "{{initiator.accountId}}" }
}
}
To make the referencing of other fields easier, the above can be written as:
{
"fields": {
"assignee": {{initiator.accountId.asJsonObject("id")}}
}
}
This not only creates the JSON in the right format, but also encodes the text correctly. To encode text by itself:
{
"fields": {
"assignee": { "id": {{initiator.accountId.asJsonString}} }
}
}
To transform the value into JSON object with a key:
{
"fields": {
"assignee": {{initiator.name.asJsonObject("key")}}
}
}
This will produce:
{
"fields": {
"assignee": { "key": "username" }
}
}
For fields that take arrays of text:
{
"fields": {
"labels": {{issue.parent.labels.asJsonStringArray}}
}
}
For fields that take an array of single field object:
{
"fields": {
"Multi User Customfield": {{issue.parent.Multi User Customfield.accountId.asJsonObjectArray("id")}}
}
} Field syntax examples
For more examples, view the Jira Cloud platform REST API documentation.
Summary
A system field that is a single line of text.
"summary": "A summary is one line of text" Description
A system field that is multiple lines of text.
"description": "A description is many lines of text\n separated by\n line feeds"Time tracking and logging work
If you’re using time tracking, you can use automation to update associated field. Because time tracking represents multiple values, originalEstimate and remainingEstimate are parts of the parent field.
You can log work against a work item:
{
"update": {
"worklog" : [
{
"add": {
"timeSpent" : "6m"
}
}
]
}
}
Or log work and set the remaining estimate at the same time:
{
"update": {
"worklog" : [
{
"add": {
"timeSpent" : "6m"
}
}
]
},
"fields": {
"timetracking": {
"originalEstimate": "10",
"remainingEstimate": "5"
}
}
}
You can combine this with smart values to log work using a calculated value:
{
"update": {
"worklog" : [
{
"add": {
"timeSpent" : "{{now.diff(issue.created).businessDays}}d"
}
}
]
}
}
To copy the time tracking fields from another work item:
{
"fields": {
"timetracking": {
"originalEstimate": "{{issue.timetracking.originalEstimate}}",
"remainingEstimate": "{{issue.timetracking.remainingEstimate}}"
}
}
}Components
A system field that is multiple values addressed by name.
"components" : [ { "name": "Active Directory"} , { "name": "Network Switch" } ]Affects Versions
A system field that is multiple values addressed by name.
"versions" : [ { "name": "Version 1.0"} , { "Version": "1.1" } ]Fix Versions
A system field that is multiple values addressed by name.
"fixVersions" : [ { "name": "2.0"} , { "name": "Network Switch" } ]Due date
A system field that is a date in 'YYYY-MM-DD' format.
"duedate" : "2015-11-18"Labels
A system field that is an array of text values.
"labels" : ["examplelabelnumber1", "examplelabelnumber2"] Adding labels
Adding a label to the set of existing labels:
{
"update": {
"labels": [
{
"add": "my-new-label"
}
]
}
}
Adding multiple labels to the set of existing labels:
{
"update": {
"labels": [
{
"add": "Label1"
},
{
"add": "Label2"
}
]
}
}You can also use remove or set as the operation instead of add.
Setting the security level of a work item
{
"update": {
"security": [
{
"set": {"name": "Public"}
}
]
}
}In this case, Public is the name of the security level. Substitute this with a valid security level in your space.
Linking work items
You can also create work item links. For example, create a new work item as a result of editing an existing work item, then create a link back to the edited work item:
{"update": {
"issuelinks": [
{
"add": {
"type": {
"name": "Relates"
},
"outwardIssue": {
"key": "{{issue.key}}"
}
}
}
]
}
} To lookup the link type name (Relates in the above example), you can consult <yoursite>/secure/admin/ViewLinkTypes!default.jspa on your site. The {{issue.key}} smart value replaces the key of the trigger work item.
Request participants
The request participants field for Jira Service Management must be in a certain structure. For example, to add the last commenter of the work item to participants:
{
"update": {
"Request participants" : [
{
"add": {
"id":"{{issue.comments.last.author.accountId}}"
}
}
]
}
}Checkbox custom field
Select multiple values from a defined list of values. You can address them by value or id.
"customfield_11440" : [{ "value" : "option1"}, {"value" : "option2"}]
or
"customfield_11440" : [{ "id" : 10112}, {"id" : 10115}] Date picker custom field
A date in 'YYYY-MM-DD' format.
"customfield_11441" : "2015-11-18"Date time picker custom field
A date time in ISO 8601 'YYYY-MM-DDThh:mm:ss.sTZD' format.
"customfield_11442" : "2015-11-18T14:39:00.000+1100"Labels custom field
An array of text.
"customfield_11443" : [ "rest_label1", "rest_label2" ] Number custom field
Contains a number.
"customfield_11444" : 664Radio button custom field
Select a single value from a defined list of values. You can address them by value or id.
"customfield_11445" : { "value": "option2" }
or
"customfield_11445" : { "id": 10112 } Cascading select custom field
Select a single parent value and a related child value. You can address them by value or id. Ensure the correct JSON syntax is used for cascading fields. Use the appropriate metadata (`editmeta`) to verify valid values for the parent and child fields before updating the JSON.
"customfield_11447" : { "value": "parent_option1", "child": { "value" : "p1_child1"} }
or
"customfield_11447" : { "id": 10112, "child": { "id" : 10115 } } Multi-select custom field
Select multiple values from a defined list of values. You can address them by value or id.
"customfield_11448" : [ { "value": "option1" }, { "value": "option2" } ]
or
"customfield_11448" : [ { "id": 10112 }, { "id": 10115 } ]
Appending values in a multi-select custom field – for example where you have a multi-select custom field and you want to append a value from another custom field to this field.
{
"update": {
"customfield_12345": [{
"add": { "value": "{{issue.customfield_12224}}" }
}]
}
}Single-select custom field
Select a single value from a defined list of values. You can address them by value or id.
"customfield_11449" : { "value": "option3" }
or
"customfield_11449" : { "id": 10112 } Multi-line text custom field
Multiple lines of text.
"customfield_11450": "Multiples lines of text\n separated by\n line feeds" Text custom field
A single line of text.
"customfield_11450": "a single line of text"URL custom field
Takes a URL.
"customfield_11452" : "http://www.atlassian.com"Single-user picker custom field
A single user can be selected.
"customfield_11453" : { "id":"2s1863211f0z284c45269423" } Multi-user picker custom field
Multiple users can be selected.
"customfield_11458" : [ { "id":"2s1863211f0z284c45269423" }, { "id":"332212e13z52142111269423" }]
Appending values in a multi-user picker custom field – for example you want to append the reporter of the work item to a multi-user picker custom field. In that case, you would have to add the below under “More options”.
{
"update": {
"customfield_12346": [{
"add": {"id":"{{reporter.accountId}}"}
}]
}
}Elements Connect (formerly nFeed) custom field
An array of string identifiers.
"customfield_10700" : [ "10300", "10400" ]
For example, copying the value of an Elements Connect field:
"customfield_10700" : {{ issue.customfield_10700.asJsonStringArray }}Was this helpful?