Part 2: Call a Jira Service Management API

This page introduces the Forge Javascript APIs. Using the @forge/api package, you'll learn how to make REST calls to an authenticated Jira Service Management endpoint.

This is part 2 of 3 in this tutorial. Complete Part 1: Build a Jira Service Management hello world app before working on this page.

Make an API call

In this section, you'll modify your app to call the Jira Service Management REST API. Using the Product Fetch API from the @forge/api package, you'll get the list of queues on a Jira Service Management queue page app in the form of an array and print the number of queues to the console.

The @forge/api package simplifies HTTP operations and contains other Forge APIs such as the Storage and Properties APIs. For this tutorial, you'll also use a UI kit hook to get context information about the Jira Service Management queues the app is on.

In the app’s top-level directory, install the @forge/api package API by running:
```
1
2
npm install @forge/api
```
Restart your tunnel to use the new npm modules by running:
```
1
2
forge tunnel
```
Make sure your docker is running.

Navigate to the src directory and open the index.jsx file. Import the @forge/api package by adding the following to the top of the file:

1
2
import api, { route } from "@forge/api";

Copy the following code to create a function that calls the Jira Service Management REST API by using the @forge/api package:

1
2
const getJsmQueues = async (serviceDeskKey) => {
  const res = await api
    .asUser()
    .requestJira(
        route`/rest/servicedeskapi/servicedesk/${serviceDeskKey}/queue`
    );
  const data = await res.json();
  return data.values;
};

This function takes a serviceDeskKey to call the REST API with path /rest/servicedeskapi/servicedesk/${serviceDeskKey}/queue.

Use the UI kit hook useProductContext to get the serviceDeskKey to call getJsmQueues:

Add useProductContext to the import statement as shown below:

1
2
import ForgeUI, { render, QueuePage, Fragment, Text, useProductContext } from "@forge/ui";

Add the following code to the App function directly before the return statement:

1
2
const context = useProductContext();

Fetch the list of queues for a service desk project and log the output in the App function.

Add the useState UI kit hook to the import statement as shown below:

1
2
import ForgeUI, { render, QueuePage, Fragment, Text, useProductContext, useState } from "@forge/ui";

Add the following code to the App function directly above the return statement:

1
2
const [queues] = useState(async () => await getJsmQueues(context.extensionContext.project.key));

console.log(`Number of queues : ${queues.length}`);

When you save the index.jsx file, the tunnel output in the terminal will display a permission-scope-required error. To address this, you'll need to add the required permissions first; this is covered in the next section.

Your index.jsx file should look like the following:

1
2
import api, { route } from "@forge/api";
import ForgeUI, { render, QueuePage, Fragment, Text, useProductContext, useState } from "@forge/ui";

  const getJsmQueues = async (serviceDeskKey) => {
    const res = await api
        .asUser()
        .requestJira(
            route`/rest/servicedeskapi/servicedesk/${serviceDeskKey}/queue`
        );
    const data = await res.json();
    return data.values;
  };

const App = () => {
  const context = useProductContext();
  const [queues] = useState(async () => await getJsmQueues(context.extensionContext.project.key));
  console.log(`Number of queues in your service desk project : ${queues.length}`);
  return (
    <Fragment>
      <Text>Hello world!</Text>
    </Fragment>
  );
};

export const run = render(
  <QueuePage>
    <App />
  </QueuePage>
);

Enable usage analytics (optional)

If you haven't enabled usage analytics yet, we recommend you do so using following command:

1
2
forge settings set usage-analytics true

This command provides the consent required by Forge to collect data about your app's deployments and installations (including error data). This, in turn, helps us monitor the overall performance and reliability of Forge. The collected data also helps us make better decisions on improving Forge's feature set and performance.

For information about how Atlassian collects and handles your data, read our Privacy Policy.

Set required app permissions

Your app calls a remote resource; namely, the Jira REST API. As such, you'll need to grant your app the right permissions. To do this, you'll need to add the required OAuth 2.0 scope to the app's manifest.

For more information on adding scopes, see Add scopes to call an Atlassian REST API.

In the steps below, you'll do this by using the forge lint command. This command will automatically add the required scope to your manifest.yml file (in this case, read:jira-work).

Run the following command:

1
2
forge lint --fix

Whenever you change permissions, you must upgrade the app's installation. Stop your tunnel process and run these commands to deploy and install your change:
```
1
2
forge deploy
forge install --upgrade
```
Start the tunnel again:
```
1
2
forge tunnel
```

Alternatively, you can also manually add required scopes to your manifest.yml file. Learn more about adding scopes to call an Atlassian REST API.

Test your app

Create a new Jira Service Management project, or open the one you created earlier.
Add a new queue to the Jira Service Management Project.
Refresh the app on Jira Service Management project Queue section.

You need to authorise the app to display it again, as the scopes have changed.

Check the output of the tunnel in the terminal. The number of queues on the app displays as follows:

1
2
invocation: 158b5987a4724ee5 index.run
INFO    08:36:00.464  fdaf676e0e72a872  Number of queues : 4

The .asUser() function inherits the product permissions of the user who has granted access to the app. This can cause different API responses between different users in the same app.

Next step

In the next tutorial, you'll learn how to make changes to your app's frontend using the UI kit components of Forge.