Skip to main content

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​

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 await works.
  • return ends 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​

NameWhat it is
apiThe Forge product API. api.asApp().requestJira(...) or api.asApp().requestConfluence(...) calls the REST API as the Companion App. See requestJira and requestConfluence
routeThe 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
fetchCalls any other web address. See Forge fetch API
authorizeChecks whether a person may do something before the app does it for them. See Forge authorize API
consolelog, info, warn and error. The output shows in the test panel and in the item's history
requestWeb triggers only: the HTTP request that called the web trigger. See below
payloadScripted 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.