Automation basics
Understand the general concepts and best practices of automation in Atlassian cloud products.
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.
Format of the JSON
The JSON object can contain the attributes update or fields, for example:
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"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 an issue, 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.
Referencing issue fields
You can reference custom fields by name rather than ID. In the example below, the same field is referenced by its ID and its name:
1
2
3
4
5
6
{
"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 issues, you can query a project’s createmeta or an issue’s editmeta information to view supported fields and operations.
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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
{
"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:
1
2
3
4
5
6
7
8
9
{
"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 project or issue, 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 issue, 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 project. To address this, go to Jira settings > Issues > 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 issues on your project.
Using smart values
Due to recent GDPR changes, referencing user fields (such as reporter, 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. Learn more about the JSON functions available as smart values.
For example, to change the current assignee to the user who initiated the event:
1
2
3
4
5
{
"fields": {
"assignee": { "id": "{{initiator.accountId}}" }
}
}
To make the referencing of other fields easier, the above can be written as:
1
2
3
4
5
{
"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:
1
2
3
4
5
{
"fields": {
"assignee": { "id": {{initiator.accountId.asJsonString}} }
}
}
To transform the value into JSON object with a key:
1
2
3
4
5
{
"fields": {
"assignee": {{initiator.name.asJsonObject("key")}}
}
}
This will produce:
1
2
3
4
5
{
"fields": {
"assignee": { "key": "username" }
}
}
For fields that take arrays of text:
1
2
3
4
5
{
"fields": {
"labels": {{issue.parent.labels.asJsonStringArray}}
}
}
For fields that take an array of single field object:
1
2
3
4
5
{
"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.
1
"summary": "A summary is one line of text" Description
A system field that is multiple lines of text.
1
"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 an issue:
1
2
3
4
5
6
7
8
9
10
11
12
{
"update": {
"worklog" : [
{
"add": {
"timeSpent" : "6m"
}
}
]
}
}
Or log work and set the remaining estimate at the same time:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"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:
1
2
3
4
5
6
7
8
9
10
11
{
"update": {
"worklog" : [
{
"add": {
"timeSpent" : "{{now.diff(issue.created).businessDays}}d"
}
}
]
}
}
To copy the time tracking fields from another issue:
1
2
3
4
5
6
7
8
{
"fields": {
"timetracking": {
"originalEstimate": "{{issue.timetracking.originalEstimate}}",
"remainingEstimate": "{{issue.timetracking.remainingEstimate}}"
}
}
}Components
A system field that is multiple values addressed by name.
1
"components" : [ { "name": "Active Directory"} , { "name": "Network Switch" } ]Affects Versions
A system field that is multiple values addressed by name.
1
"versions" : [ { "name": "Version 1.0"} , { "Version": "1.1" } ]Fix Versions
A system field that is multiple values addressed by name.
1
"fixVersions" : [ { "name": "2.0"} , { "name": "Network Switch" } ]Due date
A system field that is a date in 'YYYY-MM-DD' format.
1
"duedate" : "2015-11-18"Labels
A system field that is an array of text values.
1
"labels" : ["examplelabelnumber1", "examplelabelnumber2"] Adding labels
Adding a label to the set of existing labels:
1
2
3
4
5
6
7
8
9
{
"update": {
"labels": [
{
"add": "my-new-label"
}
]
}
}
Adding multiple labels to the set of existing labels:
1
2
3
4
5
6
7
8
9
10
11
12
{
"update": {
"labels": [
{
"add": "Label1"
},
{
"add": "Label2"
}
]
}
}You can also use remove or set as the operation instead of add.
Setting the security level of an issue
1
2
3
4
5
6
7
8
9
{
"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 project.
Linking issues
You can also create issue links. For example, create a new issue as a result of editing an existing issue, then create a link back to the edited issue:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{"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 issue.
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 issue to participants:
1
2
3
4
5
6
7
8
9
10
11
{
"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.
1
2
3
4
5
"customfield_11440" : [{ "value" : "option1"}, {"value" : "option2"}]
or
"customfield_11440" : [{ "id" : 10112}, {"id" : 10115}] Date picker custom field
A date in 'YYYY-MM-DD' format.
1
"customfield_11441" : "2015-11-18"Date time picker custom field
A date time in ISO 8601 'YYYY-MM-DDThh:mm:ss.sTZD' format.
1
"customfield_11442" : "2015-11-18T14:39:00.000+1100"Labels custom field
An array of text.
1
"customfield_11443" : [ "rest_label1", "rest_label2" ] Number custom field
Contains a number.
1
"customfield_11444" : 664Radio button custom field
Select a single value from a defined list of values. You can address them by value or id.
1
2
3
4
5
"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.
1
2
3
4
5
"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.
1
2
3
4
5
"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.
1
2
3
4
5
6
7
{
"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.
1
2
3
4
5
"customfield_11449" : { "value": "option3" }
or
"customfield_11449" : { "id": 10112 } Multi-line text custom field
Multiple lines of text.
1
"customfield_11450": "Multiples lines of text\n separated by\n line feeds" Text custom field
A single line of text.
1
"customfield_11450": "a single line of text"URL custom field
Takes a URL.
1
"customfield_11452" : "http://www.atlassian.com"Single-user picker custom field
A single user can be selected.
1
"customfield_11453" : { "id":"2s1863211f0z284c45269423" } Multi-user picker custom field
Multiple users can be selected.
1
"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 issue to a multi-user picker custom field. In that case, you would have to add the below under “More options”.
1
2
3
4
5
6
7
{
"update": {
"customfield_12346": [{
"add": {"id":"{{reporter.accountId}}"}
}]
}
}Elements Connect (formerly nFeed) custom field
An array of string identifiers.
1
"customfield_10700" : [ "10300", "10400" ]
For example, copying the value of an Elements Connect field:
1
"customfield_10700" : {{ issue.customfield_10700.asJsonStringArray }}Was this helpful?
Still need help?
The Atlassian Community is here for you.