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β
| Member | Returns | Description |
|---|---|---|
.value | Any | The 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) | Boolean | true 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() | Boolean | true when the field has no value. |
Change a fieldβ
| Member | Description |
|---|---|
.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.
| Property | Description |
|---|---|
context.viewType | The form: GIC (Create), IssueTransition, IssueView or JSMRequestCreate (service portal). |
context.projectId | The ID of the space. |
context.issueTypeId | The ID of the work type. |
context.accountId | The 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] ?? []);
| Placeholder | Description |
|---|---|
customfield_10050 | The ID of the select field to read, here the department. |
customfield_10051 | The ID of the select field whose options to limit. |
10101, 10102, 10103, 10104 | The 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);
| Placeholder | Description |
|---|---|
team-alpha | The group whose members see the field. |
customfield_10016 | The ID of the field to hide from everyone else. |
Relatedβ
- Write a UI modification script: create a script and test it.
- Conditions and actions: the no-code way to make the same changes.
- Failures on forms: what happens when a script throws.