API Quick Reference

Getting form fields

getFieldById(fieldId)

Get a FormField object to retrieve the value, set the validity, etc.

groovy
getFieldById("customfield_11111")
getFieldById("summary")

getFieldByName(fieldName)

This is the same as above example but uses the name. 

groovy
getFieldByName("My Custom Field")
getFieldByName("Description")

getFieldChanged()

Gets the ID of the field that this script is attached to.

groovy
getFieldById(getFieldChanged())

Common field operations

formField.getValue()

Gets the value that is current in the form. For certain fields, this does do some conversions.

• Select fields, radio buttons, checkboxes, etc. the string value will be returned, or a List of string values.

• Versions or Components fields the Version or Component objects(s) will be returned.

• Linked Issues field (id: "issuelinks-issues") will always return an array, even an empty one.

formField.setError(errorStr)

Marks the field as having an error. The error text is shown below the field. The user cannot submit while there are fields with errors.

groovy
formField.setError("The user selected is not a component lead")

formField.clearError()

Removes the error status from the field. Make sure that if you set an error, you also clear it for valid values.

formField.setLabel()

Sets a different "name" for the field. This only affects the visual appearance of the field. It doesn’t alter further calls to getFieldByName

groovy
formField.setLabel('Why is this high priority?')

formField.setRequired(true/false)

Makes this a required field or not.

groovy
formField.setRequired(true)

formField.setHidden(true/false)

Hides a field, or shows a hidden field. For example when the user selects Other from a select list, display a text field for them to type the value.

groovy
formField.setHidden(true)

formField.setReadOnly(true/false)

Makes a field read-only (true), or writable (false).

groovy
formField.setReadOnly(true)

formField.setFormValue(value)

Sets the value in the form. Unless you also set this to readonly, a user can modify it subsequently.

groovy
formField.setFormValue("Documentation subtask")

For "picker" fields you need to provide the ID of the option. 

For single-selects, radio buttons, multi-selects, checkboxes, project, issuetype, version, components and cascading select fields, you can provide a string matching the option label.

Note - you cannot set a value that could not exist, for instance an option that is not valid for that select list, or a component not valid for the current project. If you do this, we will log a warning in the application log. Hence it's a good idea to keep an on the application log (atlassian-jira.log , when developing your behaviours).

Alternatively, you can use the actual Option objects, or ProjectComponent, Version, Project, Resolution, which may be more useful if you are copying an existing issue. 

For multi-selects and checkboxes, this should be a list of items, eg formField.setFormValue(["Yes", "Maybe"]) 

See setting field defaults for examples of setting values for other field types.

formField.setFieldOptions(Iterable)

Sets the possible options for a select or multi select list. The value must be permissible for the field.

groovy
def customField = customFieldManager.getCustomFieldObject(getFieldChanged())
def config = customField.getRelevantConfig(getIssueContext())
def options = optionsManager.getOptions(config)

formField.setFieldOptions(options.findAll {it.value in ['foo', 'bar']})

formField.setDescription()

Sets the description for a form field.

groovy
formField.setDescription("Start typing to get a list of possible users")

Information about the current Issue

getIssueContext()

Getting the current issue type and project. Returns an com.atlassian.jira.issue.context.IssueContext.

groovy
def issueTypeName = getIssueContext().issueType.name
def projectKey = getIssueContext().projectObject.name

getRequestTypeName()

Get the RequestType name. If this behaviour is not running in a Service Management portal, this will return null.

groovy
if (getRequestTypeName() == 'IT Help')

Workflow information

getActionName()

Returns the name of the current action if the issue is undergoing a workflow action, null otherwise.

getAction()

Returns an ActionDescriptor object if the issue is undergoing a workflow action, null for Edit, Assign, etc.

getDestinationStepName()

Returns the name of the destination step if the issue is undergoing a workflow action, null otherwise.

getDestinationStep()

Returns an StepDescriptor object for the destination step if the issue is undergoing a workflow action.

Operations on tabs

For the following methods you can supply either the position of the tab (the leftmost one is at index 0), the tab name, or a FieldScreenTab.

hideTab(Integer tabIdx / String name, FieldScreenTab tab)

Hide a tab entirely. Has an optional second parameter: specifying false will show the tab.

groovy
hideTab(1) // hides the second tab
// or
hideTab("Testing Instructions")
// or
def tab = getFieldScreen().tabs.find {it.isContainsField("summary")}
hideTab(tab)

showTab(Integer tabIdx / String name, FieldScreenTab tab)

Shows a tab that was previously hidden by hideTab.

groovy
showTab(1) // shows the second tab

// you can also use
hideTab(1, false)

disableTab(Integer tabIdx / String name, FieldScreenTab tab)

Disables a tab - the user can see that the tab exists but cannot switch to it. This may be less confusing than hiding a tab, depending on your requirements. Has an optional second parameter, specifying false will enable the tab.

groovy
disableTab(1) // disables the second tab

enableTab(Integer tabIdx / String name, FieldScreenTab tab)

Enables a tab that was previously disabled by disableTab.

groovy
enableTab(1) // enables the second tab

// you can also use
disableTab(1, false)

switchTab(Integer tabIdx / String name, FieldScreenTab tab)

Switches to a tab. The primary use case for this is to control which tab is displayed when hiding or disabling a tab. If you don’t use switchTab the tab will switch to the left-most unhidden, and enabled tab

groovy
hideTab(0)    // hides the first tab
switchTab(2)  // switches to the third tab

Other field operations

formField.setHelpText(helpText)

 
getFieldById('duedate').setDescription('<div class="error">foo foo</div>')

Add help text under a field, in response to other form events. This is useful to explain to users why fields have become mandatory. To unset it use clearHelpText() or setHelpText("").

groovy
formField.setHelpText("You must enter a value for this field if you select priority Blocker")

Miscellaneous

getRequest()

Gets the servlet request that corresponds with this request for an initialiser, or a field-changed validator.

You might use this to get the IP address of the client, or headers that would let you determine the end-user’s browser.

getResponse()

Gets the servlet response. There is probably no cause to use this.

setConfigParam()

Sets a specific configuration parameter.