Jira UI modifications (preview)

The jira:uiModifications module allows you to change the look and behavior of the Global issue create (GIC) form when used in conjunction with the UI modifications (apps) REST API.

This module can be used in Jira Software only.

UI modifications (UIM) is a runtime extension which allows applications to modify the UI on supported screens in a given UIM app mounting context (for example, a combination of a project and an issue type for GIC). The UI is modified using the UIM JS API in Forge applications in the UIM Forge module. You can manage the available UI modifications and their contexts using the UIM REST API. Applications can store additional data related to UI modifications as UIM data, which is also managed by the UIM REST API. Each UI modification is backed by a UIM entity which represents it on the back-end and is delivered to the front-end in UIM data.

To understand the broader context of this module read the UI modifications guide.

UIM app

An Atlassian Forge application which uses the UIM Forge module. A single UIM app can declare only one UIM Forge module.

UIM app invocation context

Provided to the UIM app by Jira. It consists of a project, issueType, and uiModifications (UIM data).

UIM app mounting context

A combination of a project, issueType, and viewType. Currently, the only supported viewType is the GIC form.

UIM data

An array of UIM entities for a given UIM app invocation context. The interpretation of UIM data is the responsibility of the UIM app. UIM data can be accessed through the invocation argument within the initCallback and the changeCallback.

UIM entity

A single mapping of custom textual data and a UIM app mounting context. It can be created and obtained using the UIM REST API.

UIM Forge bridge API

The API provided to the UIM app through the @forge/jira-bridge module. For more details, see the Jira Bridge uiModifications documentation.

UIM Forge module

A UI modifications Forge module (jira:uiModifications) declared in the manifest.

UIM REST API

The back-end REST API used to assign and retrieve specific data (related to project, issueType, and viewType) to be consumed by the UIM app through the UIM app invocation context. For more details, see the UI modifications (apps) documentation.

Writing your first UIM app

To write your first UIM app, follow the detailed instructions below or try out the example app at atlassian/forge-ui-modifications-example.

Forge manifest

You can build your Forge app following one of our guides. To create an app that will run as a UIM app, make sure to update your manifest.yml file to include:

1
2
modules:
  jira:uiModifications:
    - key: ui-modifications-app
      title: Example UI modifications app
      resource: uiModificationsApp
resources:
  - key: uiModificationsApp
    path: static/ui-modifications/dist

The application

UIM apps depend on the @forge/jira-bridge package which exposes the uiModifications API from version 0.6.0 onwards. Both initialization-triggered and user-triggered phase changes of the GIC form are supported. This package works on the client side and will be effective only when used within the static resource declared in the jira:uiModifications module.

The UIM Forge module will be rendered inside an invisible iframe element. The only meaningful part is the script linked in the main HTML file.

1
2
//static/hello-world/index.js
import { uiModificationsApi } from '@forge/jira-bridge';

uiModificationsApi.onInit(
  ({ api }) => {
    const { getFieldById } = api;

    // Hiding the priority field
    const priority = getFieldById('priority');
    priority?.setVisible(false);

    // Changing the summary field label
    const summary = getFieldById('summary');
    summary?.setName('Modified summary label');

    // Changing the assignee field description
    const assignee = getFieldById('assignee');
    assignee?.setDescription('Description added by UI modifications');

    // Get value of labels field
    const labels = getFieldById('labels');
    const labelsData = labels?.getValue() || [];
    labels?.setDescription(
      `${labelsData.length} label(s) are currently selected`
    );
  },
  () => ['priority', 'summary', 'assignee', 'labels']
);

Keep in mind that all changes requested during the run of the onInit callback will be applied at once after the function completes its execution.

Async operations

The execution of changes can be postponed, for example when a UIM needs to perform some async operations before evaluating which modification to apply. For that purpose, our API allows you to return a promise object from the callback. The changes will be postponed until the promise resolves.

A correct implementation using a promise:

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

// Below: imaginary import
import { shouldPriorityBeHidden } from '../my-services';

uiModificationsApi.onInit(
  ({ api }) => {
    const { getFieldById } = api;

    // Hiding the priority field
    const priority = getFieldById('priority');
    // We store the update Promise
    const priorityUpdate = shouldPriorityBeHidden().then((result) => {
      if (result === true) {
        priority?.setVisible(false);
      }
    });

    // Changing the assignee field description
    const assignee = getFieldById('assignee');
    assignee?.setDescription('Description added by UI modifications');

    // We return the promise. In this case even the assignee field description
    // will be updated only after the priorityUpdate promise resolves.
    return priorityUpdate;
  },
  () => ['priority', 'assignee']
);

