Forge API for server-side scripts
This page lists what scripts in web triggers, scheduled jobs, scripted fields and post functions can use. These scripts run in your Companion App, as the app, with the Forge API from @forge/api.
Applies to: Script Master for Jira and Script Master for Confluence Β· Cloud
Before you beginβ
- The Companion App must be connected. Without it, these scripts don't run. See Set up the Companion App.
How your script runsβ
Script Master sends your script to the Companion App, which runs it like this:
"use strict";(async () => {
// Your script
})();
What that means for your code:
- Top-level
awaitworks. returnends the script and hands back its result. A web trigger must return a response object. See Web Triggers.- The code runs in strict mode, so undeclared variables are errors.
- You don't write any
import. The names below are already there. - Forge's time limits for the functions involved limit how long a run can take. See Limits.
What a script can useβ
| Name | What it is |
|---|---|
api | The Forge product API. api.asApp().requestJira(...) or api.asApp().requestConfluence(...) calls the REST API as the Companion App. See requestJira and requestConfluence |
route | The tagged template for REST paths: route`/rest/api/3/issue/${key}`. It encodes the values you put in, so they can't change the path. See route |
fetch | Calls any other web address. See Forge fetch API |
authorize | Checks whether a person may do something before the app does it for them. See Forge authorize API |
console | log, info, warn and error. The output shows in the test panel and in the item's history |
request | Web triggers only: the HTTP request that called the web trigger. See below |
payload | Scripted fields and post functions only: the work item and other details of the run. See Custom Fields and Post functions |
The Companion App also passes these globals: setTimeout, setInterval, setImmediate, clearTimeout, clearInterval, atob, btoa, encodeURI, encodeURIComponent, decodeURI, decodeURIComponent, isFinite, isNaN, parseFloat, parseInt, Array, Promise, String, Set, Boolean, Number, Map, JSON, Intl, Math, RegExp, Error, Date, URL and URLSearchParams.
The script runs in its own JavaScript context, so the language's built-in objects, such as Object, Symbol and WeakMap, are there too. Nothing else from Node.js or the web platform is. For example, require, process, Buffer, crypto, TextEncoder, TextDecoder and AbortController don't exist, and using them throws a ReferenceError.
Run as the appβ
Server-side scripts have no signed-in person. api.asApp() calls Jira or Confluence with the Companion App's permissions, not a person's. Before a web trigger changes something for a caller, check that the caller may make that change.
The web trigger requestβ
interface Request {
method: string;
path: string;
headers: { [headerName: string]: string[] };
queryParameters: { [paramName: string]: string[] };
body: string;
context: { cloudId: string; moduleKey: string };
}
The URL you copy from the web trigger already holds the id query parameter that names it, so request.queryParameters.id is always there. Add your own parameters next to it and read them, for example request.queryParameters.status?.[0]. See Web trigger request and response.
Logsβ
console.log lines, the error and the return value of each run are kept in the item's history, up to the limits. A web trigger keeps every failed run and at most one successful run every 5 minutes. See Run history. Runs that log nothing aren't kept.
Relatedβ
- Forge bridge API for browser scripts: what fragments, gadgets, macros and the Script Console get.
- Web Triggers API reference for AI: the full reference for web trigger scripts, written for AI assistants.
- Scheduled Jobs API reference for AI: the same for scheduled jobs.