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:
| Name | What it is |
|---|---|
requestJira | Calls the Jira REST API as the viewer. Works in Jira only. See requestJira |
requestConfluence | Calls the Confluence REST API as the viewer. Works in Confluence only. See requestConfluence |
view | The context the frame runs in, for example the work item, page or dashboard. Call await view.getContext(). See view |
router | Opens or navigates to a page in the product. See router |
showFlag | Shows a message flag in the product. See showFlag |
events | Sends and receives events between the app's frames. See events |
Modal | Opens a modal dialog. See Modal |
theme | The viewer's theme. theme.colorMode is light or dark |
setHeight | Sets 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:
| Name | What it is |
|---|---|
requestJira or requestConfluence | The REST API of the product you're in, called as you |
view | See above |
showFlag | See above |
context | The app's context, already loaded, so you don't need to call view.getContext() |
fetch | The browser's fetch, for calls to other systems |
console | Its 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 || [];
};
Relatedβ
- Forge API for server-side scripts: what web triggers, scheduled jobs, scripted fields and post functions get.
- Fragments API reference for AI: the full reference, written for AI assistants.
- Permissions: whose permissions each kind of script uses.