Note that async/await syntax is supported:

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

// Below: imaginary import
import { shouldPriorityBeHidden } from '../my-services';

uiModificationsApi.onInit(
  async ({ api }) => {
    const { getFieldById } = api;

    // Hiding the priority field
    const priority = getFieldById('priority');
    const result = await shouldPriorityBeHidden();
    if (result === true) {
      priority?.setVisible(false);
    }

    // Changing the assignee field description
    const assignee = getFieldById('assignee');
    assignee?.setDescription('Description added by UI modifications');
  },
  () => ['priority', 'assignee']
);

Configure the UI modification

The UIM Forge module will only render when configured for a given projectId and issueTypeId using the UIM REST API. For example, there could be an AdminPage that creates a UIM using the REST API. Apps can also include custom UIM data to be passed to the UIM Forge module when it is executed, for example a list of rules that a user has selected:

1
2
import api, { route } from '@forge/api';

const createUiModification = async (projectId, issueTypeId) => {
  const result = await api.asApp().requestJira(route`/rest/api/3/uiModifications`, {
    method: "POST",
    body: JSON.stringify({
      name: 'demo-ui-modification',
      data: '["custom data", "for your app"]',
      contexts: [{ projectId, issueTypeId, viewType: 'GIC' }],
    }),
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
    },
  });
  console.log(`Created UI modification with status ${result.status}`);
  return result.status;
}

This custom UIM data is available as uiModifications within the onInit and onChange callbacks. It has the following shape:

1
2
uiModifications: Array<{
  id: string,
  data?: string,
}>

Properties

Extension context

UIM Forge modules can retrieve the current project and issueType by using the view.getContext() method exposed by the @forge/bridge module - see custom UI view.

The UIM context shape is:

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

Usage:

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.

If user consent isn’t given for the scopes mentioned inside the app’s manifest, UIM won’t render (same as with any other extension point). Users will be prompted to give consent when they open the GIC in a project/issue type that has been configured with a UIM.

Classic scopes

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

Granular scopes

1
2
permissions:
  scopes:
    - 'read:project:jira'
    - 'read:issue-type:jira'
    - 'read:user:jira'
    - 'read:avatar:jira'
    - 'read:user-configuration:jira'
    - 'read:issue:jira'
    - 'read:priority:jira'
    - 'read:label:jira'
    - 'read:license:jira'
    - 'read:field:jira'
    - 'read:field-configuration:jira'
    - 'write:field-configuration:jira'
    - 'write:field.default-value:jira'
    - 'write:field:jira'

Known limitations

Required user permissions

Users must have the “Browse projects” permission in order to load and execute UIM. However, users can create issues in the GIC without the “Browse projects” permission as long as they have the “Create issues” permission. In this case the user will see the following error message:

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

The default Jira permissions grant all authenticated users these two permissions, but Jira administrators may revoke the “Browse projects” permission in some circumstances. For example, a team may allow all users to create new issues in their project but only team members can browse the created issues in that project.

We are working to align the permission checks performed by UI modifications and the GIC. Until then, please be aware of this additional “Browse projects” permission that users will require to use UIM.

Also note that “Browse projects” will soon be joined by the new “View projects” and “View issues” permissions. At this stage all three permissions will be needed for UI modifications as the new permissions become available. If a user already has “Browse projects” they will automatically be granted “View projects” and “View issues” as part of this transition. However problems may arise if an administrator subsequently removes one of these permissions.

Flash of unmodified fields

UIM are loaded after the create issue dialog has finished loading. The user is informed about the loading state by a small spinner icon next to the label, which indicates that a UIM is running. Users can still see the fields before the modifications are applied. For example, a field will be visible for a moment before being hidden, or the default field description will be visible before it changes.

Multiple UIM apps

If multiple UIM apps are installed and configured to run for a given project and issue type, only the first configured app for given project and issue type will run. Uninstalling an app doesn't remove corresponding configurations, but after the first configured app is uninstalled, the second one configured for this context will run.

Show fields and Find your field

Fields can be hidden by individual users using Show fields. Data for these hidden fields is not sent to the UIM app.

Find your field does not know about fields being hidden by a UIM app using setVisible. Users may not be able to discover why a field is not visible to them.

Supported project types

Currently, UIM only supports company-managed and team-managed Jira Software projects. Other project types, like Jira Service Management, won’t work with UIM at this stage.

Supported entry points

The GIC can be opened from many places in the system. We currently support the following entry points:

• the global Create button in the top Navigation bar
• the c keyboard shortcut
• a Forge app with custom UI using CreateIssueModal from @forge/jira-bridge