API Quick Reference

Getting form fields

getFieldById(fieldId)

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

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

getFieldByName(fieldName)

Same as above but uses the name

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

getFieldChanged()

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

 
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.

 
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

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

formField.setRequired(true/false)

Makes this a required field or not.

 
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.

 
formField.setHidden(true)

formField.setReadOnly(true/false)

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

 
formField.setReadOnly(true)

formField.setFormValue(value)

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

 
formField.setFormValue("Documentation subtask")

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.

 
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.

 
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.

 
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.

 
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.

 
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.

 
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.

 
disableTab(1) // disables the second tab

enableTab(Integer tabIdx / String name, FieldScreenTab tab)

Enables a tab that was previously disabled by disableTab.

 
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

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

Other field operations

formField.setHelpText(helpText)

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("").

 
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.