| Table of Contents |
|---|
Several actions in Automation for JIRA support editing fields through an "Advanced" section. This is necessary if you want to update system or custom fields for which we don't have a nice form control yet. Over time we'll reduce the need for this. The advanced fields field requires you to specify a valid JSON object using the format specified by JIRA's REST API.
Actions that currently support setting advanced field values are:
- Clone issue
- Create issue
- Edit issue
- Transition issue
Here's an example of what this section looks like for the "Transition issue" action:
Format of the JSON
The JSON object can contain two top level attributes: "update" or "fields". These attributes then contain an object specifying the field ids you would like to change with the new values for those fields. For example:
| Code Block |
|---|
{
"update": {
"description": {
"set": "a new description"
},
"labels": [{
"add": "test-label"
}]
},
"fields": {
"summary": "something's wrong"
}
} |
So what's the difference between "update" and "fields"? "fields" is simply a shortcut for calling "update" with the "set" operation. So in the example above, calling "set" for the description field would be equivalent to just including the "description" in the "fields" section below like this: {"fields": {"description":"a new description"}}. Please note that the same field can never appear in both the "update" and "fields" section at the same time.
"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 above, we'll add "test-label" to the existing labels on the issue. If we'd used the "set" operation then all existing labels would have been replaced with "test-label". This way existing labels will continue to exist for the issue.
How do I reference issue fields?
We have added some smarts to allow you to reference custom fields by name rather that id. E.g. the following references the same field:
| Code Block |
|---|
{
"fields": {
"customfield_10003": "the value I want to set",
"My Text Customfield": "this is the same field as above and will cause an error"
}
} |
As you can see, it is much easier to just use the name and it is a lot easier to read as well. The fields are case insensitive and you can replace spaces with underscores. If there are multiple customfields with the same name or the same name as a system field, you will have to use the old syntax.
How do I find out what fields/operations are supported?
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.
...
https://<yourinstance>/rest/api/2/issue/createmeta?projectKeys=JRA&expand=projects.issuetypes.fields
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"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...
}
}
]
}
]
} |
...
https://<yourinstance>/rest/api/2/issue/<YOURISSUEKEY>/editmeta
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"fields": {
"summary": {
"required": true,
"schema": {
"type": "string",
"system": "summary"
},
"name": "Summary",
"key": "summary",
"operations": [
"set"
]
},
"issuetype": {
"required": true,
"schema": {
"type": "issuetype",
"system": "issuetype"
},
"name": "Issue Type",
"key": "issuetype",
"operations": [],
"allowedValues": [
{
"self": "https://goonbag.atlassian.net/rest/api/2/issuetype/10002",
"id": "10002",
"description": "A task that needs to be done.",
"iconUrl": "https://goonbag.atlassian.net/secure/viewavatar?size=xsmall&avatarId=10318&avatarType=issuetype",
"name": "Task",
"subtask": false,
"avatarId": 10318
}
]
},
// other fields removed for brevity...
"customfield_10400": {
"required": false,
"schema": {
"type": "option",
"custom": "com.atlassian.jira.plugin.system.customfieldtypes:select",
"customId": 10400
},
"name": "Single Select",
"key": "customfield_10400",
"operations": [
"set"
],
"allowedValues": [
{
"self": "https://goonbag.atlassian.net/rest/api/2/customFieldOption/10100",
"value": "red",
"id": "10100"
},
{
"self": "https://goonbag.atlassian.net/rest/api/2/customFieldOption/10101",
"value": "blue",
"id": "10101"
},
{
"self": "https://goonbag.atlassian.net/rest/api/2/customFieldOption/10102",
"value": "green",
"id": "10102"
}
]
},
// other fields removed for brevity...
"assignee": {
"required": false,
"schema": {
"type": "user",
"system": "assignee"
},
"name": "Assignee",
"key": "assignee",
"autoCompleteUrl": "https://goonbag.atlassian.net/rest/api/latest/user/assignable/search?issueKey=TEST-45&username=",
"operations": [
"set"
]
}
}
} |
The JSON produced above returns all fields that you can included in the Advanced JSON for edit, including their possible operations and values. You can also use this to look up the custom field id for a particular custom field you may want to edit. For example the editmeta object above allows me to search for the "Single Select" custom field to find its possible operations and values (only "set" and "red", "blue", "green"). For example to set the "Single Select" field to green during an edit, I would specify this Advanced JSON:
| Code Block |
|---|
{
"update": {
"Single Select": [
{
"set": {"value": "green"}
}
]
}
} |
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 trieds 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 issue from being editable.
Examples
Adding labels
Adding a label to the set of existing labels:
| Code Block |
|---|
{
"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
| Code Block |
|---|
{
"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.
Using smart-values
Advanced field values also support smart values! For example this is how you would update the assignee to the user who initiated the event:
| Code Block |
|---|
{
"fields": {
"assignee": { "name": "{{initiator.key}}" }
}
} |
Linking issues
You can also create issue links using the Advanced section! For example if you create a new issue as a result of an edit of an existing issue, then you could create a link back to the edited issue using this:
| Code Block |
|---|
{"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 will be replaced with the key of the issue that triggered the rule.
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 multiples lines of text\n separated by\n line feeds",
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 string values.
"labels" : ["examplelabelnumber1", "examplelabelnumber2"]
Checkbox custom field - A custom field that allows you to select a 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 custom field that is a date in 'YYYY-MM-DD' format.
"customfield_11441" : "2015-11-18"
Date time picker custom field - A custom field that is a datetime in ISO 8601 'YYYY-MM-DDThh:mm:ss.sTZD' format.
"customfield_11442" : "2015-11-18T14:39:00.000+1100"
Labels custom field - A custom field that is an array of strings.
"customfield_11443" : [ "rest_label1", "rest_label2" ]
Number custom field - A custom field that contains a number.
"customfield_11444" : 666
Radio button custom field - A custom field that allows you to 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 - A custom field that allows you to select a single parent value and 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 - A custom field that allows you to select a 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 - A custom field that allows you to 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 - A custom field that allows multiple lines of text.
"customfield_11450": "Multiples lines of text\n separated by\n line feeds"
Text custom field - A custom field that allows a single line of text.
"customfield_11450": "a single line of text"
URL custom field - A custom field that allows a URL to be entered.
"customfield_11452" : "http://www.atlassian.com",
Single-user picker custom field - A custom field that allows a single user to be selected.
"customfield_11453" : { "name":"tommytomtomahawk" },
Multi-user picker custom field - A custom field that allows multiple users to be selected.
"customfield_11458" : [ { "name":"inigomontoya" }, { "name":"tommytomtomahawk" }]Time tracking
You can log work and change the timetracking estimate using the advanced fields section. You can log work using:
| Code Block |
|---|
{
"update": {
"worklog" : [
{
"add": {
"timeSpent" : "6m"
}
}
]
}
} |
Or log work and set the remaining estimate at the same time:
| Code Block |
|---|
{
"update": {
"worklog" : [
{
"add": {
"timeSpent" : "6m"
}
}
]
},
"fields": {
"timetracking": {
"originalEstimate": "10",
"remainingEstimate": "5"
}
}
} |
You can combine this with Smart Fields to log work using a calculated value.
| Code Block |
|---|
{
"update": {
"worklog" : [
{
"add": {
"timeSpent" : "{{#now}}func=businessDaysBetween({{issue.created}}), format=\"toDays\"{{/}}d"
}
}
]
}
} |
| Info | ||
|---|---|---|
| ||
| Info | ||
Our documentation has recently move to a new location! Please head on over to: http://docs.codebarrel.io/automation/#/smart-fields/advanced-fields |