Update Fields

Updating custom fields is a very common task. There are three ways to specify custom field values:

1. Use textual names for fields, for readable and simple code. For example, for a select list you specify the option value.
2. Use object IDs if you feel concerned about names changing. For instance, in a select list you can use an option ID.
3. Use the underlying objects (Option, Version) - this is useful when copying values from one issue to another.

We also cater for common automation tasks, such as setting an additional fix version or multi-select value without retrieving the current value, adding the new one, and then setting the new list of values.

Custom fields can be set by numeric ID or name. The numeric ID of a custom field is just the number portion of its ID. For example, if the String ID is customfield_12345, the numeric ID is 12345. Use the custom field name for readable and portable scripts. To read the value of a custom field, see the Reading Custom Field Values section below. 

Read the value of custom fields

You can use the HAPI shortcut to get custom field 

groovy
// by custom field name
issue.getCustomFieldValue('My text field')
            
// or by custom field ID
issue.getCustomFieldValue(10146)

Using this shortcut means you don't have to use CustomFieldManager to look up the custom field instance first.

Caching

It's important to note that an issue's fields are cached when the Issue object is first retrieved. Therefore, if you retrieve a custom field value and then update the field, whatever the value was before you updated the field is returned. To ensure the updated value is returned you can use refresh().

For example, the following logs out null rather than the updated value:

groovy
def issue = Issues.getByKey('JRA-1')

logger.warn(issue.getCustomFieldValue('Select List').toString())

issue.update {
	setCustomFieldValue('Select List', 'First Option')
}

logger.warn(issue.getCustomFieldValue('Select List').toString()

If we add refresh() to the Issue object it returns the expected result of First Option:

groovy
logger.warn(issue.refresh().getCustomFieldValue('Select List').toString())

Update text fields

In this example we're using custom field values to add a text field to the issue. Text fields can be set using the following:

groovy
issue.update {
	setCustomFieldValue('My text field', 'foo')
}

//or

issue.update {
	setCustomFieldValue(10104, 'foo')
}

Bulk update text fields

In this example you are working on a product, and you changed its name in the early stages of development. Now you wish to edit the name in the description of all issues. You can use a JQL query to bulk update fields, as shown below:

groovy
Issues.search('project = KAN and description ~ hello').each { issue ->
    issue.update {
        setDescription('goodbye')
    }
}

Update date and date time fields

In this example we're setting the due date. Date system fields, such as due date and Date Picker custom fields, can be set as follows:

groovy
import java.time.LocalDate

def issueOne = Issues.getByKey('JRA-1')
def issueTwo = Issues.getByKey('JRA-2')

issueOne.update {
	setDueDate('2024-11-27')
    
	// additionally you can use a LocalDate, e.g. for copying from another issue
    setDueDate(issueTwo.getDueDate().toLocalDate())
            
    // or use a LocalDate object, for instance to set the date to 7 days from now 
    setDueDate(LocalDate.now().plusDays(7))
}

Set a single value

In this example we're setting a single radio button field. To set a single value (radio-buttons, and single-select custom fields):

groovy
issue.update {
	setCustomFieldValue('My radio buttons', 'Yes')
}

Set multiple values

In this example we're setting multiple checkbox fields. You can set multiple values as follows:

groovy
                issue.update {
                    setCustomFieldValue('My checkboxes', 'Yes', 'Maybe')
                }

You can also use the Groovy spread operator to list multiple values. The spread operator (*) allows you to pass elements of a collection as individual arguments to a method. This is particularly useful when you have a list of values. For example:

groovy
def issue = Issues.getByKey('JRA-1')
def list = ['Yes', 'Maybe']

issue.update {
    setCustomFieldValue('My checkboxes', *list)
}

Add to an existing selected option

In this example we're adding an additional checkbox value and adding a fix version. You can add an existing selected option using add(). This is also valid on other fields that are a "collection" of object; for example affects/fix versions and components:

groovy
issue.update {
	setCustomFieldValue('My checkboxes') {
    	add('Maybe')
	}
            
    setFixVersions {
    	add('v2.0')
	}
}

Remove a selected value

In this example we're removing the No checkbox value. You can remove a selected value if it is present:

groovy
issue.update {
    setCustomFieldValue('My checkboxes') {
        remove('No')        
    }
}

Set values by option Name

In this example we're setting the checkbox 'Yes' and 'Maybe' values by their name. The add, remove, and replace methods have overloads which let you set the "object" rather than the textual name. For example Version, Option, or the object's name.

To set by option name:

groovy
issue.update {
	setCustomFieldValue('My checkboxes') {
    	set('Yes', 'No')
    }            
}

Related Content

• Javadocs Groovy Class
• Javadocs methods