Creating a Hello World Jira App

In this article, we will go through the necessary points for creating an application for Jira. Our application will be very simple, merely demonstrating the resources available for creating this type of application.

The Atlassian ecosystem have a series of software and tools for project management, with emphasis on Jira and Confluence. Developed by the Atlassian group, these applications are widely used in project management, especially in the context of software development.

Both Jira and Confluence offer a wide range of integrations through their app store. In this platform, users have access to a variety of solutions ready to be integrated into their projects, optimizing processes and increasing team productivity.

However, under certain circumstances, there may arise the need for a custom tool that is not available in the app store or in the standard features of the software. And that’s where Forge comes in, a tool offered by Atlassian.

With Forge, users have the ability to create their own applications directly within the Atlassian environment, customizing them according to their specific needs. These applications can be hosted and listed in the Atlassian ecosystem, ensuring integration with Jira and Confluence.

The developer documentation can be accessed here: https://developer.atlassian.com/.

Basically, it’s possible to create applications that will be using Node.js technologies on the backend and React on the frontend.

Additionally, through existing resources, it’s possible to use the Forge platform’s own UI kit, which already offers some pre-built components. It’s also possible to create a completely custom UI.

Before we start developing our application, we need to install the Forge CLI and also create an API token for the CLI, as described in the following documentation: https://developer.atlassian.com/platform/forge/getting-started/.

To install the Forge CLI, Docker and NPM are required, and after that, we can proceed with the installation using the following command:‍

npm install -g @forge/cli

And after installation and creating the API Token, we’ll log in using the command:

npm install -g @forge/cli

It’s necessary to create a development environment for our applications, where we can install and test before submitting to the Atlassian marketplace. This procedure is done through http://go.atlassian.com/cloud-dev.

Once done, we move on to creating the application. We navigate to the repository on our machine where we want to create the application and use the command:

forge create

In this process, we’ll need to define the app’s name, that we gonna call “hello-world-app“, choose a UI kit, where we should go for "UI kit 2 (Preview)", and also the product type and its template. For these two options, we should choose “Jira” and “jira-issue-panel,” thus creating a folder with the chosen name for the app.

Upon accessing the folder, we’ll have a file structure like this:

hello-world-app
├── README.md
├── manifest.yml
├── package-lock.json
├── package.json
└── src
   ├── frontend
   │   └── index.jsx
   ├── index.js
   └── resolvers
       └── index.js

• manifest.yml: Describes your app. This file contains the name and ID of the app, the app permissions, and the modules the app uses.
• package.json: The app’s Node.js metadata.
• package-lock.json: Records the version of the app’s dependencies.
• README.md: Information about 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.

This app displays content in a Jira issue panel using the jira:issuePanel module. Jira shows the title of the jira:issuePanel as the panel's heading. Let's change the title.

1. In the app’s top-level directory, open the manifest.yml file.
2. Find the title entry under the jira:issuePanel module.
3. Change the value of title from hello-world-app to Hello World App.

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

modules:
 jira:issuePanel:
   - key: hello-world-hello-world-issue-panel
     resource: main
     resolver:
       function: resolver
     render: native
     title: Hello World App
     icon: https://developer.atlassian.com/platform/forge/images/icons/issue-panel-icon.svg
 function:
   - key: resolver
     handler: index.handler
resources:
 - key: main
   path: src/frontend/index.jsx
app:
 id: '<your app id>'

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

You must run the forge deploy command before forge install because an installation links your deployed app to an Atlassian site.

forge deploy

forge install

After that you need to select the product using the arrow keys and press enter, in our case will be Jira. The last steep is to enter the URL from the development site that was created, 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.

With your app installed, it’s time to see the app on an issue. In the issue panel of that issue, select the button displaying the Atlassian logo. Your app should display like the example below.

From this point onwards, we can proceed with the development of our application, utilizing the resources available within Forge. For example, we can use tunnels via Docker to conduct tests and have logs of our application.

Various features are also available, such as configuration pages, admin panels, data storage, among others. Below is a list of documentation for useful resources available:

https://developer.atlassian.com/

https://developer.atlassian.com/platform/forge/getting-started/

https://developer.atlassian.com/platform/forge/build-a-hello-world-app-in-jira/

https://developer.atlassian.com/platform/forge/manifest-reference/modules/

https://developer.atlassian.com/platform/forge/apis-reference/product-rest-api-reference/

https://developer.atlassian.com/platform/forge/storage/

https://developer.atlassian.com/platform/forge/user-interface/‍