Getting form fields

getFieldById(fieldId)

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

getFieldById("customfield_11111")
getFieldById("summary")
GROOVY
getFieldByName(fieldName)

Same as above but uses the name

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

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

getFieldById(getFieldChanged())
GROOVY

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")
GROOVY
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?')
GROOVY
formField.setRequired(true/false)

Makes this a required field or not.

formField.setRequired(true)
GROOVY
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)
GROOVY
formField.setReadOnly(true/false)

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

formField.setReadOnly(true)
GROOVY
 formField.setFormValue(value)

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

formField.setFormValue("Documentation subtask")
GROOVY

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.

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

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

Sets the description for a form field.

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

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
GROOVY
getRequestTypeName()

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

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

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)
GROOVY
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)
GROOVY
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
GROOVY
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)
GROOVY
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
GROOVY

Other field operations

formField.setHelpText(helpText)

Deprecated. 

setHelpText  sets an error message under the field, in the same way that setError  does. However,  setError prevents the form from being submitted, until clearError  is called on the field. Using setHelpText  makes it appear the field is in an error state, but the user is allowed to submit the form.

Because of this ambiguity, setHelpText  is deprecated and should not be used.

To set explanatory text, use setDescription.  If you wish to show something that looks like an error message (but does not prevent the form being submitted), you can use a CSS class or styles:

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


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")
GROOVY

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.