Skip to main content

Forge bridge API for browser scripts

This page lists the functions and objects Script Master gives scripts that run in the browser: fragments, gadgets, macros and the Script Console. They're the Forge bridge's own functions, so Atlassian's reference pages describe them in full.

Applies to: Script Master for Jira and Script Master for Confluence Β· Cloud

Browser scripts run with the permissions of the person viewing them. A request through requestJira or requestConfluence can only read and change what that person could in Jira or Confluence.

UI modifications use a different API. See UI modification script API.

Fragments, gadgets and macros​

Your code is an HTML document that runs in a frame. Its scripts can use these names without an import:

NameWhat it is
requestJiraCalls the Jira REST API as the viewer. Works in Jira only. See requestJira
requestConfluenceCalls the Confluence REST API as the viewer. Works in Confluence only. See requestConfluence
viewThe context the frame runs in, for example the work item, page or dashboard. Call await view.getContext(). See view
routerOpens or navigates to a page in the product. See router
showFlagShows a message flag in the product. See showFlag
eventsSends and receives events between the app's frames. See events
ModalOpens a modal dialog. See Modal
themeThe viewer's theme. theme.colorMode is light or dark
setHeightSets the frame's height. See Frame height

Frame height​

The frame fits its content by itself, and follows the content when it grows or shrinks. You don't need to call anything.

Call setHeight only when you want something else:

// A fixed height: taller content scrolls inside the frame
setHeight('300px');

// Hide the frame, for a fragment or macro that works without showing anything
setHeight('0px');

// Go back to fitting the content
setHeight('auto');

A height you set stays until you call setHeight('auto'). In Confluence, a page editor can also set Maximum height (px) on each macro. Taller content then scrolls inside the macro.

When the code fails​

Script Master watches each frame for uncaught errors and rejected promises. When one happens, it records the failure for admins. Viewers see a short message instead of the content, or above it. See Failures.

Script Console​

Scripts in the Script Console run in your own browser, as you. They get:

NameWhat it is
requestJira or requestConfluenceThe REST API of the product you're in, called as you
viewSee above
showFlagSee above
contextThe app's context, already loaded, so you don't need to call view.getContext()
fetchThe browser's fetch, for calls to other systems
consoleIts log, info, warn and error lines appear under Output

The script's console.log output and return value appear below the editor. See Script Console.

Examples​

Snippets to copy into a fragment, gadget or macro.

Reset styles​

Atlassian's CSS reset sets the fonts, spacing and base styles of Atlassian products. Add it at the top of a fragment, gadget or macro:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@atlaskit/css-reset@3.0.1/dist/bundle.css" />

See CSS reset in the Atlassian Design System.

Dark mode​

Load Atlassian's design tokens for the viewer's theme:

<script type="module">
document.querySelector(":root").setAttribute("data-color-mode", theme.colorMode);
document.querySelector(":root").setAttribute("data-theme", `${theme.colorMode}:${theme.colorMode}`);
document.querySelector(":root").insertAdjacentHTML("afterbegin", `<link rel="stylesheet" href="https://forge.cdn.prod.atlassian-dev.net/atlaskit-tokens_${theme.colorMode}.css" />`);
</script>

Show errors in the frame​

Script Master already records failures for admins. To also show an error in the frame while you work on it, write it into the page:

<div id="errors" style="color:red"></div>

<script type="module">
window.onerror = (e) => document.getElementById('errors').textContent = e.toString();
</script>

Find work items with JQL​

const fetchWorkItemsByJql = async (jql) => {
const response = await requestJira(`/rest/api/3/search/jql?jql=${encodeURIComponent(jql)}&fields=summary`);
if (!response.ok) {
throw new Error(`JQL search failed: ${response.status}`);
}
const data = await response.json();
return data.issues || [];
};

Read the changelog of a work item​

const fetchChangelog = async (issueKey) => {
const response = await requestJira(`/rest/api/3/issue/${issueKey}/changelog`);
if (!response.ok) {
throw new Error(`Changelog request failed for ${issueKey}: ${response.status}`);
}
const data = await response.json();
return data.values || [];
};