Accept fast, cook later · Level 2

Behind, or starting here? Download the code as it should be before this lesson.

Right now the head chef waits while the resolver talks to Jira. That is fine for one ticket and not for eight, and a function called from a page has only a few seconds before Forge stops it. This lesson splits the work: the desk accepts the menu and answers at once, and a separate function does the slow part later.

Feel the wait

The same menu goes to two desks: the one from lesson 1, and the one this lesson builds. Press the button and compare how long each one keeps the head chef waiting.

How slow is Jira today?about 3 sSimulated timings

Lesson 1 · Wait for Jira `asUser()`

The resolver writes the ticket itself, then answers.

Button busy for 0.0 s

Lesson 2 · Take a receipt `asApp()`

The resolver saves the menu, puts { menuId } on the rail and answers. The prep cook writes the ticket later.

Button busy for 0.0 s

Step 1: Add storage and the rail

Runs in the Atlassian cloud · Back of house

Key-Value Store (KVS) · labelled jars

The Key-Value Store keeps JSON values under string keys, hosted by Forge, from @forge/kvs. Each installation has its own store, so two sites never see each other’s data. Use a prefix in each key, such as menu:, to keep different kinds of record apart. A value can be up to about 240 KiB.

In the kitchen A shelf of jars. Write the label, put something in, find it by its label later.

Atlassian docs: Storage reference (opens in a new tab)

Runs in the Atlassian cloud · Back of house

Queue (@forge/events) · the rail

A queue, from @forge/events, takes a small message now and hands it to a consumer function later. The function that pushed it answers straight away. The consumer runs on its own, and can be given a longer time limit than a function called from a page:

Seconds before Forge stops the function, drawn to scale. The kind of invocation sets the limit.

UI calls (invoke from a page or panel) and product events25 s
Web triggers, Rovo actions, scheduled triggers and async events, by default55 s
The prep cook in this course (timeoutSeconds: 120)120 s (2 min)
A queue consumer with timeoutSeconds, at most900 s (15 min)

The rule: A click is a short function. A job belongs on a queue. A process that must stay up belongs in a container.

In the kitchen The rail where job slips wait until the prep cook takes them down.

Atlassian docs: Events (opens in a new tab)

RunTerminal

npm install @forge/kvs @forge/events

Editpackage.json

npm install @forge/events @forge/kvs writes these lines.

10	10		`"dependencies": {`
11	11		`"@forge/api": "^8.2.0",`
12	12		`"@forge/bridge": "^7.1.0",`
	13	+	Added: `"@forge/events": "^3.0.7",`
	14	+	Added: `"@forge/kvs": "^2.0.7",`
13	15		`"@forge/react": "^12.3.0",`
14	16		`"@forge/resolver": "^2.0.0",`
15	17		`"react": "^18.2.0"`

Why: Key-Value Store (KVS) · Queue (@forge/events)

Stuck? “Cannot find module @forge/…” · I added an npm package

Done: package.json lists @forge/kvs and @forge/events

Step 2: Save, put a slip on the rail, hand back a receipt

Runs in the Atlassian cloud · Back of house

Queue event · a job slip

What you push to a queue is a small event body. Keep it to an id. The real data stays in storage, where the consumer reads it, so a slip never carries more than it must and never goes stale.

In the kitchen A slip that says only “job 42”. The details stay in the jar with that label.

Runs in the Atlassian cloud · Back of house

Job id · the receipt

The id the resolver returns at once, before any work is done. Here it is menuId, a random UUID. The desk keeps it and asks about that menu every two seconds until it is done.

In the kitchen The receipt the head chef gets straight away, with a number to ask about later.

It pushes only { menuId } to the queue.It pins a slip with only the jar’s label on the rail.

A new file holds the whole pattern. The order matters: save first, then push. Push first, and the prep cook may start before the menu exists.

New filesrc/menus.js

A new file: menus live in labelled jars, and only their id goes on the rail.

1	+	Added: `import { randomUUID } from 'node:crypto';`
2	+	Added: `import { kvs } from '@forge/kvs';`
3	+	Added: `import { Queue } from '@forge/events';`
4	+	Added: `import { STORE } from './lib/config';`
5	+	Added:
6	+	Added: `const rail = new Queue({ key: 'menu-jobs' });`
7	+	Added:
8	+	Added: export const getMenu = (menuId) => kvs.get(`${STORE.MENU}${menuId}`);
9	+	Added:
10	+	Added: export const saveMenu = (menuId, menu) => kvs.set(`${STORE.MENU}${menuId}`, { ...menu, updatedAt: new Date().toISOString() });
11	+	Added:
12	+	Added: `/**`
13	+	Added: `* Accept fast: save the whole menu in a jar, put a slip with only its id on the`
14	+	Added: `* rail, and return the receipt. Save first: the prep cook may start before this returns.`
15	+	Added: `*/`
16	+	Added: `export async function acceptMenu(menu) {`
17	+	Added: `const menuId = randomUUID();`
18	+	Added: `await saveMenu(menuId, { ...menu, status: 'waiting', checkpoint: {} });`
19	+	Added: `await rail.push({ body: { menuId } });`
20	+	Added: `return menuId;`
21	+	Added: `}`

Why: Key-Value Store (KVS) · Queue event · Job id

Stuck? Sending a menu fails with “400 Bad Request” from the queue

Done: src/menus.js exports acceptMenu and getMenu

Step 3: The desk uses the rail now

The desk no longer writes tickets itself, so it swaps the ticket helpers for the new module:

Editsrc/desk.js

The desk no longer writes tickets itself.

1	1		`import Resolver from '@forge/resolver';`
2	2		`import api, { route } from '@forge/api';`
3		−	Removed: `import { LABELS, settings } from './lib/config';`
4		−	Removed: `import { paragraphs } from './lib/adf';`
	3	+	Added: `import { settings } from './lib/config';`
5	4		`import { validateMenu } from './lib/validate';`
	5	+	Added: `import { acceptMenu, getMenu } from './menus';`
6	6
7	7		`const resolver = new Resolver();`
8	8

Why: Queue (@forge/events)

Done: src/desk.js imports acceptMenu and getMenu

Step 4: Check before using the restaurant’s badge

Runs in the Atlassian cloud · Back of house

asApp() · on the restaurant’s own badge

asApp() calls a product API as the app itself, with the app’s scopes and no person attached. A consumer has nobody to act for, so it must use it. The app may be allowed more than the person who asked, so check the person’s own permission before the app acts for them.

In the kitchen When nobody is there to lend a badge, the kitchen uses the restaurant’s own.

Atlassian docs: Product REST APIs (opens in a new tab)

The prep cook will write tickets as the app. Before accepting a menu, ask Jira whether the person sending it could create work items in the Kitchen space themselves:

Editsrc/desk.js

Ask Jira, as the person, whether they may create work items in the project.

6	6
7	7		`const resolver = new Resolver();`
8	8
	9	+	Added: `// The prep cook will create tickets on the restaurant's own badge. Before that,`
	10	+	Added: `// check that the person asking could create work items in the project themselves.`
	11	+	Added: `async function canCreateIn(projectKey) {`
	12	+	Added: `const response = await api`
	13	+	Added: `.asUser()`
	14	+	Added: .requestJira(route`/rest/api/3/mypermissions?projectKey=${projectKey}&permissions=CREATE_ISSUES`);
	15	+	Added: `if (!response.ok) return false;`
	16	+	Added: `const data = await response.json();`
	17	+	Added: `return data.permissions?.CREATE_ISSUES?.havePermission === true;`
	18	+	Added: `}`
	19	+	Added:
9	20		`// One ticket for the whole menu, created on the head chef's own badge.`
10	21		`resolver.define('submitMenu', async ({ payload }) => {`
11	22		`const check = validateMenu(payload);`

Why: asApp() · asUser()

