Advanced field editing using JSON
Tip
Only use this if you can't edit a field via the 'Choose fields to set...' dropdown. This may be necessary for custom fields provided by other apps.
You can edit fields through a section available under More options for these actions:
These additional fields require you to specify a valid JSON object using the format specified by Jira's REST API.
Here's an example of what this section looks like for the "edit issue" action:
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 callingupdate
with theset
operation. So in the example above, callingset
for the description field is equivalent to just including thedescription
in thefields
section like this:{"fields": {"description":"a new description"}}
.update
can be useful for fields with multiple values, where you want to add/remove from the existing set. For example, with the labels example in the screenshot above you can add "test-label" to the existing labels on the issue. If you used theset
operation all existing labels would be overwritten with "test-label". Usingupdate
the new one is added to the existing ones.
Warning
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 that id. 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"
}
}
As you can see, it's much easier to use the name (and it's a lot easier to read as well). 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
Jira's REST api thankfully can help here. Depending on if you're creating or editing issues, you can query a project's createmeta or issue's editmeta information.
You can retrieve the meta data for both operations by visiting:
https://yourinstance/rest/api/2/issue/createmeta?projectKeys=JRA&expand=projects.issuetypes.fields
https://yourinstance/rest/api/2/issue/YOURISSUEKEY/editmeta
This yields 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 Core)",
"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 JSON produced above returns all fields you can included in the Additional fields
including their possible operations and values.
For example, the editmeta object above 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, I would use the following JSON:
{
"update": {
"Single Select": [
{
"set": {"value": "green"}
}
]
}
}
You can also use this 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 Automation for Jira tries to edit/create the issue it will fail with an error in the audit log. This is most likely due to the fact that the field is missing on the appropriate edit or create screen in your project. To fix this simply navigate to the 'Screens' section in project admin of your project and ensure the field you're trying to update is on the appropriate edit or create screen.
Additionally, ensure that the automation add-on user has the right permissions to edit or create issues in your project! Finally your workflow may also be preventing an issue from being editable.
Using smart-values
Advanced field values also support smart values! For in-depth explanations of the syntax, see Jira smart values - JSON functions.
For example, this is how you change the current assignee to the user who initiated the event:
{
"fields": {
"assignee": { "name": "{{initiator.name}}" }
}
}
We have also created some convenience methods to make the referencing of other fields easier. E.g. the above can written as:
{
"fields": {
"assignee": {{initiator.name.asJsonObject("name")}}
}
}
This not only creates the JSON in the right format, but encodes the text correctly as well. To encode text by itself you can use:
{
"fields": {
"assignee": { "name": {{initiator.name.asJsonString}} }
}
}
To transform the value into JSON object with a key use the following:
{
"fields": {
"assignee": {{initiator.name.asJsonObject("key")}}
}
}
This produces:
{
"fields": {
"assignee": { "key": "username" }
}
}
For fields that take arrays of text you can use:
{
"fields": {
"labels": {{issue.parent.labels.asJsonStringArray}}
}
}
For fields that take an array of single field object you can use:
{
"fields": {
"Multi User Customfield": {{issue.parent.Multi User Customfield.asJsonObjectArray("name")}}
}
}
Field syntax examples
For more examples, please see the field formats documentation provided by Jira:
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 in Jira, you may want to use Automation for Jira to update associated fields. This is not as straight forward as setting other fields, because timetracking represents multiple values. Meaning originalEstimate
and remainingEstimate
are just parts of the parent field.
You can log work against an issue:
{
"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 issue:
{
"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"
}
]
}
}
You could also use remove
or set
as the operation instead of add
depending on what you need to do.
Setting the security level of an issue
{
"update": {
"security": [
{
"set": {"name": "Public"}
}
]
}
}
"Public" in this case 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:
{"update": {
"issuelinks": [
{
"add": {
"type": {
"name": "Relates"
},
"outwardIssue": {
"key": "{{issue.key}}"
}
}
}
]
}
}
To lookup the link type name ("Relates" in the example above), you can consult https://<yourinstance>/secure/admin/ViewLinkTypes!default.jspa
on your instance. The {{issue.key}}
smart value replaces the key of the trigger issue.
Request participants
The request participants field for Jira Service Desk must be in a certain structure. For example, to add the last commenter of the issue to participants:
{
"update": {
"Request participants" : [
{
"add": {
"name":"{{issue.comments.last.author.name}}"
}
}
]
}
}
Checkbox custom field
Select multiple values from a defined list of values. You can address them by 'value' or by '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" : 666
Radio button custom field
Select a single value from a defined list of values. You can address them by 'value' or by 'id'.
"customfield_11445" : { "value": "option2" }
or
"customfield_11445" : { "id": 10112 }
Cascading select custom field
Select a single parent value then a related child value. You can address them by 'value' or by 'id'.
"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 by 'id'.
"customfield_11448" : [ { "value": "option1" }, { "value": "option2" } ]
or
"customfield_11448" : [ { "id": 10112 }, { "id": 10115 } ]
Single-select custom field
Select a single value from a defined list of values. You can address them by 'value' or by '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
A URL can be entered.
"customfield_11452" : "http://www.atlassian.com",
Single-user picker custom field
A single user can be selected.
"customfield_11453" : { "name":"tommytomtomahawk" },
Multi-user picker custom field
Multiple users can be selected.
"customfield_11458" : [ { "name":"inigomontoya" }, { "name":"tommytomtomahawk" }]
Elements Connect (formerly nFeed) custom field
An array of string identifiers.
"customfield_10700" : [ "10300", "10400" ]
An example of copying the value of an Elements Connect field:
"customfield_10700" : {{ issue.customfield_10700.asJsonStringArray }}