Skip to main content

UI modification script API

This page lists what a UI modification script can read and change on a Jira form.

Applies to: Script Master for Jira Β· Cloud

How a script runs​

A script runs in the browser of the person filling in the form: once when the form opens, then again after each change. It runs after the rules of every UI modification on the form, so it can change what rules set. When several scripts apply, each runs in turn.

The script is the body of an async function, so you can use await and return at the top level. It receives four names: field, change, context and jira.

Changes are collected while the script runs and applied together when it finishes. If the script throws an error, none of its changes are applied and a failure is counted. The rest of the form keeps working. See Failures on forms.

field(id)​

Returns a field on the form by its ID, for example field('summary'), field('duedate') or field('customfield_10050'). Calls chain, so one line can make several changes:

field('duedate').visible().required();

If the form doesn't have the field, changes to it are skipped.

Read a field​

MemberReturnsDescription
.valueAnyThe field's value when the script started, as the form reports it. Options are objects, for example field('priority').value?.name. Setting a value doesn't change .value.
.is(...values)Booleantrue when the field has any of the values. Matches like a rule condition: an option by its name or ID, a user by account ID.
.isEmpty()Booleantrue when the field has no value.

Change a field​

MemberDescription
.visible(isVisible)Shows the field, or hides it with visible(false).
.required(isRequired)Makes the field required, or optional with required(false).
.readOnly(isReadOnly)Makes the field read-only, or editable with readOnly(false).
.name(text)Changes the field's label.
.description(text)Sets the field's hint. On the Create dialog, Jira shows it behind View details.
.set(value)Sets the field's value. The value must have the shape Jira expects for that field type.
.showOptions(ids)Offers only the options with these IDs.
.hideOptions(ids)Removes the options with these IDs.
.restore(...properties)Puts properties back to how they were when the form opened: 'visible', 'required', 'readOnly', 'name', 'description' or 'optionsVisibility'. A value can't be restored.

visible(), required() and readOnly() without an argument mean true.

change​

change is undefined when the form opens. After a change, change.id is the ID of the field that changed.

if (change?.id === 'priority') {
const urgent = field('priority').value?.name === 'Highest';
field('duedate').visible(urgent).required(urgent);
}

context​

Where the form is and who is filling it in.

PropertyDescription
context.viewTypeThe form: GIC (Create), IssueTransition, IssueView or JSMRequestCreate (service portal).
context.projectIdThe ID of the space.
context.issueTypeIdThe ID of the work type.
context.accountIdThe account ID of the person filling in the form.
if (context.viewType === 'GIC') {
field('duedate').required();
}

jira.get(path)​

Sends a GET request to the Jira REST API and returns the parsed JSON response. The path must start with /rest/.

const me = await jira.get('/rest/api/3/myself');
field('summary').description(`Reporting as ${me.displayName}`);

The request runs as the person filling in the form, with their permissions. If Jira answers with an error, jira.get throws, for example GET /rest/api/3/component/10000 failed with 404. Scripts can only read from Jira: a script that calls anything other than jira.get can't be saved.

Fields a script can change​

Jira only lets a UI modification change fields it declares in advance. Script Master declares every field your script names in quotes, such as field('customfield_10050').

A field ID built while the script runs, such as field(`customfield_${id}`), isn't found this way, and changes to it are skipped. To declare such a field, export the UI modification, add its ID to the "scriptFieldIds" list in the JSON, and import it again. See Import and export UI modifications.

Examples​

Assignee from the component lead​

When Components changes, read the first component and set Assignee to its lead.

if (change?.id !== 'components') return;
const picked = field('components').value?.[0];
if (!picked) return;
const component = await jira.get(`/rest/api/3/component/${picked.id}`);
field('assignee').set(component.leadAccountId ?? null);

Options that follow another field​

Offer only the laptop models that fit the picked department.

const optionsByDepartment = {
Design: ['10101', '10102'],
Engineering: ['10103', '10104'],
};
const department = field('customfield_10050').value?.value;
field('customfield_10051').showOptions(optionsByDepartment[department] ?? []);
PlaceholderDescription
customfield_10050The ID of the select field to read, here the department.
customfield_10051The ID of the select field whose options to limit.
10101, 10102, 10103, 10104The IDs of the options to offer. The field picker in a rule shows them.

Hide a field from people outside a group​

const me = await jira.get('/rest/api/3/myself?expand=groups');
const isTeam = me.groups.items.some(group => group.name === 'team-alpha');
field('customfield_10016').visible(isTeam);
PlaceholderDescription
team-alphaThe group whose members see the field.
customfield_10016The ID of the field to hide from everyone else.