Stuck? Creating a ticket fails with “Jira answered 400”

Done: src/desk.js has a canCreateIn function

Step 5: Accept fast and hand back a receipt

submitMenu now checks, saves, pushes and returns the receipt. A second resolver, getMenu, lets the desk follow it:

Editsrc/desk.js

submitMenu returns as soon as the slip is on the rail.
getMenu lets only the sender follow their receipt.

17	17		`return data.permissions?.CREATE_ISSUES?.havePermission === true;`
18	18		`}`
19	19
20		−	Removed: `// One ticket for the whole menu, created on the head chef's own badge.`
21		−	Removed: `resolver.define('submitMenu', async ({ payload }) => {`
	20	+	Added: `// Accept fast: check, save, queue, and return a receipt straight away.`
	21	+	Added: `resolver.define('submitMenu', async ({ payload, context }) => {`
22	22		`const check = validateMenu(payload);`
23	23		`if (!check.ok) return { error: check.error };`
24		−	Removed: `const { projectKey, issueType } = settings();`
25		−	Removed: `const { title, notes } = check.menu;`
26		−	Removed: const response = await api.asUser().requestJira(route`/rest/api/3/issue`, {
27		−	Removed: `method: 'POST',`
28		−	Removed: `headers: { Accept: 'application/json', 'Content-Type': 'application/json' },`
29		−	Removed: `body: JSON.stringify({`
30		−	Removed: `fields: {`
31		−	Removed: `project: { key: projectKey },`
32		−	Removed: `issuetype: { name: issueType },`
33		−	Removed: `summary: title,`
34		−	Removed: `description: paragraphs(notes),`
35		−	Removed: `labels: [LABELS.MENU],`
36		−	Removed: `},`
37		−	Removed: `}),`
38		−	Removed: `});`
39		−	Removed: `if (!response.ok) {`
40		−	Removed: return { error: `Jira answered ${response.status}: ${await response.text()}` };
	24	+	Added: `const { projectKey } = settings();`
	25	+	Added: `if (!(await canCreateIn(projectKey))) {`
	26	+	Added: return { error: `You can’t create work items in ${projectKey}, so the kitchen won’t either.` };
41	27		`}`
42		−	Removed: `const issue = await response.json();`
43		−	Removed: `return { ticket: { key: issue.key, dish: title } };`
	28	+	Added: `const menuId = await acceptMenu({ ...check.menu, requestedBy: context.accountId });`
	29	+	Added: `return { menuId };`
44	30		`});`
45	31
	32	+	Added: `// Only the person who sent a menu can follow its receipt.`
	33	+	Added: `resolver.define('getMenu', async ({ payload, context }) => {`
	34	+	Added: `const menu = typeof payload?.menuId === 'string' ? await getMenu(payload.menuId) : undefined;`
	35	+	Added: `if (!menu \|\| menu.requestedBy !== context.accountId) return { error: 'No menu with that receipt.' };`
	36	+	Added: `return { status: menu.status, tickets: menu.tickets ?? [], page: menu.page ?? null, error: menu.error ?? null };`
	37	+	Added: `});`
	38	+	Added:
46	39		`export const handler = resolver.getDefinitions();`

Why: Job id · Product context

getMenu compares context.accountId with the person who sent the menu, so a receipt id on its own shows nothing to anyone else.

Stuck? My menu stays “waiting” or ends “failed”

Done: submitMenu returns a menuId, and getMenu answers only the sender

Step 6: Write a ticket on the restaurant’s badge

The ticket-writing code moves into its own file, now as the app. The space always comes from settings, never from the menu:

New filesrc/kitchen/createTicket.js

A new file: the project always comes from settings, never from the browser.

1	+	Added: `import api, { route } from '@forge/api';`
2	+	Added: `import { LABELS, LIMITS, settings } from '../lib/config';`
3	+	Added: `import { paragraphs } from '../lib/adf';`
4	+	Added:
5	+	Added: `/**`
6	+	Added: `* Creates one dish ticket on the restaurant's own badge (asApp). No user is`
7	+	Added: `* present in a queue consumer. The project always comes from settings.`
8	+	Added: `*/`
9	+	Added: `export async function createTicket({ summary, notes, specialist = false }) {`
10	+	Added: `const { projectKey, issueType } = settings();`
11	+	Added: `const labels = specialist ? [LABELS.MENU, LABELS.SPECIALIST] : [LABELS.MENU];`
12	+	Added: const response = await api.asApp().requestJira(route`/rest/api/3/issue`, {
13	+	Added: `method: 'POST',`
14	+	Added: `headers: { Accept: 'application/json', 'Content-Type': 'application/json' },`
15	+	Added: `body: JSON.stringify({`
16	+	Added: `fields: {`
17	+	Added: `project: { key: projectKey },`
18	+	Added: `issuetype: { name: issueType },`
19	+	Added: `summary: summary.slice(0, LIMITS.SUMMARY),`
20	+	Added: `description: paragraphs(notes),`
21	+	Added: `labels,`
22	+	Added: `},`
23	+	Added: `}),`
24	+	Added: `});`
25	+	Added: `if (!response.ok) {`
26	+	Added: throw new Error(`Jira answered ${response.status}: ${await response.text()}`);
27	+	Added: `}`
28	+	Added: `const issue = await response.json();`
29	+	Added: `return issue.key;`
30	+	Added: `}`

Why: asApp()

Done: src/kitchen/createTicket.js uses api.asApp()

Step 7: The prep cook works the rail

Runs in the Atlassian cloud · Back of house

Consumer (worker function) · the prep cook

A consumer is the function a consumer module runs for each event on its queue. It starts after the resolver has already answered, gets the event’s body, and has its own time limit. If it throws, Forge can run it again with the same event, so it must be safe to run twice.

In the kitchen The prep cook takes slips off the rail one at a time and does the long work.

Later, Forge runs the consumer function with the event.Later, the prep cook takes the slip off the rail.

For now the prep cook writes one ticket for the whole menu, as the desk did, and records progress in the menu’s jar as it goes. The desk shows those statuses.

New filesrc/worker.js

A new file: one run per job slip, after submitMenu has returned.

1	+	Added: `import { getMenu, saveMenu } from './menus';`
2	+	Added: `import { createTicket } from './kitchen/createTicket';`
3	+	Added:
4	+	Added: `// The prep cook. Forge runs this once per job slip on the menu-jobs rail, after`
5	+	Added: `// submitMenu has already returned. A slip can arrive more than once, so every`
6	+	Added: `// step checks the checkpoint before doing work.`
7	+	Added: `export async function run(event) {`
8	+	Added: `const { menuId } = event.body;`
9	+	Added: `const menu = await getMenu(menuId);`
10	+	Added: `if (!menu) {`
11	+	Added: console.error(`Prep cook: no menu ${menuId}`);
12	+	Added: `return;`
13	+	Added: `}`
14	+	Added: `const checkpoint = menu.checkpoint ?? {};`
15	+	Added: `const save = (status, extra = {}) => saveMenu(menuId, { ...menu, ...extra, status, checkpoint });`
16	+	Added: `try {`
17	+	Added: `await save('cooking');`
18	+	Added: `if (!checkpoint.menuTicket) {`
19	+	Added: `checkpoint.menuTicket = await createTicket({ summary: menu.title, notes: menu.notes });`
20	+	Added: `await save('cooking');`
21	+	Added: `}`
22	+	Added: `await save('done', { tickets: [{ key: checkpoint.menuTicket, dish: menu.title }] });`
23	+	Added: `} catch (error) {`
24	+	Added: console.error(`Prep cook: menu ${menuId} failed:`, error);
25	+	Added: `await save('failed', { error: error.message });`
26	+	Added: `throw error;`
27	+	Added: `}`
28	+	Added: `}`

Why: Consumer (worker function) · Checkpoint

Stuck? My menu stays “waiting” or ends “failed”

Done: src/worker.js exports run

Step 8: Put the rail and the prep cook on the licence

Three changes: the consumer, which joins the rail to the prep cook; the prep cook’s function with a longer timer; and the scope for storage. The queue’s name, menu-jobs, must match new Queue({ key: 'menu-jobs' }) exactly.

Editmanifest.ymlChange 1 of 3

A consumer: the menu-jobs rail is worked by menu-worker.

18	18		`function: bell`
19	19		`events:`
20	20		`- avi:jira:created:issue`
	21	+	Added: `consumer:`
	22	+	Added: `- key: menu-consumer`
	23	+	Added: `queue: menu-jobs`
	24	+	Added: `function: menu-worker`
21	25		`function:`
22	26		`- key: resolver`
23	27		`handler: index.handler`

Editmanifest.ymlChange 2 of 3

The prep cook’s function, with a longer timer.

25	29		`handler: bell.run`
26	30		`- key: desk-resolver`
27	31		`handler: desk.handler`
	32	+	Added: `- key: menu-worker`
	33	+	Added: `handler: worker.run`
	34	+	Added: `timeoutSeconds: 120`
28	35		`resources:`
29	36		`- key: main`
30	37		`path: src/frontend/index.jsx`

Editmanifest.ymlChange 3 of 3

A key to the labelled jars.

44	51		`scopes:`
45	52		`- read:jira-work`
46	53		`- write:jira-work`
	54	+	Added: `- storage:app`

Why: Queue (@forge/events) · Consumer (worker function) · Runtime limits · Key-Value Store (KVS)

Stuck? Sending a menu fails with “400 Bad Request” from the queue · I changed manifest.yml

Done: manifest.yml has a consumer for menu-jobs, a menu-worker function and the storage:app scope

Step 9: Quiet the bell for the kitchen’s own tickets

Declared in manifest.yml · The licence

ignoreSelf · the bell ignores the restaurant’s own badge

ignoreSelf: true in a trigger’s filter drops events that the app itself caused. Without it, every ticket the app writes rings its own bell, and a trigger that edits what it listens to can run in a loop.

In the kitchen If the kitchen itself changed the ticket, the bell stays quiet.

The Level 1 bell rings for every new work item, including the ones the prep cook now writes. Let it ignore the app’s own:

Editmanifest.yml

Tickets the app creates no longer ring the bell.

18	18		`function: bell`
19	19		`events:`
20	20		`- avi:jira:created:issue`
	21	+	Added: `filter:`
	22	+	Added: `ignoreSelf: true`
21	23		`consumer:`
22	24		`- key: menu-consumer`
23	25		`queue: menu-jobs`

Why: ignoreSelf · Product trigger

Stuck? I changed manifest.yml

Done: the new-ticket-bell trigger has ignoreSelf: true

Step 10: Build, deploy and sign the new licence

storage:app is a new scope, so this is a major version:

RunTerminal

npm run build:ui
forge deploy --approve MAJOR_VERSION_RULE
forge install --upgrade

Stuck? Deploy stops after a permission change · I changed the menu desk (Level 2) · The tunnel is running while I deploy or upgrade

Done: forge install --upgrade finished

Step 11: Send the menu and take a receipt

Open the menu desk and send the Spring menu again. The button is free almost at once, and the desk shows the receipt moving: on the rail, writing dish tickets, done. Open the new ticket: its reporter is the app, not you. forge logs shows no bell line for it.

Stuck? My menu stays “waiting” or ends “failed” · Sending a menu fails with “400 Bad Request” from the queue

Done: the desk showed a receipt at once, then the new ticket, reported by the app

Compare with yours: download the code after this lesson.

Feel the wait

Lesson 1 · Wait for Jira asUser()

Lesson 2 · Take a receipt asApp()

Lesson 1 · Wait for Jira `asUser()`

Lesson 2 · Take a receipt `asApp()`