Print the menu of record · Level 2

Step 1: Keys to the menu book

Writing a page takes two Confluence scopes: one to look up the space, one to create pages in it. Add them now; the code that needs them comes next.

Editmanifest.yml

Read spaces and write pages in Confluence.

58	58		`- read:jira-work`
59	59		`- write:jira-work`
60	60		`- storage:app`
	61	+	Added: `- read:space:confluence`
	62	+	Added: `- write:page:confluence`

Why: Scope · Confluence page

Stuck? I added a scope or a supplier host

Done: manifest.yml lists read:space:confluence and write:page:confluence

Step 2: Write the menu of record

After the tickets, the consumer writes one Confluence page that lists them.After the tickets, the prep cook prints the menu of record.

A new file finds the space’s id from its key, then creates the page through Confluence’s REST API. The body is Confluence’s storage format, a kind of XHTML, so every piece of text goes through escapeHtml first.

New filesrc/kitchen/menuPage.js

A new file: find the space, then create one page listing every dish ticket.

1	+	Added: `import api, { route } from '@forge/api';`
2	+	Added: `import { escapeHtml } from '../lib/html';`
3	+	Added:
4	+	Added: `/** Looks up a Confluence space's id from its key. Pass api.asApp() or api.asUser(). */`
5	+	Added: `export async function findSpaceId(client, spaceKey) {`
6	+	Added: const response = await client.requestConfluence(route`/wiki/api/v2/spaces?keys=${spaceKey}&limit=1`);
7	+	Added: if (!response.ok) throw new Error(`Confluence answered ${response.status} looking for space ${spaceKey}.`);
8	+	Added: `const data = await response.json();`
9	+	Added: `const id = String(data.results?.[0]?.id ?? '');`
10	+	Added: if (!/^\d+$/.test(id)) throw new Error(`No Confluence space with key ${spaceKey}.`);
11	+	Added: `return id;`
12	+	Added: `}`
13	+	Added:
14	+	Added: `// Storage format is XHTML. The jira macro shows each ticket as a live card.`
15	+	Added: `function render(menu, tickets) {`
16	+	Added: `const dishes = tickets`
17	+	Added: .map((t) => `<li><ac:structured-macro ac:name="jira"><ac:parameter ac:name="key">${escapeHtml(t.key)}</ac:parameter></ac:structured-macro> ${escapeHtml(t.dish)}</li>`)
18	+	Added: `.join('');`
19	+	Added: const people = menu.attendees?.length ? `<p>At the meeting: ${escapeHtml(menu.attendees.join(', '))}</p>` : '';
20	+	Added: `const notes = escapeHtml(menu.notes).replace(/\n/g, '<br/>');`
21	+	Added: return `<p>Agreed at the menu meeting “${escapeHtml(menu.title)}”.</p>${people}<h2>Dishes</h2><ul>${dishes}</ul><h2>Notes</h2><p>${notes}</p>`;
22	+	Added: `}`
23	+	Added:
24	+	Added: `/** The menu of record: one page per menu, in the space from settings, on the restaurant's badge. */`
25	+	Added: `export async function createMenuPage({ spaceKey, menuId, menu, tickets }) {`
26	+	Added: `const spaceId = await findSpaceId(api.asApp(), spaceKey);`
27	+	Added: const response = await api.asApp().requestConfluence(route`/wiki/api/v2/pages`, {
28	+	Added: `method: 'POST',`
29	+	Added: `headers: { Accept: 'application/json', 'Content-Type': 'application/json' },`
30	+	Added: `body: JSON.stringify({`
31	+	Added: `spaceId,`
32	+	Added: `status: 'current',`
33	+	Added: title: `Menu of record: ${menu.title} (${menuId.slice(0, 8)})`,
34	+	Added: `body: { representation: 'storage', value: render(menu, tickets) },`
35	+	Added: `}),`
36	+	Added: `});`
37	+	Added: if (!response.ok) throw new Error(`Confluence answered ${response.status}: ${await response.text()}`);
38	+	Added: `const page = await response.json();`
39	+	Added: return { id: String(page.id), title: page.title, url: `${page._links?.base ?? ''}${page._links?.webui ?? ''}` };
40	+	Added: `}`

Why: Confluence page · Product REST APIs

Stuck? The tickets appear, but no Confluence page

Done: src/kitchen/menuPage.js exports createMenuPage and findSpaceId

Step 3: A way to leave a note on a ticket

A small helper adds a comment to a work item as the app:

New filesrc/kitchen/comment.js

A new file: comment on a work item on the restaurant’s badge.

1	+	Added: `import api, { route } from '@forge/api';`
2	+	Added:
3	+	Added: `/** Adds a comment (an ADF document) to a work item on the restaurant's own badge. */`
4	+	Added: `export async function comment(issueKey, body) {`
5	+	Added: const response = await api.asApp().requestJira(route`/rest/api/3/issue/${issueKey}/comment`, {
6	+	Added: `method: 'POST',`
7	+	Added: `headers: { Accept: 'application/json', 'Content-Type': 'application/json' },`
8	+	Added: `body: JSON.stringify({ body }),`
9	+	Added: `});`
10	+	Added: if (!response.ok) throw new Error(`Jira answered ${response.status} commenting on ${issueKey}.`);
11	+	Added: `}`

Why: asApp()

Done: src/kitchen/comment.js exports comment

Step 4: Publish once, then link every ticket

After the tickets, the prep cook writes the page, if a space is set, and then comments the link on each ticket. Both steps are checkpointed:

Editsrc/worker.jsChange 1 of 2

Bring in the page, the comment and the settings.

1	1		`import { getMenu, saveMenu } from './menus';`
2	2		`import { createTicket } from './kitchen/createTicket';`
3	3		`import { splitMenu } from './kitchen/splitMenu';`
	4	+	Added: `import { createMenuPage } from './kitchen/menuPage';`
	5	+	Added: `import { comment } from './kitchen/comment';`
	6	+	Added: `import { withLink } from './lib/adf';`
	7	+	Added: `import { settings } from './lib/config';`
4	8
5	9		`// The prep cook. Forge runs this once per job slip on the menu-jobs rail, after`
6	10		`// submitMenu has already returned. A slip can arrive more than once, so every`

Editsrc/worker.jsChange 2 of 2

After the tickets: write the page once, then comment on each ticket once.

33	37		`}`
34	38		`tickets.push({ key: checkpoint.created[index], dish: dish.dish });`
35	39		`}`
36		−	Removed: `await save('done', { tickets });`
	40	+	Added: `const { spaceKey } = settings();`
	41	+	Added: `if (spaceKey && !checkpoint.page) {`
	42	+	Added: `await save('publishing', { tickets });`
	43	+	Added: `checkpoint.page = await createMenuPage({ spaceKey, menuId, menu, tickets });`
	44	+	Added: `await save('publishing', { tickets });`
	45	+	Added: `}`
	46	+	Added: `checkpoint.commented = checkpoint.commented ?? {};`
	47	+	Added: `for (const ticket of checkpoint.page ? tickets : []) {`
	48	+	Added: `if (checkpoint.commented[ticket.key]) continue;`
	49	+	Added: `await comment(ticket.key, withLink('On the menu of record:', checkpoint.page.url));`
	50	+	Added: `checkpoint.commented[ticket.key] = true;`
	51	+	Added: `await save('publishing', { tickets });`
	52	+	Added: `}`
	53	+	Added: `await save('done', { tickets, page: checkpoint.page ?? null });`
37	54		`} catch (error) {`
38	55		console.error(`Prep cook: menu ${menuId} failed:`, error);
39	56		`await save('failed', { error: error.message });`

Why: Confluence page · Checkpoint

Stuck? The tickets appear, but no Confluence page · My menu stays “waiting” or ends “failed”

Done: the worker writes the page once and comments on each ticket once

Step 5: Sign the licence, and open in Confluence

New scopes mean a major version. And the app has only been installed on Jira so far; to write pages, it needs an installation on Confluence on the same site, once:

RunTerminal

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

For the last command, choose Confluence and your developer site. From now on, a major version needs forge install --upgrade for both installations; the CLI asks which one to upgrade.

Stuck? The app now writes to Confluence (Level 2) · Deploy stops after a permission change

Done: the app is installed on Confluence on your developer site

Step 6: Send a menu and read the page

Send a menu from the desk. When it is done, the desk offers to open the page in Confluence. It lists every new dish ticket as a live card, with the notes below. Open any of those tickets: its comments include a link back to the page.

Stuck? The tickets appear, but no Confluence page

Done: a menu-of-record page lists the new tickets, and each ticket links to it