Read the ticket · Level 1

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

The card still asks for Pad thai on every ticket. This lesson makes the cook read the summary of the ticket the card is on. That means a call into Jira, and Jira has its own rules about who may read what.

Step 1: Bring in the Jira API

Atlassian’s own products · House systems

Product REST APIs · the house systems

Jira and Confluence have REST APIs for everything you see on screen: work items, comments, pages. From a function you call them through @forge/api, with requestJira or requestConfluence, and a path built with the route tag. Forge adds the authentication; you never handle a Jira token.

In the kitchen The building’s own systems: the ticket board and the menu book.

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

The package is already installed from lesson 4. Import its default export and route:

Editsrc/resolvers/index.js

api and route come from @forge/api.

1	1		`import Resolver from '@forge/resolver';`
	2	+	Added: `import api, { route } from '@forge/api';`
2	3		`import { findDish } from '../supplier/apiNinjas';`
3	4
4	5		`const resolver = new Resolver();`

Why: Product REST APIs

Stuck? “Cannot find module @forge/…”

Done: the resolver imports api and route from @forge/api

Step 2: Read the summary on the staff member’s badge

Runs in the Atlassian cloud · Back of house

asUser() · on the staff member’s badge

asUser() makes the call as the person using the app, with exactly their permissions. If they cannot see a work item, neither can your code. The first time someone uses an asUser() call, Jira asks them to allow the app to act for them. Its opposite, asApp(), acts as the app itself; Level 2 needs it for work that runs with nobody watching.

In the kitchen The kitchen goes into the house systems on the badge of the person who asked, and can only open what they can.

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

The resolver reads the summary with asUser().The cook reads the ticket on the staff member’s badge.

Add a helper that asks Jira for one work item, with only the summary field:

Editsrc/resolvers/index.js

A helper that asks Jira for one work item’s summary.

4	4
5	5		`const resolver = new Resolver();`
6	6
	7	+	Added: `// Ask Jira for the work item's summary, with the permissions of the person viewing it.`
	8	+	Added: `async function readSummary(issueId) {`
	9	+	Added: const response = await api.asUser().requestJira(route`/rest/api/3/issue/${issueId}?fields=summary`);
	10	+	Added: `if (!response.ok) {`
	11	+	Added: throw new Error(`Jira answered ${response.status} for this work item.`);
	12	+	Added: `}`
	13	+	Added: `const issue = await response.json();`
	14	+	Added: `return issue.fields.summary;`
	15	+	Added: `}`
	16	+	Added:
7	17		`resolver.define('getDish', async () => {`
8	18		`const query = 'pad thai';`
9	19		`try {`

Why: asUser() · Product REST APIs

route escapes the id safely, so a strange id can never change the path. A non-OK answer, such as 404 when the viewer cannot see the work item, becomes an error with the status in it.

Stuck? The app asks me to “Allow access”

Done: the resolver has a readSummary function that calls api.asUser().requestJira

Step 3: Cook the dish on the ticket

Runs in the Atlassian cloud · Back of house

Product context · the ticket number

Every resolver call arrives with a context that Forge fills in: who is calling, from which site, and from where in the product. On an issue panel, context.extension.issue holds the work item’s id and key. The browser cannot change it, so it is the right source for which ticket to read.

In the kitchen The runner always says which ticket the card is clipped to.

Atlassian docs: App context security (opens in a new tab)

Replace the fixed dish with the ticket’s summary:

Editsrc/resolvers/index.js

Take the work item id from the context, not from the browser, and use its summary.

14	14		`return issue.fields.summary;`
15	15		`}`
16	16
17		−	Removed: `resolver.define('getDish', async () => {`
18		−	Removed: `const query = 'pad thai';`
	17	+	Added: `resolver.define('getDish', async ({ context }) => {`
	18	+	Added: `const query = await readSummary(context.extension.issue.id);`
19	19		`try {`
20	20		`const dish = await findDish(query, process.env.API_NINJAS_KEY);`
21	21		`return { query, dish };`

Why: Product context

The card could have sent the work item id in invoke() instead, but anything the browser sends can be changed by the person using it. The context comes from Forge.

Stuck? The card says there is no recipe for my work item

Done: getDish reads the summary of context.extension.issue.id

Step 4: Let the inspector add the key

Declared in manifest.yml · The licence

Scope · a key to the house systems

A scope is a permission to use part of a product API, such as read:jira-work for reading work items. The app declares its scopes under permissions.scopes, the admin agrees to them at install, and Forge refuses any API call the scopes do not cover, even if the person could do it themselves.

In the kitchen Each key opens one door into the house systems. No key, no entry.

Atlassian docs: Permissions (opens in a new tab)

Lives on your laptop · Home kitchen

forge lint · the inspector

forge lint checks the manifest and code before a deploy and reports problems, such as an API call with no matching scope. forge lint --fix adds what it can work out for you. forge deploy runs the same checks first.

In the kitchen The inspector walks through, spots the missing key and writes it onto the licence for you.

The new call reads Jira, and the manifest has no scope for that yet. Ask the linter:

RunTerminal

forge lint

It reports the missing scope. Let it write it:

RunTerminal

forge lint --fix

Editmanifest.yml

forge lint --fix writes this for you.

24	24		`fetch:`
25	25		`backend:`
26	26		`- address: api.api-ninjas.com`
	27	+	Added: `scopes:`
	28	+	Added: `- read:jira-work`

Why: Scope · forge lint

Stuck? I added a scope or a supplier host

Done: manifest.yml lists read:jira-work under scopes

Step 5: Sign the new licence again

A new scope is a new permission, so this is a major version again. Stop the tunnel if it runs, then:

RunTerminal

forge deploy --approve MAJOR_VERSION_RULE
forge install --upgrade

Reload the Pad thai ticket. Because the cook now reads Jira as you, the card first asks you to allow access. Allow it once; the recipe appears after.

Stuck? Deploy stops after a permission change · The app asks me to “Allow access” · The tunnel is running while I deploy or upgrade

Done: forge install --upgrade finished and the card asked you to allow access

Step 6: Try other dishes

Create two more dish tickets in the Kitchen space, such as Lasagna and Tom yum soup, and open each one. Each card shows its own dish.

Rename one to something that is not a dish. The card shows the information message with the summary in it: the empty state from lesson 5, now with a real query.

Stuck? The card says there is no recipe for my work item

Done: two tickets show two different recipes

Compare with yours: download the code after this lesson.