UI Kit components
Jira UI Kit components
UI Kit hooks
Forge bridge APIs
Jira bridge APIs
Upgrade UI Kit versions
Previous versions

uiModifications

To consume the UI Modifications (UIM) API, your app needs to import the @forge/jira-bridge package:

1
2
import { uiModificationsApi } from '@forge/jira-bridge';

This API is strictly related to the Jira UI modifications module

Initialization

onInit method signature

1
2
onInit(<initCallback>, <registerFieldsCallback>): void

onInit method description

initCallback is where apps can query field/screen tab 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. There is no need to register screen tabs in order to modify them.

Both callback functions are called every time:

  • the Global issue create (GIC), Issue view or Issue transition is opened from a supported entry point
  • the project or issueType (from context) changes
  • GIC only: an issue is created with the create another issue checkbox enabled

The initCallback function will receive one object as an argument. This object contains the following attributes:

  • api - the API used to find and modify fields and/or screen tabs
  • uiModifications - an array of UIM entities registered for a given context

The registerFieldsCallback function will receive an object containing:

  • uiModifications - an array of UIM entities registered for a given context
1
2
uiModificationsApi.onInit(({ api, uiModifications }) => {
  // You can find form fields using the FieldsHookApi
  const summary = api.getFieldById('summary');
  // You can manipulate the fields you found
  if (summary) {
    summary.setDescription('New summary description');
  }
  // You can find screen tabs using the ScreenTabsHookApi
  const tabs = api.getScreenTabs();
  // You can manipulate the tabs you found
  if (Array.isArray(tabs) && tabs.length > 0) {
    tabs[0].setVisible(true);
    tabs[0].focus();
  }
}, ({ 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. That means that consecutive modifications applied by the same FieldAPI/ScreenTabAPI method within the onInit callback will override the previous ones.

1
2
uiModificationsApi.onInit(({ api }) => {
    const { getFieldById } = api;
    const summary = getFieldById('summary');

    summary.setDescription('First description'); // will be overridden by the next `summary.setDescription` call
    summary.setDescription('Second description'); //  this change will be applied
}, ({ uiModifications }) => {
    return ['summary'];
})

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.

Warning

UIM blocks any changes requested for fields within initCallback for any field IDs not in the array returned from registerFieldsCallback.

Warning

If the initCallback doesn’t return a Promise which resolves after all field and tab modification requests are made, then field and tab modifications requested asynchronously will be ignored.

Reacting to change

onChange method signature

1
2
onChange(<changeCallback>, <registerFieldsCallback>): void

onChange method description

changeCallback is where apps can query field/screen tab 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. There is no need to register screen tabs in order to modify them.

Both callback functions are called every time:

  • the blur field event is triggered by one of the supported text fields, which are summary and description
  • the change field event is triggered by any other supported field (for select-type fields when the user picks an option; for Issue view when the user commits a value)

The changeCallback function will receive one object as an argument. This object contains the following attributes:

  • api - the API used to find and modify fields and/or screen tabs
  • change - an object with the current attribute containing the object exposing the FieldAPI of the field which triggered the change event
  • uiModifications - an array of UIM entities registered for a given context

The 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 event
  • uiModifications - an array of UIM entities registered for a given context
1
2
uiModificationsApi.onChange(({ api, change, uiModifications }) => {
  // You can find form fields using the FieldsHookApi
  // 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');
  }
  // You can find screen tabs using the ScreenTabsHookApi
  const tabs = api.getScreenTabs();
  // You can manipulate the tabs you found
  if (Array.isArray(tabs) && tabs.length > 0) {
    tabs[0].setVisible(true);
    tabs[0].focus();
  }
}, ({ 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. That means that consecutive modifications applied by the same FieldAPI/ScreenTabAPI method within the onChange callback will override the previous ones.

1
2
uiModificationsApi.onChange(({ api }) => {
    const { getFieldById } = api;
    const summary = getFieldById('summary');

    summary.setDescription('First description'); // will be overridden by the next `summary.setDescription` call
    summary.setDescription('Second description'); //  this change will be applied
}, ({ uiModifications }) => {
    return ['summary'];
})

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.

Warning

UIM blocks any changes requested for fields within changeCallback for any field IDs not in the array returned from registerFieldsCallback.

Warning

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.

Error handling

onError method signature

1
2
onError(<errorCallback>): void

onError method description

An errorCallback is where apps can process information about the errors that happened during the execution of UI modifications. The callback function is called when:

  • a validation error occurs, which means data passed to one of the FieldAPI or ScreenTabAPI methods was invalid
  • a conflict error occurs, which means multiple apps attempted to call the same FieldAPI or ScreenTabAPI method on the same field or tab

The errorCallback function will receive one object as an argument. This object contains the following attributes:

  • errors - the array of objects with error data
1
2
uiModificationsApi.onError(({ errors }) => {
    // you can process errors' data in the errorCallback
    for (const error of errors) {
        if (error.type === 'FIELD_VALIDATION_FAILED') {
            logFieldValidationError(error);
        }

        if (error.type === 'SCREENTABS_VALIDATION_FAILED') {
            logScreenTabsValidationError(error);
        }

        if (error.type === 'MULTIPLE_APPS_CONFLICT') {
            logConflictError(error);
        }
    }
})

field validation error shape

1
2
{
    type: 'FIELD_VALIDATION_FAILED',
    fieldId: string,
    fieldType: string,
    method: string, // for example: setRequired
    message?: string; // additional information about the error
}

screen tab validation error shape

1
2
{
    type: 'SCREENTABS_VALIDATION_FAILED',
    message?: string; // additional information about the error
}

conflict error shape

1
2
{
    type: 'MULTIPLE_APPS_CONFLICT',
    cause: 'FIELD',
    fieldId: string;
    fieldType: string;
    lifecycleHook: 'onInit' | 'onChange';
    method: string, // for example: setValue
    message: string; // additional information about the error
}

Querying fields

getFieldById method signature

1
2
getFieldById<fieldType>(<fieldId>): FieldAPI | undefined

getFieldById method description

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 supported view.

Returns undefined if the field doesn't exist or isn’t supported by UIM.

Example of usage with regular field:

1
2
uiModificationsApi.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
2
    uiModificationsApi.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'])

Iterating over supported fields

getFields method signature

1
2
getFields(): FieldAPI[]

getFields method description

Returns an array of FieldAPI objects with all supported fields available on a current view form.

Example of usage:

1
2
uiModificationsApi.onInit(({ api }) => {
  const { getFields } = api;
  const fields = getFields();
  // You can iterate over fields
  // and perform operations on each
  // field using the FieldAPI here
}, () => []) 

Supported fields per view

Support for custom fields

Global issue create

Field / methodssetName
getName
setDescription
getDescription
setVisible
isVisible
setValue
getValue
setReadOnly
isReadOnly
setRequired
isRequired
setOptionsVisibility
getOptionsVisibility
affects versions yes yes yes yes yes yes no
assignee yes yes yes yes yes yes no
cascading select yes yes yes yes yes yes no
components yes yes yes yes yes yes no
checkboxes yes yes yes yes yes yes yes
date picker yes yes yes yes yes yes no
date time picker yes yes yes yes yes yes no
description yes yes yes yes yes yes no
due date yes yes yes yes yes yes no
fix versions yes yes yes yes yes yes no
issue type no no no yes no no yes
labels yes yes yes yes yes yes no
multi select yes yes yes yes yes yes yes
multi user picker yes yes yes yes yes yes no
number yes yes yes yes yes yes no
paragraph yes yes yes yes yes yes no
parent yes yes yes yes yes yes no
people yes yes yes yes yes yes no
priority yes yes yes yes yes yes yes
radio buttons yes yes yes yes yes yes yes
reporter yes yes yes yes yes yes no
single select yes yes yes yes yes yes yes
summary yes yes yes yes yes yes no
target start yes yes yes yes yes yes no
target end yes yes yes yes yes yes no
text field yes yes yes yes yes yes no
url yes yes yes yes yes yes no
user picker yes yes yes yes yes yes no

Issue view (preview)

This section 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, see Forge release phases: EAP, Preview, and GA.

Field / methodssetName
getName
setDescription
getDescription
setVisible
isVisible
setValue
getValue
setReadOnly
isReadOnly
setRequired
isRequired
setOptionsVisibility
getOptionsVisibility
affects versions yes yes yes yes yes no no
assignee yes yes yes yes yes no no
cascading select yes yes yes yes yes no no
components yes yes yes yes yes no no
checkboxes yes yes yes yes yes no yes
date picker yes yes yes yes yes no no
date time picker yes yes yes yes yes no no
description yes no yes yes yes no no
fix versions yes yes yes yes yes no no
labels yes yes yes yes yes no no
multi select yes yes yes yes yes no yes
multi user picker yes yes yes yes yes no no
number yes yes yes yes yes no no
original estimate yes yes yes yes yes no no
paragraph yes yes yes yes yes no no
parent yes yes yes yes yes no no
people yes yes yes yes yes no no
priority yes no yes yes yes no no
radio buttons yes yes yes yes yes no no
reporter yes yes yes yes yes no no
single select yes yes yes yes yes no yes
status no no no yes no no no
summary no no no yes yes no no
text field yes yes yes yes yes no no
url yes yes yes yes yes no no
user picker yes yes yes yes yes no no

Issue transition (preview)

This section 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, see Forge release phases: EAP, Preview, and GA.

Field / methodssetName
getName
setDescription
getDescription
setVisible
isVisible
setValue
getValue
setReadOnly
isReadOnly
setRequired
isRequired
setOptionsVisibility
getOptionsVisibility
assignee yes yes yes yes yes yes no
cascading select yes yes yes yes yes yes no
checkboxes yes yes yes yes yes yes yes
date picker yes yes yes yes yes yes no
date time picker yes yes yes yes yes yes no
description yes yes yes yes yes yes no
affects versions yes yes yes yes yes yes yes
fix versions yes yes yes yes yes yes yes
issue type no no no yes no no yes
labels yes yes yes yes yes yes no
multi select yes yes yes yes yes yes yes
number yes yes yes yes yes yes no
paragraph yes yes yes yes yes yes no
parent yes yes yes yes yes yes yes
priority yes yes yes yes yes yes yes
radio buttons yes yes yes yes yes yes yes
reporter yes yes yes yes yes yes no
resolution yes yes yes yes yes no yes
single select yes yes yes yes yes yes yes
text field yes yes yes yes yes yes no
url yes yes yes yes yes yes no
user picker yes yes yes yes yes yes no
multi user picker yes yes yes yes yes yes no
original estimate yes yes yes yes yes yes no

Common FieldAPI

Warning

The changes requested by setters in this API aren't applied immediately. They're batched and only applied after the execution of the onInit or onChange callback ends. This means that reading the values using getters will always provide the initial form field state, which is immutable.

getId

1
2
getId(): string

Returns the field's ID.

getType

1
2
getType(): FieldType

Returns the field's type.

setName

1
2
setName(value: string): FieldAPI

Changes the field's name.

Example:

1
2
field.setName('New name for the field');

getName

1
2
getName(): string

Returns the field's name.

setDescription

1
2
setDescription(value: string): FieldAPI

Changes the field's description.

Example:

1
2
field.setDescription('This the description!');

getDescription

1
2
getDescription(): string

Returns the field’s description.

setVisible

1
2
setVisible(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
2
field.setVisible(false);

isVisible

1
2
isVisible(): boolean

Returns true if the field is currently visible. Returns false otherwise.

setValue

1
2
setValue(value: unknown): FieldAPI

Set a given field's value. See the specific field value contracts in the Field details section below to make sure the changes requested by this method will be applied.

getValue

1
2
getValue(): unknown

See the field contracts below to learn the shape of the data returned by each field.

setReadOnly

1
2
setReadOnly(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
2
field.setReadOnly(true);

Empty read-only fields on the Issue view

On the Issue view, fields that don't have a value are automatically hidden when set to read-only. This is the default behavior when the user doesn't have permission to edit.

isReadOnly

1
2
isReadOnly(): boolean

Returns true if the field's value currently can't be modified. Returns false otherwise.

setRequired

1
2
setRequired(value: boolean): FieldAPI

Set a given field as required. Fields required by system configuration can't be set to non-required. Example:

1
2
field.setRequired(true);

isRequired

1
2
isRequired(): boolean

Returns true if the field is currently required. Returns false otherwise.

setOptionsVisibility

1
2
setOptionsVisibility(options: string[], isVisible: boolean): FieldAPI

Applies a visibility rule based on a list of option ids and isVisible arguments for a given field's dropdown list of options.

Note that the method only allows you to either make some options visible or make some options hidden, not both.

Example:

1
2
// Only display the enumerated options, others will be hidden
field.setOptionsVisibility(['field-option-id-1', 'field-option-id-2'], true);

// Only hide the enumerated options, others will be visible
field.setOptionsVisibility(['field-option-id-1', 'field-option-id-2'], false);

// Special case, hide all options in the dropdown
field.setOptionsVisibility([], true);

Options hidden in the dropdown can still be selected as a field's default value or by using field.setValue.

Known limitation

In Issue view and Issue transition, the number of options that can be set via the setOptionsVisibility method can't be greater than 100 per one update.

This means that each field with setOptionsVisibility support has its own 100 options limit.

getOptionsVisibility

1
2
getOptionsVisibility(): OptionsVisibility | undefined

Returns an object containing the isVisible: boolean and options: string[] attributes. The options attribute contains IDs of options with modified visibility.

This method, when called within the onInit callback, always returns undefined, meaning the visibility of options wasn't yet modified by setOptionsVisibility.

Field details

issue type

type: issuetype

setValue signature

Warning

The execution of the setValue method will initiate a UIM context change in Global issue create (GIC). Issue type is a part of the UIM invocation context. Changing the issue type with setValue changes that context.

UI modifications won’t be applied to an issue type field that’s out of the UIM app invocation context.

Note that issue types have different UIM app invocation contexts, so UIM functionality may not be applied the same way, in particular when it comes to setting visibility of options.

1
2
setValue(id: string): FieldAPI

getValue signature

1
2
getValue(): IssueTypeField

issue type field shape

1
2
{
    id: string,
    name: string,
}

Reference screenshots

priority

type: priority

setValue signature

1
2
setValue(id: string): FieldAPI

getValue signature

1
2
getValue(): PriorityField

Priority field shape

1
2
{ 
  id: string,   // '2'
  name: string, // 'High'
  iconUrl?: string,
}

Reference screenshot

Resolution

type: resolution

setValue signature

Special values

Use null to unset the value.

1
2
setValue(id: string | null): FieldAPI

getValue signature

1
2
getValue(): ResolutionField

Resolution field shape

1
2
{ 
  id: string,
  value: string,
} | null

Reference screenshot

summary

type: summary

setValue signature

1
2
setValue(id: SummaryField): FieldAPI

getValue signature

1
2
getValue(): SummaryField

Summary field shape

1
2
string

Reference screenshot

assignee

type: assignee

setValue signature

Special values

1
2
setValue(accountId: string | null): FieldAPI

getValue signature

1
2
getValue(): AssigneeField

Assignee field shape

1
2
null | {
    accountId: string,
}

Known limitation

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.

Reference screenshot

reporter

type: reporter

setValue signature

Special values

Use null to unset the value.

1
2
setValue(accountId: string | null): FieldAPI

getValue signature

1
2
getValue(): ReporterField

reporter field shape

1
2
null | {  accountId: string }

Known limitation

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.

Reference screenshots

labels

type: labels

setValue signature

1
2
setValue(ids: string[]): FieldAPI

getValue signature

1
2
getValue(): LabelsField

labels field shape

1
2
string[]

Reference screenshot

description

type: description

Warning

setValue signature

1
2
setValue(value: DescriptionField): FieldAPI

getValue signature

1
2
getValue(): DescriptionField

description field shape (Global issue create, Issue transition)

1
2
string // 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/

description field shape (Issue view)

1
2
type ADF = {
    version: 1,
    type: 'doc',
    content: Node[]
} // Rich-text editor (ADF format)
// https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/

Reference screenshots

components

type: components

Field usage

setValue signature

Special values

Use [] to unset the value.

1
2
setValue(ids: string[]): FieldAPI

getValue signature

1
2
getValue(): ComponentsField

components field shape

1
2
[
    {
        id: string,
        name: string,
    },
    {
        id: string,
        name: string,
    },
    ...
  ]

Reference screenshots

fix versions

type: fixVersions

setValue signature

Special values

Use [] to unset the value.

1
2
setValue(ids: string[]): FieldAPI

getValue signature

1
2
getValue(): FixVersionsField

fix versions field shape

1
2
[
    {
        id: string,
        name: string,
    },
    {
        id: string,
        name: string,
    },
    ...
  ]

Known limitation

In Issue view and Issue transition, you can only set up to 100 IDs per update using the setValue method.

This means that each supported field has its own limit of 100 IDs.

Reference screenshots

affects versions

type: versions

Field usage

setValue signature

Special values

Use [] to unset the value.

1
2
setValue(ids: string[]): FieldAPI

getValue signature

1
2
getValue(): VersionsField

affects versions field shape

1
2
[
    {
        id: string,
        name: string,
    },
    {
        id: string,
        name: string,
    },
    ...
  ]

Known limitation

You can only set up to 100 IDs per update using the setValue method.

This means that each field of this type has its own limit of 100 IDs.

Reference screenshots

single select

type: com.atlassian.jira.plugin.system.customfieldtypes:select

setValue signature

Special values

Use null to unset the value.

1
2
setValue(id: string): FieldAPI

getValue signature

1
2
getValue(): SelectField

select field shape

1
2
null | {
    id: string,
    value: string,
}

Reference screenshots

multi select

type: com.atlassian.jira.plugin.system.customfieldtypes:multiselect

setValue signature

Special values

Use [] to unset the value.

1
2
setValue(ids: string[]): FieldAPI

getValue signature

1
2
getValue(): MultiSelectField

multi select field shape

1
2
[
    {
        id: string,
        value: string,
    },
    {
        id: string,
        value: string,
    },
    ...
]

Known limitation

In Issue view and Issue transition, you can only set up to 100 IDs per update using the setValue method.

This means that each supported field has its own limit of 100 IDs.

Reference screenshots

Cascading select

type: com.atlassian.jira.plugin.system.customfieldtypes:cascadingselect

setValue signature

Special values

Use null to unset the value.

1
2
setValue(value: {
    parentId: string;
    childId: string | null;
} | null): FieldAPI

getValue signature

1
2
getValue(): CascadingSelectField

cascading select field shape

1
2
null | {
    parent: { id: string; value: string };
    child: { id: string; value: string } | null;
}

Reference screenshots

checkboxes

type: com.atlassian.jira.plugin.system.customfieldtypes:multicheckboxes

setValue signature

Special values

Use [] to unset the value.

1
2
setValue(ids: string[]): FieldAPI

getValue signature

1
2
getValue(): MultiCheckboxesField

checkboxes field shape

1
2
[
    {
        id: string,
        value: string,
    },
    {
        id: string,
        value: string,
    },
    ...
]

Known limitation

In Issue view and Issue transition, you can only set up to 100 IDs per update using the setValue method.

This means that each supported field has its own limit of 100 IDs.

Reference screenshots

radio buttons

type: com.atlassian.jira.plugin.system.customfieldtypes:radiobuttons

setValue signature

Special values

Use null to unset the value.

1
2
setValue(id: string | null): FieldAPI

getValue signature

1
2
getValue(): RadioButtonsField

radio buttons field shape

1
2
null | {
    id: string,
    value: string,
}

Reference screenshots

paragraph

type: com.atlassian.jira.plugin.system.customfieldtypes:textarea

setValue signature

1
2
setValue(value: ParagraphField): FieldAPI

getValue signature

1
2
getValue(): ParagraphField

paragraph field shape

1
2
string // 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/

Reference screenshots

text field

type: com.atlassian.jira.plugin.system.customfieldtypes:textfield

setValue signature

1
2
setValue(value: TextField): FieldAPI

getValue signature

1
2
getValue(): TextField

text field shape

1
2
string // Plain-text editor

Reference screenshots

user picker

type: com.atlassian.jira.plugin.system.customfieldtypes:userpicker

setValue signature

Special values

Use null to unset the value.

1
2
setValue(accountId: string | null): FieldAPI

getValue signature

1
2
getValue(): UserPickerField

user picker field shape

1
2
null | {
    accountId: string,
}

Known limitation

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.

Reference screenshots

multi user picker

type: com.atlassian.jira.plugin.system.customfieldtypes:multiuserpicker

setValue signature

Special values

Use [] to unset the value.

1
2
setValue(accountId: string[]): FieldAPI

getValue signature

1
2
getValue(): MultiUserPickerField

multi user picker field shape

1
2
[
    {
        accountId: string,
    },
    {
        accountId: string,
    },
    ...
  ]

Known limitation

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.

Reference screenshots

people

type: com.atlassian.jira.plugin.system.customfieldtypes:people

Field usage

Warning

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.

setValue signature

Special values

Use [] to unset the value.

1
2
setValue(accountId: string[]): FieldAPI

getValue signature

1
2
getValue(): PeopleField

people field shape

1
2
[
    {
        accountId: string,
    },
    {
        accountId: string,
    },
    ...
  ]

Known limitation

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.

Reference screenshots

url

type: com.atlassian.jira.plugin.system.customfieldtypes:url

setValue signature

1
2
setValue(url: string): FieldAPI

getValue signature

1
2
getValue(): UrlField

url field shape

1
2
string

Reference screenshots

date picker

type: com.atlassian.jira.plugin.system.customfieldtypes:datepicker

setValue signature

Special values

Use null to unset the value.

Warning

The provided string must be in the yyyy-MM-dd date format.

1
2
setValue(date: string | null): FieldAPI

getValue signature

1
2
getValue(): DatePickerField

date picker field shape

1
2
string | null

Reference screenshots

date time picker

type: com.atlassian.jira.plugin.system.customfieldtypes:datetime

setValue signature

Special values

Use null to unset the value.

Warning

The provided string must be in the YYYY-MM-DDThh:mmTZD date format.

1
2
setValue(value: string | null): FieldAPI

getValue signature

1
2
getValue(): DatePickerField

date picker field shape

1
2
string | null

Reference screenshots

due date

type: duedate

setValue signature

Special values

Use null to unset the value.

Warning

The provided string must be in the yyyy-MM-dd date format.

1
2
setValue(date: string | null): FieldAPI

getValue signature

1
2
getValue(): DatePickerField

date picker field shape

1
2
string | null

Reference screenshots

target start

type: com.atlassian.jpo:jpo-custom-field-baseline-start

setValue signature

Special values

Use null to unset the value.

Warning

The provided string must be in the yyyy-MM-dd date format.

1
2
setValue(date: string | null): FieldAPI

getValue signature

1
2
getValue(): DatePickerField

date picker field shape

1
2
string | null

Reference screenshots

target end

type: com.atlassian.jpo:jpo-custom-field-baseline-end

setValue signature

Special values

Use null to unset the value.

Warning

The provided string must be in the yyyy-MM-dd date format.

1
2
setValue(date: string | null): FieldAPI

getValue signature

1
2
getValue(): DatePickerField

date picker field shape

1
2
string | null

Reference screenshots

number

type: com.atlassian.jira.plugin.system.customfieldtypes:float

setValue signature

Special values

Use null to unset the value.

1
2
setValue(value: number | null): FieldAPI

getValue signature

1
2
getValue(): NumberField

number custom field shape

1
2
number | null

Reference screenshots

parent

type: parent

setValue signature

Special values

1
2
setValue(id: string | null): FieldAPI

getValue signature

1
2
getValue(): ParentField

parent field shape

1
2
{ 
  id: string,  
  key: string, 
} | null

Reference screenshot

status

type: status

setValue signature

Transition screen

The screen will appear if configured for the used transition ID.

Warning

The get value method returns the ID and name of the current status. You should pass the transition ID to the set value method.

1
2
setValue(transitionId: string): FieldAPI

getValue signature

1
2
getValue(): StatusField | null

status field shape

1
2
{ 
  id: string,  
  name: string, 
}

Reference screenshot

original estimate

type: timeoriginalestimate

setValue signature

Special values

Use null to unset the value.

Warning

1
2
setValue(value: number | null): FieldAPI

getValue signature

1
2
getValue(): OriginalEstimateField

original estimate field shape

1
2
number | null

Reference screenshots

Querying screen tabs

getScreenTabById method signature

1
2
getScreenTabById(<tabId>): ScreenTabAPI | undefined

getScreenTabById method description

Accepts one argument: tabId (string) - the identifier of the screen tab which the app wants to work on.

Returns the ScreenTabAPI object if the tab exists on the GIC or Issue View.

Returns undefined if the screen tab doesn't exist.

Example of usage with a regular screen tab:

1
2
uiModificationsApi.onInit(({ api }) => {
  const { getScreenTabById } = api;
  const tab = getScreenTabById('<identifier>')
  // You can perform operations on a specific screen tab
  // using the ScreenTabAPI here
}, () => [''])

Iterating over screen tabs