Skip to main content

Move a script to your own Forge app

Turn a Script Master fragment, gadget or other script into a standalone Forge app when you want full control over its code, build and releases. Each Script Master module is built on a Forge module, so most of your code carries over.

Before you begin​

  • Tools on your computer: Node.js and the Forge CLI, signed in with forge login.
  • Jira or Confluence permission: admin rights on a site where you can install the new app, for example a development site.
  • Your script: open the item in Script Master and copy its code, or export it. See Import, export and duplicate.

Which Forge module to use​

In Script MasterForge module
Fragment: Work item paneljira:issuePanel
Fragment: Work item actionjira:issueAction
Fragment: Space page (Jira)jira:projectPage
Fragment: Space settings page (Jira)jira:projectSettingsPage
Fragment: Queue pagejiraServiceManagement:queuePage
Fragment: Page actionconfluence:contentAction
Fragment: Page byline itemconfluence:contentBylineItem
Fragment: Space page (Confluence)confluence:spacePage
Fragment: Space settings page (Confluence)confluence:spaceSettings
Gadgetjira:dashboardGadget
Macromacro
UI modificationjira:uiModifications
Scripted fieldjira:customFieldType
Post functionjira:workflowPostFunction
Validator and conditionjira:workflowValidator and jira:workflowCondition
Web triggerwebtrigger
Scheduled jobscheduledTrigger

Example: move a work item panel​

This fragment lists everyone who changed a work item. It's based on one of Script Master's fragment templates:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@atlaskit/css-reset@3.0.1/dist/bundle.css" />
<div>
Contributors: <div id='contributors'>Loading...</div>
</div>

<script type="module">
const context = await view.getContext();
const issueKey = context.extension.issue.key;
const response = await requestJira(`/rest/api/3/issue/${issueKey}/changelog`, {
headers: { 'Accept': 'application/json' }
});
const responseData = await response.json();
const allContributors = responseData.values.map(obj => obj.author.displayName);
const uniqueContributors = new Set(allContributors);

document.getElementById('contributors').textContent = Array.from(uniqueContributors).join(', ');
</script>

Create the Forge app​

  1. Run forge create and choose these options when asked:
    • Product: Jira
    • UI type: Custom UI
    • Template: jira-issue-panel
  2. Follow Atlassian's Build a Custom UI app in Jira until the template's "Hello world" panel shows on a work item.

Result: You have a working Forge app with an empty work item panel.

Move the code​

  1. Import what Script Master gave your script without an import. In Forge, requestJira, view and the other bridge functions come from @forge/bridge.
  2. Move the script into a React useEffect, so it runs once when the panel loads.
  3. Move the HTML into the component's return.
  4. Remove setHeight and theme. They're Script Master's own, not part of Forge.

The panel's App.js then looks like this:

import { requestJira, view } from '@forge/bridge';
import { useEffect, useState } from 'react';

function App() {
const [contributors, setContributors] = useState('Loading...');

useEffect(() => {
(async () => {
const context = await view.getContext();
const issueKey = context.extension.issue.key;
const response = await requestJira(`/rest/api/3/issue/${issueKey}/changelog`, {
headers: { 'Accept': 'application/json' }
});
const responseData = await response.json();
const allContributors = responseData.values.map(obj => obj.author.displayName);
setContributors(Array.from(new Set(allContributors)).join(', '));
})();
}, []);

return (
<div>
Contributors: <div>{contributors}</div>
</div>
);
}

export default App;

Deploy and test​

  1. Build the Custom UI project in its folder, for example with npm run build.
  2. Add the scopes your code needs to the app's manifest.yml. Run forge lint to find missing ones.
  3. Run forge deploy, then forge install on your site.
  4. Open a work item and add your panel.

Result: The panel shows the work item's contributors, as the fragment did. You can then turn the fragment off in Script Master.

Move a server-side script​

Web trigger, scheduled job, scripted field and post function scripts run in the Companion App, which supplies api, route, fetch and authorize. In your own app:

  1. Add import api, { authorize, fetch, route } from '@forge/api'; at the top of the function's file.
  2. Wrap the script in the function your Forge module calls, and pass request or payload in as its argument.
  3. Declare the module, the function and the scopes in manifest.yml.

Your own app runs the code in its own Forge functions, so it doesn't need the Companion App.