Field Behaviours

Field Behaviours are the individual rules you apply to specific fields within a Behaviour configuration. Each rule defines what should happen to a field — whether it should be visible, required, have a value set, or respond to user changes.

Setting Up Field Rules

When creating or editing a Behaviour, you define rules for individual fields:

1. Select a field from the form (Summary, Priority, custom fields, etc.)
2. Choose the trigger: onInit (when form opens) or onChange (when that field changes)
3. Write the script that modifies one or more fields

Field Modification Methods — Complete Reference

setRequired(boolean)

Makes a field mandatory. The form cannot be submitted without filling it.

// Make "Component" required for all Bug tickets
fields.components.setRequired(true);

setVisible(boolean)

Shows or hides a field entirely. Hidden fields don't appear on the form at all.

// Hide the "Sprint" field on the Create screen for Epics
if (context.issueType === 'Epic') {
  fields.getFieldById('customfield_10020').setVisible(false);
}

setDescription(string)

Changes the help text displayed below the field. Useful for context-sensitive guidance.

fields.summary.setDescription('Start with the component name: [Auth] Login fails...');

setName(string)

Changes the display label of the field.

// Rename "Story Points" to "Effort Estimate" for non-technical teams
fields.getFieldById('customfield_10016').setName('Effort Estimate');

setValue(value)

Sets or changes the field's current value.

// Auto-set the assignee to the reporter when priority is Critical
if (fields.priority.getValue() === 'Critical') {
  fields.assignee.setValue(context.reporter);
}

setDefault(value)

Sets the initial value on create screens. Only effective in isCreateView().

if (isCreateView()) {
  fields.priority.setDefault('Medium');
}

setReadOnly(boolean)

Prevents the user from editing the field.

// Lock priority on transition screens
if (isTransitionView()) {
  fields.priority.setReadOnly(true);
}

setOptionsVisibility(map)

Controls which options appear in a select/dropdown field. Pass an object where keys are option names and values are booleans.

// In a "Production" project, hide the "Trivial" priority option
fields.priority.setOptionsVisibility({
  'Critical': true,
  'High': true,
  'Medium': true,
  'Low': true,
  'Trivial': false
});

Reading Field Values

getValue()

const currentPriority = fields.priority.getValue();
const summary = fields.summary.getValue();

getFieldById(fieldId)

Access any field by its Jira field ID (e.g., customfield_10001):

const teamField = fields.getFieldById('customfield_10042');
const teamValue = teamField.getValue();

Checking Current State

if (fields.dueDate.isRequired()) { ... }
if (fields.components.isVisible()) { ... }
if (fields.summary.isReadOnly()) { ... }

Combining Multiple Rules

A single behaviour script can modify multiple fields:

// onInit: Set up the entire form based on issue type
if (context.issueType === 'Bug') {
  fields.getFieldById('customfield_10001').setVisible(true);   // "Steps to Reproduce"
  fields.getFieldById('customfield_10001').setRequired(true);
  fields.getFieldById('customfield_10002').setVisible(true);   // "Browser/OS"
  fields.severity.setRequired(true);
  fields.dueDate.setRequired(true);
  
} else if (context.issueType === 'Story') {
  fields.getFieldById('customfield_10001').setVisible(false);
  fields.getFieldById('customfield_10002').setVisible(false);
  fields.getFieldById('customfield_10016').setRequired(true);  // Story Points
}

onChange Patterns

The context.change object tells you which field changed:

// onChange handler
if (context.change.field === 'priority') {
  handlePriorityChange(context.change.value);
} else if (context.change.field === 'components') {
  handleComponentChange(context.change.value);
}

function handlePriorityChange(priority) {
  if (priority === 'Critical' || priority === 'High') {
    fields.assignee.setRequired(true);
  } else {
    fields.assignee.setRequired(false);
  }
}

function handleComponentChange(component) {
  // Show environment field only for infrastructure components
  const infraComponents = ['Database', 'Network', 'Cloud'];
  fields.getFieldById('customfield_10050').setVisible(
    infraComponents.includes(component)
  );
}