Advanced field editing using JSON

Still need help?

The Atlassian Community is here for you.

Ask the community

tip/resting Created with Sketch.

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 calling update with the set operation. So in the example above, calling set for the description field is equivalent to just 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/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 the set operation all existing labels would be overwritten with "test-label".  Using update 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 }}
Last modified on Apr 5, 2022

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.