Jira UI modifications

The jira:uiModifications module is shared between Jira and Jira Service Management. It allows you to change the look and behavior of:

• Jira: Jira global issue create, Jira issue view (Preview), and Jira issue transition (Preview)(the new experience)
• Jira Service Management: Jira Service Management request create portal (Preview)

This page documents how jira:uiModifications works for Jira. The module itself is the same but for Jira Service Management-specific views, see Jira Service Management UI modifications.

The module is designed to be used in conjunction with the UI modifications (apps) REST API.

Get started

Manifest structure

1
2
modules {}
└─ jira:uiModifications []
   ├─ key (string) [Mandatory]
   ├─ title (string | i18n) [Mandatory]
   └─ resource (string) [Mandatory]

resources []
├─ key (string) [Mandatory]
└─ path (string) [Mandatory]

Properties

i18n object

Extension context

UIM Forge modules can retrieve the current project and issueType using the getContext bridge method in Custom UI and UI Kit.

1
2
{
  extension: {
    type: 'jira:uiModifications',
    project: {
      id: string,
      key: string,
      type: string,
    },
    issueType: {
      id: string,
      name: string,
    },
    viewType: 'GIC'
  }
}

Example

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

uiModificationsApi.onInit(async ({ api, uiModifications }) => {
  const { getFieldById } = api;
  const context = await view.getContext();

  const { project, issueType } = context.extension;
  
  uiModifications.forEach(({ data: customDataConfiguredUsingRestApi }) => {
    // ...
  });
}, ({ uiModifications }) => [
  // ...
])

Scopes

UI modifications expose customer data to the app that provides them. Therefore, you must declare either classic (recommended) or granular scopes in your manifest. Note that you always have to declare all scopes from your chosen group.

1
2
permissions:
  scopes:
    - 'read:jira-user'
    - 'read:jira-work'
    - 'manage:jira-configuration'
    - 'write:jira-work'
    - 'manage:jira-project'

Required user permissions

In case a required permission isn’t assigned, the user will see the following error:

1
2
We couldn't load the UI modifications configuration for this form

View-specific requirements and limitations

Each supported view type has its own known limitations:

Other known limitations

Multiple UIM apps

If you install and configure multiple UIM apps to run for a given combination of project, issue type, and view type, up to 5 apps can apply changes simultaneously. If more than 5 apps are configured, changes from the remaining apps will be disregarded. Apps apply changes asynchronously, so the order of application is random.

There may be conflicts when multiple apps attempt to modify the same field using the same FieldAPI method. In such cases, app developers will receive conflict errors via the onError handler, and users will see corresponding notifications:

If the conflict happens, the changes applied by the app which finished running last will override changes from other apps.

Image previews unavailable until issue is created

The Atlassian Document Format (ADF) supports rich content when using the UIM to add media content (like images) to Jira description, text area, or rich text custom fields.

However, when adding an image through the UIM during issue creation (for example, throught the GIC modal) the image preview might display a Preview unavailable message. This is because the necessary permissions to display the image aren't available yet; they'll be available after the issue is created and/or the page is refreshed.