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 App | Runs elsewhere: works without it |
|---|---|
| Web Triggers | Script Console, in your browser |
| Scheduled Jobs | Fragments, 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 functions | Validators 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β
- 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.
- 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.
- 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.
- 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.
| Status | Meaning |
|---|---|
| Secured Execution | A Companion App is connected and answers. Server-side scripts run there. |
| Not set up | No Companion App URL is saved. Server-side scripts fail until you add one. |
| Invalid Configuration | A 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.
Relatedβ
- Set up the Companion App: deploy it and connect it to Script Master.
- Data security and privacy: what travels where.
- Server-side scripts don't run: the Action Required banner.