Rate this page:
This page describes a Forge preview feature. Preview features are deemed stable; however, they remain under active development and may be subject to shorter deprecation windows. Preview features are suitable for early adopters in production environments.
We release preview features so partners and developers can study, test, and integrate them prior to General Availability (GA). For more information about preview features, see What's coming.
To consume the UI Modifications (UIM) API, your app needs to import the @forge/jira-bridge
package:
1 2import { uiModificationsApi } from '@forge/jira-bridge';
This API is strictly related to the Jira UI modifications module
1 2onInit(<initCallback>, <registerFieldsCallback>): void
initCallback
is where apps can query field data and request modifications. registerFieldsCallback
is used to specify which fields will be changed by initCallback
. The information returned by registerFieldsCallback
is used to display a loading indicator next to the relevant fields until initCallback
finishes.
Both callback functions are called every time:
project
or issueType
(from context) changescreate another issue
checkbox enabledThe initCallback
function will receive one object as an argument. This object contains the following attributes:
api
- the API used to find and modify the GIC fieldsuiModifications
- an array of UIM entities registered for a given contextThe registerFieldsCallback
function will receive an object containing:
uiModifications
- an array of UIM entities registered for a given context1 2uiModificationsApi.onInit(({ api, uiModifications }) => { // You can find form fields using the FieldQueryingAPI here const summaryField = api.getFieldById('summary'); // You can manipulate the fields you found if (summaryField) { summaryField.setDescription('New summary description'); } }, ({ uiModifications }) => { // This function should return an array of the IDs of the fields // which are going to be changed in initCallback return ['summary']; })
All modifications requested synchronously using this API will be batched and applied at once.
If a Promise
is returned from the callback, all of the modifications will be postponed until the Promise
resolves.
This may be useful in a scenario when the app needs to perform an async operation before it requests a change.
UIM blocks any changes requested for fields within initCallback
for any field IDs not in the array returned from registerFieldsCallback
.
If the initCallback
doesn’t return a Promise
which resolves after all field modification requests are made, then field modifications requested asynchronously will be ignored.
1 2onChange(<changeCallback>, <registerFieldsCallback>): void
changeCallback
is where apps can query field data and request modifications. registerFieldsCallback
is used to specify which fields will be changed by changeCallback
. The information returned by registerFieldsCallback
is used to display a loading indicator next to the relevant fields until changeCallback
finishes.
Both callback functions are called every time:
blur
form field event is triggered by one of the GIC-supported text fields, which are summary
and description
change
form field event is triggered by any other GIC-supported fieldThe changeCallback
function will receive one object as an argument.
This object contains the following attributes:
api
- the API used to find and modify the GIC fieldschange
- an object with the current
attribute containing the object exposing the FieldAPI
of the field which triggered the change eventuiModifications
- an array of UIM entities registered for a given contextThe registerFieldsCallback
function will receive an object containing:
change
- an object with the current
attribute containing the object exposing the FieldAPI
of the field which triggered the change eventuiModifications
- an array of UIM entities registered for a given context1 2uiModificationsApi.onChange(({ api, change, uiModifications }) => { // You can find form fields using the FieldQueryingAPI here // You can also manipulate the fields you found or access the field // that triggered the change const { current } = change; if (current.getId() === 'summary') { // hint: You may want to read the content of uiModifications before // deciding what changes need to be applied here current.setDescription('New summary description'); } }, ({ change, uiModifications }) => { // This function should return an array of the IDs of the fields // which are going to be changed in changeCallback return ['summary']; })
All modifications requested synchronously using this API will be batched and applied at once.
If a Promise
is returned from the callback
, all of the modifications will be postponed until the Promise
resolves. This may be useful in a scenario when the app needs to perform an async operation before it requests a change.
UIM blocks any changes requested for fields within changeCallback
for any field IDs not in the array returned from registerFieldsCallback
.
If the changeCallback
doesn’t return a Promise
which resolves after all field modification requests are made, then field modifications requested asynchronously will be ignored.
1 2getFieldById<fieldType>(<fieldId>): FieldAPI | undefined
Uses the generic: fieldType
(string) - the type of the field that the app wants to work on.
Accepts one argument: fieldId
(string) - the ID of the field which the app wants to work on.
Returns the FieldAPI object if the field exists on the GIC form.
Returns undefined
if the field doesn't exist on the GIC form.
Example of usage with regular field:
1 2uiModificationsApi.onInit(({ api }) => { const { getFieldById } = api; const description = getFieldById('description') // You can perform operations on 'description' // field using the FieldAPI here }, () => ['description'])
Example of usage with custom field:
1 2uiModificationsApi.onInit(({ api }) => { const { getFieldById } = api; const select = getFieldById<'com.atlassian.jira.plugin.system.customfieldtypes:select'>('customfield_10035') // You can perform operations on 'customfield_10035' // single select field using the FieldAPI here }, () => ['customfield_10035'])
1 2getFields(): FieldAPI[]
Returns an array of FieldAPI objects with all supported fields available on a current view form.
Example of usage:
1 2uiModificationsApi.onInit(({ api }) => { const { getFields } = api; const fields = getFields(); // You can iterate over fields // and perform operations on each // field using the FieldAPI here }, () => [])
The changes requested by setters in this API are not applied immediately.
They are batched and their application is postponed until the onInit
or onChange
callback execution ends.
This means that reading the values using getters will always provide the initial form field state, which is immutable.
1 2getId(): string
Returns the field's ID.
1 2getType(): FieldType
Returns the field's type.
1 2setName(value: string): FieldAPI
Changes the field's name.
Example:
1 2field.setName('New name for the field');
1 2getName(): string
Returns the field's name.
1 2setDescription(value: string): FieldAPI
Changes the field's description.
Example:
1 2field.setDescription('This the description!');
1 2getDescription(): string
Returns the field’s description.
1 2setVisible(value: boolean): FieldAPI
Changes field visibility. The form payload will contain the field’s value, but the field won’t be visible in the UI if this is set to false
.
Example:
1 2field.setVisible(false);
1 2isVisible(): boolean
Returns true
if the field is currently visible. Returns false
otherwise.
1 2setValue(value: unknown): FieldAPI
Set a given field's value. See the specific field value contracts in the supported fields below to make sure the changes requested by this method will be applied.
1 2getValue(): unknown
Set a given field's value. See the specific field value contracts in the supported fields below to make sure the changes requested by this method will be applied.
1 2setReadOnly(value: boolean): FieldAPI
Set if a given field’s value is read-only. If true, the form payload will contain the field’s value, but the user won’t be able to modify the value in the UI.
Example:
1 2field.setReadOnly(true);
1 2isReadOnly(): boolean
Returns true
if the field's value currently can't be modified. Returns false
otherwise.
1 2setRequired(value: boolean): FieldAPI
Set a given field as required. Fields required by system configuration can't be set to non-required. Example:
1 2field.setRequired(true);
1 2isRequired(): boolean
Returns true
if the field is currently required. Returns false
otherwise.
type: priority
The following setValue signature setValue(value: PriorityField): FieldAPI
is deprecated and will be removed after June 28, 2023.
1 2setValue(id: string): FieldAPI
1 2getValue(): PriorityField
1 2{ id: string, // '2' name: string, // 'High' iconUrl?: string, }
type: summary
1 2setValue(id: SummaryField): FieldAPI
1 2getValue(): SummaryField
1 2string
type: assignee
An accountId
of "-1"
is used for the "Automatic" assignee value. null
is used for the "Unassigned" value.
For more information on the "Automatic" assignee value, see https://support.atlassian.com/jira-software-cloud/docs/who-does-the-automatic-assignee-option-assign-an-issue-to/
The following setValue signature setValue(value: AssigneeField): FieldAPI
is deprecated and will be removed after June 28, 2023.
1 2setValue(accountId: string | null): FieldAPI
1 2getValue(): AssigneeField
displayName
and avatarUrls
properties in an assignee field shape are deprecated and will be removed after June 28, 2023.
The new shape will contain accountId
only.
1 2null | { accountId: string, /** @deprecated will be removed */ displayName: string, /** @deprecated will be removed */ avatarUrls?: { '48x48': string, } }
The number of unique accountIds that can be set via the setValue
method can't be greater than 90 per one batched update.
This means that all calls to setValue
for user-based fields performed in a single onInit
or onChange
callback are counted against this limit.
type: reporter
Use null
to unset the value.
1 2setValue(accountId: string | null): FieldAPI
1 2getValue(): ReporterField
1 2null | { accountId: string }
The number of unique accountIds that can be set via the setValue
method can't be greater than 90 per one batched update.
This means that all calls to setValue
for user-based fields performed in a single onInit
or onChange
callback are counted against this limit.
type: labels
1 2setValue(id: LabelsField): FieldAPI
1 2getValue(): LabelsField
1 2string[]
type: description
The description
field can be configured using either the rich-text "Wiki style renderer" (current default) or plain-text "Default style renderer". Each renderer requires a different value type, and apps will need to match the type they receive from getValue
in any calls to setValue
.
For more information on how to configure field renderers, please refer to https://support.atlassian.com/jira-cloud-administration/docs/configure-renderers/
1 2setValue(id: DescriptionField): FieldAPI
1 2getValue(): DescriptionField
1 2string // Plain-text editor | type ADF = { version: 1, type: 'doc', content: Node[] } // Rich-text editor (ADF format) // https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
type: com.atlassian.jira.plugin.system.customfieldtypes:select
Use null
to unset the value.
The following setValue signature setValue(value: SelectField): FieldAPI
is deprecated and will be removed after June 28, 2023.
1 2setValue(id: string): FieldAPI
1 2getValue(): SelectField
The name
property will be removed in favor of the value
property after June 28, 2023.
1 2null | { id: string, value: string, /** @deprecated use `value` instead of `name` */ name: string }
type: com.atlassian.jira.plugin.system.customfieldtypes:multiselect
Use []
to unset the value.
The following setValue signature setValue(value: MultiSelectField): FieldAPI
is deprecated and will be removed after June 28, 2023.
1 2setValue(id: string[]): FieldAPI
1 2getValue(): MultiSelectField
The name
property will be removed in favor of the value
property after June 28, 2023.
1 2[ { id: string, value: string, /** @deprecated use `value` instead of `name` */ name: string }, { id: string, value: string, /** @deprecated use `value` instead of `name` */ name: string }, ... ]
type: com.atlassian.jira.plugin.system.customfieldtypes:multicheckboxes
Use []
to unset the value.
1 2setValue(id: string[]): FieldAPI
1 2getValue(): MultiCheckboxesField
1 2[ { id: string, value: string, }, { id: string, value: string, }, ... ]
type: com.atlassian.jira.plugin.system.customfieldtypes:textarea
1 2setValue(value: ParagraphField): FieldAPI
1 2getValue(): ParagraphField
1 2string // Plain-text editor | type ADF = { version: 1, type: 'doc', content: Node[] } // Rich-text editor (ADF format) // https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
type: com.atlassian.jira.plugin.system.customfieldtypes:textfield
1 2setValue(value: TextField): FieldAPI
1 2getValue(): TextField
1 2string // Plain-text editor
type: com.atlassian.jira.plugin.system.customfieldtypes:userpicker
Use null
to unset the value.
The following setValue signature setValue(value: UserPickerField): FieldAPI
is deprecated and will be removed after June 28, 2023.
1 2setValue(accountId: string | null): FieldAPI
1 2getValue(): UserPickerField
displayName
and avatarUrls
properties in user picker field shape are deprecated and will be removed after June 28, 2023.
The new shape will contain accountId
only.
1 2null | { accountId: string, /** @deprecated will be removed */ displayName: string, /** @deprecated will be removed */ avatarUrls?: { '48x48': string, } }
The number of unique accountIds that can be set via the setValue
method can't be greater than 90 per one batched update.
This means that all calls to setValue
for user-based fields performed in a single onInit
or onChange
callback are counted against this limit.
type: com.atlassian.jira.plugin.system.customfieldtypes:multiuserpicker
Use []
to unset the value.
The following setValue signature setValue(value: MultiUserPickerField): FieldAPI
is deprecated and will be removed after June 28, 2023.
1 2setValue(accountId: string[]): FieldAPI
1 2getValue(): MultiUserPickerField
displayName
and avatarUrls
properties in multiple user picker field shape are deprecated and will be removed after June 28, 2023.
The new shape will contain accountId
only.
1 2[ { accountId: string, /** @deprecated will be removed */ displayName: string, /** @deprecated will be removed */ avatarUrls? : { '48x48': string, } }, { accountId: string, /** @deprecated will be removed */ displayName: string, /** @deprecated will be removed */ avatarUrls? : { '48x48': string, } }, ... ]
The number of unique accountIds that can be set via the setValue
method can't be greater than 90 per one batched update.
This means that all calls to setValue
for user-based fields performed in a single onInit
or onChange
callback are counted against this limit.
type: com.atlassian.jira.plugin.system.customfieldtypes:people
This field is available in a team-managed project only.
The people
field can be configured using either the single or multiple value field. In the case of a single value configuration, only the first value from the array provided via the setValue
will be displayed in the field.
Use []
to unset the value.
1 2setValue(accountId: string[]): FieldAPI
1 2getValue(): PeopleField
1 2[ { accountId: string, }, { accountId: string, }, ... ]
The number of unique accountIds that can be set via the setValue
method can't be greater than 90 per one batched update.
This means that all calls to setValue
for user-based fields performed in a single onInit
or onChange
callback are counted against this limit.
Rate this page: