Advanced/Additional fields

When to use

Several actions in Automation for Jira support editing fields through a section available under More options.   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 additional 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:

Advanced

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:

{
    "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.

Referencing 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:

{
    "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.

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:

This yields the following response for the '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 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:

{
    "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 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 issue from being editable.

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:

{
    "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 strings correctly as well.

To encode a string 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 strings 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")}}
    }
}

The following is assuming an issue with 2 versions "Version 2.0" and "Version 3.0":

smart-value Result
{{issue.fixVersions.first.name.asJsonString}} "Version 2.0"
{{issue.fixVersions.first.name.asJsonObject("name"}}) { "name": "Version 2.0" }
{{issue.fixVersions.asJsonObjectArray("name"}}) [{ "name": "Version 2.0" },{ "name": "Version 3.0" }]
{{issue.fixVersions.name.asJsonObject("key").asJsonArray}} [{ "key": "Version 2.0" },{ "key": "Version 3.0" }]
{{issue.fixVersions.name.right(3).asJsonArray}} [2.0,3.0]
{{issue.fixVersions.name.asJsonStringArray}} ["Version 2.0","Version 3.0"]
{{issue.fixVersions.name.asJsonString.asJsonArray}} ["Version 2.0","Version 3.0"]

Examples

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 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:

{"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.

Time tracking and logging work

If your using time tracking in Jira you may want to use Automation for Jira to update the associated fields. This is not as straight forward as setting other fields because timetracking is a conglomerate field (represents multiple values). Meaning originalEstimate and remainingEstimate are just parts of the parent field.

You can also just 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}}func=businessDaysBetween({{issue.created}}), format=\"toDays\"{{/}}d"
        }
      }
    ]
  }
}

To copy the time tracking fields from another issue, you would write:

{
    "fields": {
        "timetracking": {
              "originalEstimate": "{{issue.timetracking.originalEstimate}}",
              "remainingEstimate": "{{issue.timetracking.remainingEstimate}}"
        }
    }
}

Setting request participants

The request participants field for Jira Service Desk also needs to be certain structure. For example, if you want to add the last commentor of the issue to participants. You can do:

{
  "update": {
    "Request participants" : [
      {
        "add": {
          "name":"{{issue.comments.last.author.name}}"
        }
      }
    ]
  }
}

More 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"

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" }]