Custom UI bridge

The custom UI bridge is a JavaScript API that enables custom UI apps to securely integrate with Atlassian products.

Install the custom UI bridge using the @forge/bridge npm package. Import @forge/bridge using a bundler, such as Webpack.

For example, you can start by creating a new app from one of the custom UI templates. In the static/hello-world directory, running npm install && npm build will bundle the template static web application together with the custom UI bridge, into the static/hello-world/build directory, which is used as the resource path in the Forge app's manifest.yml.

In the template, the bridge is used in static/hello-world/src/App.js:

1
2
3

import { invoke } from "@forge/bridge";

invoke("getText", { example: "my-invoke-variable" }).then(setData);

invoke

The invoke bridge method enables custom UI apps to run backend FaaS functions hosted by Atlassian.

To use the invoke bridge method, you need to define your functions using the custom UI resolver.

Function signature

1
2
3
4

function invoke(
  functionKey: string,
  payload?: { [key in number | string]: any; },
): Promise<{ [key: string]: any } | void>

Arguments

• functionKey: A string identifier for the resolver function to invoke with this method. This string should exactly match the functionKey in one of your resolver function definitions.
• payload: Data that is passed into the resolver function.

Returns

• A Promise that resolves with the data returned from the invoked function.

requestJira

The requestJira bridge method enables custom UI apps to call the Jira Cloud platform REST API as the current user.

To use the requestJira bridge method, you need to define a custom UI resolver using @forge/resolver at version 0.2.0 or later. You don't need to define any functions in the resolver.

Function signature

1
2
3
4
5
6
7
8
9

function requestJira(
  path: string,
  options?: RequestInit,
): Promise<{
  status: number,
  ok: boolean,
  statusText: string,
  body: { [key in string | number]: any } | string | null
}>

Arguments

• uri: A Jira REST API operation path. See the Jira Cloud platform REST API for more information.
• options: See the node-fetch library’s Options documentation or the accepted values. Defaults: { 'content-type': 'application/json' }

Returns

• A Promise that resolves with the REST API response.

Example

1
2
3
4
5

import { requestJira } from '@forge/bridge';

requestJira('/rest/api/3/issue/ISSUE-1').then(response => {
  console.log(response);
});

requestConfluence

The requestConfluence bridge method enables custom UI apps to call the Confluence Cloud platform REST API as the current user.

To use the requestConfluence bridge method, you need to define a custom UI resolver using @forge/resolver at version 0.2.0 or later. You don't need to define any functions in the resolver.

Function signature

1
2
3
4
5
6
7
8
9

function requestConfluence(
  path: string,
  options?: RequestInit,
): Promise<{
  status: number,
  ok: boolean,
  statusText: string,
  body: { [key in string | number]: any } | string | null
}>

Arguments

• uri: A Confluence REST API operation path. See the Confluence Cloud platform REST API for more information.
• options: See the node-fetch library’s Options documentation for the accepted values. Defaults: { 'content-type': 'application/json' }

Returns

• A Promise that resolves with the REST API response.

Example

1
2
3
4
5

import { requestConfluence } from '@forge/bridge';

requestConfluence('/wiki/rest/api/content').then(response => {
  console.log(response);
});

router

The router object enables you to navigate the host product to another page.

navigate

The navigate method allows you to navigate the host window to a given URL. If you’re linking to an external site, the user is prompted before opening the link in a new tab. If the user declines to proceed, the returned Promise is rejected.

If you’re using relative URLs (starts with /), the user won’t be prompted.

Function signature

1

function navigate(url: string): Promise<void>

Example

1
2
3
4
5

import { router } from '@forge/bridge';

router.navigate('/browse/ISSUE-1234');

router.navigate('https://example.com');

open

The open method allows you to open a new window to a given URL. If you’re linking to an external site, the user is prompted before opening the link in a new window. If the user declines to proceed, the returned Promise is rejected.

If you’re using relative URLs (starts with /), the user won’t be prompted.

Function signature

1

function open(url: string): Promise<void>

Example

1
2
3
4
5

import { router } from '@forge/bridge';

router.open('/browse/ISSUE-1234');

router.open('https://example.com');

view

The view object refers to the context in which a resource is loaded. For example, a modal.

close

The close method enables you to request the closure of the current view. For example, close a modal.

Function signature

1

function close(): Promise<void>

Example

1
2
3

import { view } from '@forge/bridge';

view.close();

getContext

The getContext method enables you to retrieve contextual information for your custom UI app. The data available depends on the module in which your app is used.

Function signature

1

function getContext(): Promise<{ [key: string]: any }>

Example

1
2
3

import { view } from '@forge/bridge';

const context = await view.getContext();