Rate this page:

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

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

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.

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();
  • There may be an extensionContext property in the context data. This extensionContext property is deprecated and will soon be removed. Use the extension property instead.
  • Not all of the values in the context data are guaranteed to be secure, unalterable, and valid to be used for authorization. See App context security for more information.

Rate this page: