Jira Service Management 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) – the request create form your customers use in the help center or portal.
  • Jira Service Management agent view (Preview) – the views your agents use inside a service project. This covers three separate views: global issue create (GIC), issue view, and issue transition.

The agent view shares the same views as Jira, but runs in service projects. Because of this, its extension context also exposes the request type of the work item, and the set of supported fields differs from the request create portal. For each agent view, the viewType in the extension context tells you which view your app is running in: GICAgentView, IssueViewAgentView, or IssueTransitionAgentView.

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

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

Get started

Manifest structure

1
2
3
4
5
6
7
8
9
10
11
modules {}
└─ jira:uiModifications []
   ├─ key (string) [Mandatory]
   ├─ title (string | i18n) [Mandatory]
   ├─ resource (string) [Mandatory]
   └─ unlicensedAccess (List<string>)

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

Properties

i18n object

Extension context

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

The shape of the context depends on the view your app is running in:

• On the request create portal, the context exposes the current portalId and request type.
• On the agent view, the context exposes the current project, issueType, and requestTypeId, plus issue and issueTransition where relevant to the view. Use the viewType property to detect which agent view your app is running in.

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  extension: {
    type: 'jira:uiModifications',
    portalId: {
      id: string,
    },
    request: {
      typeId: string
    },
    viewType: 'JSMRequestCreate'
  }
}

Example

The same app can run on both the request create portal and the agent view. Read the viewType from the extension context to work out which view your app is running in, then read only the properties available in that view.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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 { portalId, request } = 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.

The same scopes cover both the request create portal and the agent view. The agent view supports more fields, so it needs a few extra scopes on top of the portal ones. These are marked as agent view only in the examples below. If your app runs in both views, declare all of the scopes listed.

1
2
3
4
5
6
7
8
9
permissions:
  scopes:
    - 'read:jira-user'
    - 'read:jira-work'
    - 'manage:jira-configuration'
    - 'write:jira-work'
    # Agent view only (Preview)
    - '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

Permissions are evaluated per view. The request create portal is used by customers, while the agent view runs inside a service project and is used by agents, so each has different requirements.

View-specific requirements and 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.