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 Master | Forge module |
|---|---|
| Fragment: Work item panel | jira:issuePanel |
| Fragment: Work item action | jira:issueAction |
| Fragment: Space page (Jira) | jira:projectPage |
| Fragment: Space settings page (Jira) | jira:projectSettingsPage |
| Fragment: Queue page | jiraServiceManagement:queuePage |
| Fragment: Page action | confluence:contentAction |
| Fragment: Page byline item | confluence:contentBylineItem |
| Fragment: Space page (Confluence) | confluence:spacePage |
| Fragment: Space settings page (Confluence) | confluence:spaceSettings |
| Gadget | jira:dashboardGadget |
| Macro | macro |
| UI modification | jira:uiModifications |
| Scripted field | jira:customFieldType |
| Post function | jira:workflowPostFunction |
| Validator and condition | jira:workflowValidator and jira:workflowCondition |
| Web trigger | webtrigger |
| Scheduled job | scheduledTrigger |
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β
- Run
forge createand choose these options when asked:- Product: Jira
- UI type: Custom UI
- Template:
jira-issue-panel
- 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β
- Import what Script Master gave your script without an
import. In Forge,requestJira,viewand the other bridge functions come from@forge/bridge. - Move the script into a React
useEffect, so it runs once when the panel loads. - Move the HTML into the component's
return. - Remove
setHeightandtheme. 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β
- Build the Custom UI project in its folder, for example with
npm run build. - Add the scopes your code needs to the app's
manifest.yml. Runforge lintto find missing ones. - Run
forge deploy, thenforge installon your site. - 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:
- Add
import api, { authorize, fetch, route } from '@forge/api';at the top of the function's file. - Wrap the script in the function your Forge module calls, and pass
requestorpayloadin as its argument. - 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.
Relatedβ
- Forge bridge API for browser scripts: what Script Master gives fragments, gadgets and macros.
- Forge API for server-side scripts: what server-side scripts get.
- Forge getting started: Atlassian's guide to building Forge apps.