From Zero to Forge Hero: Building Custom Apps in Jira Service Management

Ready to unleash the power of custom forge apps in Jira Service Management? This guide equips you with everything you need to build your first custom app using Atlassian Forge!

This guide will walk you through the process of creating a simple Forge app using Windows 11 and Powershell that integrates with Jira Service Management, enabling you to build your own app within Jira Service Management.

If you use a different Operating system or prefer another command line interface, you can find the Official Atlassian Documentation here.

Prerequisites:

Forge apps are written in JavaScript so you'll need to be familiar with the basics of JavaScript. It's also helpful to be familiar with React.

Set up Node.js

The Forge CLI requires a fully supported LTS release of Node.js installed; namely, versions 18.x or 20.x. Follow the Node.js setup instructions specific for Windows 11 below:

1. Download the LTS installer from Node.js.
2. Install the package using one of the methods listed in the Node.js link

I didn't have any package managers installed so I chose the "Prebuilt Installer" as shown below.

Forge CLI: Install the latest version of the Forge CLI:

1. Run the following command on Powershell to install the latest Forge version:

npm install --g @forge/cli@latest         

If you have any issues with the command npm, you will need to verify your installation of Nodejs above.

2. Verify that the CLI is installed correctly by running:

forge --version        

You should see a version be printed out, you might see other warnings but if you see a version number, it has been installed.

If you are ever stuck and need assistance, you can type the command:

forge --help        

Logging into Forge

You will log in with your Atlassian Username (Email) and a password (Atlassian API Token).

1. First, we need to create an API token by going to https://id.atlassian.com/manage/api-tokens
2. Click Create API token.
3. Enter a label to describe your API token. For example, forge-api-token.
4. Click Create.
5. Click Copy to clipboard and close the dialog.

To start the login process, enter the command:

forge login        

You'll be asked whether to allow Forge to collect usage analytics data (use the arrow keys and enter to navigate):

Allow Forge to collect CLI usage and error reporting information?        

Answering Yes will allow Forge to collect data about your app's deployments and installations (including error data).

Enter the email address associated with your Atlassian account.

Enter your Atlassian API token, you can paste this in from your previous copy.

It should look similar to the below screenshot.

Creating your first JSM custom app

To start the process:

forge create        

1. Enter a name for your app (up to 50 characters). For example, first-jsm-app.
2. Select the UI Kit category.
3. Select the Jira Service Management product.
4. Select the jira-service-management-queue-page template.

Be patient and wait for the creation of the app, it might take a few minutes.

Change to the app subdirectory to see the app files:

cd first-jsm-app        

You can now also run the dir command to see the file structure, it should look like this:

first-jsm-app

├── README.md

├── manifest.yml

├── package-lock.json

├── package.json

└── src

├── frontend

│?? └── index.jsx

├── index.js

└── resolvers

└── index.js

Let’s have a look at what these files are:

• manifest.yml: Describes your app. This file contains the name and ID of the app, the app permissions, and the modules the app uses. To learn more about the manifest.yml file, see Forge manifest documentation.
• package.json: The app’s Node.js metadata. See the Node documentation for more information.
• package-lock.json: Records the version of the app’s dependencies.
• README.md: Information about the app. We recommend updating this as you change the behavior of the app.
• src/frontend/index.jsx: Where you write the application with which the user interacts directly.
• src/resolvers/index.js: Where you write backend functions (resolver functions) for your app. To learn more about resolvers, see the Custom UI Resolver documentation.

Change the page title

This app displays content in a Jira Service Management queues section of your project using the jiraServiceManagement:queuePage module. Jira Service Management shows the title of the jiraServiceManagement:queuePage as the page's heading, as well as in the list of apps in left navigation. Let's change the title to include your name.

1. In the app’s top-level directory, open the manifest.yml file.
2. Find the title entry under the jiraServiceManagement:queuePage module.
3. Change the value of title from first-jsm-app to forge-app-for-<your name>. For example, forge-app-for-brandon.

Your manifest.yml file should look like the following, with your values for the title and app ID:

modules:
  jiraServiceManagement:queuePage:
    - key: first-jsm-app-hello-world-queue-page
      resource: main
      resolver:
        function: resolver
      render: native
      title: forge-app-for-brandon
  function:
    - key: resolver
      handler: index.handler
resources:
  - key: main
    path: src/frontend/index.jsx
app:
  id: '<your app id>'        

Install your app

To use your app, it must be installed onto an Atlassian site. The forge deploy command builds, compiles, and deploys your code, and reports any compilation errors. The forge install command then installs the deployed app onto an Atlassian site with the required API access.

Navigate to the app's top-level directory and deploy your app by running:

forge deploy        

Install the app:

forge install        

1. Select your Atlassian product using the arrow keys and press the enter key. We had to choose Jira here as there is not Jira Service Management product listed.
2. Enter the URL for your development site. For example, example.atlassian.net.

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.

View your app

With your app installed, it’s time to see the app on your project's queues section.

1. Create a new Jira Service Management Project. Learn more about Jira Service Management Queues.
2. In the left navigation of your project, open queues and select the app from the Apps section. Your app should display like the example below.

You can also find your app in the usual area for app on the navigation bar at the top of the screen

Explaining the messages and code

We can see that Hello World is displayed twice in our basic app, this is because there are messages in two areas of the app structure.

"first-jsm-app\src\frontend\index.jsx" code displays Hello World without a comma:

import React, { useEffect, useState } from 'react';
import ForgeReconciler, { Text } from '@forge/react';
import { invoke } from '@forge/bridge';
const App = () => {
  const [data, setData] = useState(null);
  useEffect(() => {
    invoke('getText', { example: 'my-invoke-variable' }).then(setData);
  }, []);
  return (
    <>
      <Text>Hello world!</Text>
      <Text>{data ? data : 'Loading...'}</Text>
    </>
  );
};
ForgeReconciler.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);        

Whereas "first-jsm-app\src\resolvers\index.js" displays a console log function with the message "Hello, World!" with a comma.

import Resolver from '@forge/resolver';

const resolver = new Resolver();

resolver.define('getText', (req) => {
  console.log(req);
  return 'Hello, world!';
});

export const handler = resolver.getDefinitions();        

Deploy app changes

Once your app is installed, it will automatically pick up all minor app deployments so you don't need to run the forge install command again.

Minor deployments are changes that don't modify app permissions in the manifest.yml file. You can deploy the changes onto your developer site or Bitbucket workspace by using one of two methods:

• Manually, by running the forge deploy command.
• Automatically, by running the forge tunnel command.

Take your time, test and practice editing the frontend and resolver code and your creativity can run wild.

This is just the start of Atlassian Forge Custom apps, if you would like to learn more and create more complex apps, you can check out Atlassian's Forge documentation and youtube tutorials on the Atlassian Developer youtube channel.

Elegance Group - Atlassian Platinum Partner

Proudly sponsored by Elegance Group, a distinguished Atlassian partner recognised globally and awarded Partner of the Year in 2022 and still conducting elegant solutions.

For expert Licensing or Services from an acclaimed Atlassian Partner, reach out to Elegance Group. Book a meeting with us to enhance your business with our unparalleled Atlassian solutions.