Skip to main content

The Companion App

The Script Master Companion App is a small Forge app that you deploy under your own Atlassian developer account and install on your site. Script Master sends every server-side script to it to run. Without it, those scripts don't run.

Why scripts run in a separate app​

A Forge app's functions are shared by every site that installs the app. If Script Master ran your server-side scripts inside its own functions, a script from one site could in theory reach data from another site's run.

The Companion App is your own app, registered under your own developer account, so nobody else's scripts run in it. Your scripts run there, isolated from Script Master's shared functions and from other customers.

Which modules need it​

Runs on a server: needs the Companion AppRuns elsewhere: works without it
Web TriggersScript Console, in your browser
Scheduled JobsFragments, Gadgets and Macros, in the viewer's browser
Custom Fields (scripted fields and the field preview)UI Modifications, in the person's browser
Workflow post functionsValidators and conditions, which Jira evaluates
-Script Master Tools, in the browser of the person using the tool

Until a Companion App is connected, the server-side modules show Action Required: This feature cannot function without companion app, and their scripts fail. You can still write and save them.

How a run works​

  1. Something starts a server-side script: a call to a web trigger, a scheduled time, a work item view that needs a scripted field, or a transition with a post function.
  2. Script Master's Forge function sends the script and its inputs (the HTTP request for a web trigger, the work item and transition details for a post function or field) to your Companion App's URL.
  3. The Companion App checks the token in the URL, runs the script and sends back the return value, the error if there was one, and the console output.
  4. Script Master records the run, and answers the caller. For a web trigger, that's the response your script returned.

Scripts run as the Companion App, with its Forge permissions. In a script, api.asApp() calls Jira or Confluence as that app, not as a person. See Forge bridge API for server-side scripts.

Forge's time limits for the functions involved limit how long a run can take. See Limits.

What the Companion App stores​

  • Its token, in Forge's secret storage inside the Companion App.

Script Master stores the Companion App's URL, with the token in it, in its own settings. Only admins can see it, on the Settings tab.

Your scripts and their inputs travel from Script Master to the Companion App over HTTPS. Both apps run on Atlassian Forge. The Companion App doesn't keep scripts or results after a run.

The status in Script Master​

Your browser checks whether Script Master can reach the Companion App each time you open a page that depends on it. It calls the Companion App's URL. A Companion App that answers within 10 seconds counts as connected.

The check runs on the Overview, Settings, Web Triggers, Scheduled Jobs, Custom Fields and Workflows tabs, the Get started page, a scripted field's context editor and preview, and the post function editor. Settings and Get started show the status below. The other pages show the Action Required banner when no Companion App is connected.

StatusMeaning
Secured ExecutionA Companion App is connected and answers. Server-side scripts run there.
Not set upNo Companion App URL is saved. Server-side scripts fail until you add one.
Invalid ConfigurationA URL is saved, but it isn't a valid web address, the Companion App refused it, or it didn't answer within 10 seconds.

To set it up, see Set up the Companion App.

Keep it up to date​

The Companion App is your own Forge app, so Atlassian doesn't update it for you. To get a newer version, pull the latest code from its repository and deploy it again, the same way you deployed it first.