Forge Workflows (@forge/workflows) is under development and is not yet available. These pages describe the
planned API, which may change before release.
For more details, see Forge EAP, Preview, and GA.
In this tutorial, you build a Jira issue panel with a Summarise subtasks button. The button starts a workflow that summarises each subtask in parallel and joins the summaries together. The panel shows a progress bar while the workflow runs, and the summary when it finishes.
A workflow is a chain of tasks that runs in the background, one invocation per task call. Starting it gives you a run ID, which you use to check on the run. For an introduction to tasks, futures and chains, see Forge Workflows API.
You need a Forge app written in TypeScript, with a Jira issue panel module. To create one, see Getting started.
Install the SDK:
1 2npm install @forge/workflows
Workflows keep the state of each run in your app's storage, so add the storage:app scope to manifest.yml:
1 2 3 4 5permissions: scopes: - read:jira-work - storage:app
Create src/workflows.ts:
1 2 3 4 5 6 7 8 9 10 11 12 13import { task } from '@forge/workflows'; import { summariseIssue } from './llm'; // A task: each call runs in its own invocation. const summarise = task(async (issueKey: string) => summariseIssue(issueKey)); export const summariseSubtasks = (issueKeys: string[]) => issueKeys .map(summarise) // one task call per subtask .collect({ concurrency: 5 }) // run at most 5 at once, and wait for all of them .pipe((summaries) => summaries.join('\n\n') || 'This issue has no subtasks.') // the run's result .start(); // start a run; resolves to { runId }
summariseIssue is your own function, for example one that calls the
Forge LLMs API.
The last step's value becomes the run's result. Here, that's the joined summaries.
In src/index.ts, add one resolver that starts the workflow and one that returns the run's status. The start
resolver reads the issue from the panel's context and looks up its subtasks before starting the run, because a
workflow's fan-out items must be known when it starts:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26import api, { route } from '@forge/api'; import Resolver from '@forge/resolver'; import { runs } from '@forge/workflows'; import { summariseSubtasks } from './workflows'; const resolver = new Resolver(); // The subtasks of an issue, as the current user can see them. const getSubtaskKeys = async (issueKey: string): Promise<string[]> => { const response = await api.asUser().requestJira(route`/rest/api/3/issue/${issueKey}?fields=subtasks`); if (!response.ok) throw new Error(`Couldn't read ${issueKey}: ${response.status}`); const issue = (await response.json()) as { fields: { subtasks?: Array<{ key: string }> } }; return (issue.fields.subtasks ?? []).map((subtask) => subtask.key); }; // Returns { runId } as soon as the run has started. resolver.define('start', async ({ context }) => { const issueKey = context.extension.issue.key as string; return summariseSubtasks(await getSubtaskKeys(issueKey)); }); // Returns { state, progress, result?, error? }. resolver.define('status', ({ payload }) => runs.get(payload.runId)); export const handler = resolver.getDefinitions();
runs.get can read any run in your app, and the workflow's steps run with your app's permissions. In a real app,
check that the user is allowed to start the run and to see its result. See
Security.
In your issue panel's frontend, start the run, then call the status resolver every 2 seconds until the run
finishes:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37import React, { useEffect, useState } from 'react'; import ForgeReconciler, { Button, ProgressBar, Text } from '@forge/react'; import { invoke } from '@forge/bridge'; const App = () => { const [runId, setRunId] = useState(); const [run, setRun] = useState(); useEffect(() => { if (!runId) return; const timer = setInterval(async () => { // In production, catch invoke errors, clear the timer, and show an error. const status = await invoke('status', { runId }); if (!status) return clearInterval(timer); setRun(status); if (status.state !== 'RUNNING') clearInterval(timer); }, 2000); return () => clearInterval(timer); }, [runId]); const start = async () => { // In production, disable the button while this awaits and show invoke errors. // The resolver finds the issue from the panel's context, so there's nothing to send. const { runId } = await invoke('start'); setRunId(runId); }; if (!runId) return <Button onClick={start}>Summarise subtasks</Button>; if (!run || run.state === 'RUNNING') { const { done = 0, total = 1 } = run?.progress ?? {}; return <ProgressBar value={done / total} />; } return run.state === 'SUCCEEDED' ? <Text>{run.result}</Text> : <Text>Failed: {run.error?.message}</Text>; }; ForgeReconciler.render(<App />);
progress tells you how many of the subtask summaries have finished, which fills the progress bar.
Navigate to the app's top-level directory and deploy your app by running:
1 2forge deploy
Install your app using one of the following commands:
To install to your latest active Forge demo development site, or provision one if needed:
1 2forge install --demo-site
Demo sites include realistic seeded data and are active for 90 days by default.
To select an existing Atlassian site:
1 2forge install
If prompted, select your Atlassian context using the arrow keys and press the enter key.
If prompted, enter the URL for your development site. For example, example.atlassian.net. View a list of your active sites at Atlassian administration.
Once the successful installation message appears, your app is installed and ready
to use on the specified site.
You can always delete your app from the site by running the forge uninstall command.
Open an issue, click Summarise subtasks, and watch the progress bar fill as each subtask is summarised.
.catch() or collect({ settle: true }). See
Errors, limits and testing.waitForSignal(), or an agent tool-call loop with loop(). See the
examples and the
API reference.Rate this page: