Last updated Aug 24, 2017
Improve this page

Getting started

Welcome to Jira Cloud development! This tutorial is designed to help you learn the basics of development for the Jira Cloud products (i.e. Jira Core, Jira Software, and Jira Service Desk), using Atlassian Connect. Atlassian Connect is our recommended framework for extending Jira Cloud, and handles discovery, installation, authentication, and seamless integration into the Jira UI.

By the end of this tutorial, you’ll have set up everything you need to start developing for Jira Cloud. This includes setting up your local development environment for Atlassian Connect, getting a Jira Cloud development instance, and validating your setup by building and deploying a basic “Hello World” app.

Before you begin

To complete this tutorial, you’ll need the following:

  • Your favorite IDE or text editor.
  • A basic knowledge of JavaScript and web development.
  • A basic understanding of Jira.
  • A running Node.js environment (v4.5.0 or later required): download Node.js, if you don’t have it already. Node.js bundles npm, which you’ll also need.
  • A tool for tunneling to the internet. There are a number of tools that you can use to tunnel your local development environment to the internet, but we recommend ngrok, which is free and easy to use.

Set up a development environment

To develop for Jira Cloud, you’ll need two things: a local development environment to build apps and an Atlassian Cloud instance to test them in.

Step 1. Get an Atlassian Cloud instance

Let’s start by getting you an Atlassian Cloud instance that you can install and test your apps on. 

  1. Go to go.atlassian.com/cloud-dev and sign up for a free development environment. It will take a several minutes to provision.
  2. Once your Atlassian Cloud instance is ready, sign in and complete the setup wizard. 
  3. Finally, enable development mode for your Atlassian Cloud instance. This lets you install apps in your instance that are not from the Atlassian Marketplace:
    1. Navigate to Jira settings (cog icon ) > Add-ons  > Manage add-ons.
    2. Scroll to the bottom of the Manage add-ons page and click Settings.
    3. Select the Enable development mode checkbox.

Your Atlassian Cloud development instance has Confluence and all of the Jira products installed, but be aware that Atlassian Cloud development instances have limits on the number of users.

Step 2. Set up your local development environment

If you install an Atlassian Connect app in an Atlassian Cloud instance, the app itself is usually hosted elsewhere (e.g. on a service like Heroku). However, when you are building an app, it’s easiest to develop it on your local machine and make it available over the internet (via HTTPS) via tunneling. This allows you to test it against an Atlassian Cloud instance, but still work locally. 

  1. If you have npm installed, use: npm install -g ngrok
  2. Check that it’s working by running ngrok help in your terminal. 

That’s all the setup that you need to do for now. We’ll show you how to use ngrok to make your app available to the internet later in this tutorial, when you deploy your app.

Build a basic app

In this section, you’ll build a basic app by turning a simple web application into an Atlassian Connect app. This app will be for Jira Cloud, but the process is similar for other Atlassian products. This will give you a hands-on introduction to Atlassian Connect and will validate that your development environment is set up correctly.

Step 1. Define an app descriptor

The fundamental building block of an app is the JSON descriptor file, usually named atlassian-connect.json. This file describes your app to the Atlassian application, including your app’s key, name, permissions needed to operate, and the different modules it uses for integration.

In the steps below, you’ll define the atlassian-connect.json file for a Jira Cloud app. It will use a generalPages module, and add a link to Jira’s top navigation element titled “Greeting”. 

  1. Create a project directory for your app source files. You’ll be working in this directory for the rest of this tutorial.

  2. In your project directory, create a new file named atlassian-connect.json with the following contents:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
    {
     "name": "Hello World",
     "description": "Atlassian Connect app",
     "key": "com.example.myapp",
     "baseUrl": "https://<placeholder-url>",
     "vendor": {
         "name": "Example, Inc.",
         "url": "http://example.com"
     },
     "authentication": {
         "type": "none"
     },
     "apiVersion": 1,
     "modules": {
         "generalPages": [
             {
                 "url": "/helloworld.html",
                 "key": "hello-world",
                 "location": "system.top.navigation.bar",
                 "name": {
                     "value": "Greeting"
                 }
             }
         ]
     }
 }

    Note, you don’t need to change the placeholder used for baseUrl for now. You’ll update it later in this tutorial when you’re ready to deploy your app.

  3. Save and close the descriptor file.

  4. (optional) Validate your descriptor using the Atlassian Connect validator. This handy tool shows you any errors in your app descriptor, such as missing properties, syntax errors, etc.

Step 2. Create a web application

Now that you’ve created the app descriptor, let’s create a web app. We’ll be using a simple static HTML page as the “app”. This is the most basic Atlassian Connect integration: an app descriptor and an HTML page that it uses. It’s not a typical app, but once you understand how it works, it takes only a few more steps to turn a web application into a fully fledged Atlassian Connect app.

  1. In your project directory, create a new file named helloworld.html. You’ll notice that this is the same filename referenced in the url element of your descriptor file.

  2. Add the following content to the helloworld.html file:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
    <!DOCTYPE html>
<html lang="en">
 <head>
     <link rel="stylesheet" href="//aui-cdn.atlassian.com/aui-adg/5.9.12/css/aui.min.css" media="all">
 </head>
 <body>
     <section id="content" class="ac-content">
         <div class="aui-page-header">
             <div class="aui-page-header-main">
                 <h1>Hello World</h1>
             </div>
         </div>
     </section>

     <script id="connect-loader" data-options="sizeToParent:true;">
         (function() {
             var getUrlParam = function (param) {
                 var codedParam = (new RegExp(param + '=([^&]*)')).exec(window.location.search)[1];
                 return decodeURIComponent(codedParam);
             };

             var baseUrl = getUrlParam('xdm_e') + getUrlParam('cp');
             var options = document.getElementById('connect-loader').getAttribute('data-options');

             var script = document.createElement("script");
             script.src = baseUrl + '/atlassian-connect/all.js';

             if(options) {
                 script.setAttribute('data-options', options);
             }

             document.getElementsByTagName("head")[0].appendChild(script);
         })();
     </script>

 </body>
</html>

  3. Save your file.

That’s all the coding you need to do. Let’s have a look at the content of the helloworld.html file in more detail:

  • Styling— The HTML page uses Atlassian User Interface (AUI), by including the relevant CSS from the AUI CDN. AUI is a library of reusable front-end UI components.
  • The ac-content class— This class wraps the content of your app and dynamically resizes the iframe in Jira. This keeps your app content visible without pesky scrollbars.
  • The script tag — The all.js file is included in the HTML page via a script tag. This file is the client library for the Atlassian Connect JavaScript API, and is hosted on every Atlassian Cloud application. The Atlassian Connect JavaScript API simplifies client interactions with the Atlassian application, like making an XMLHttpRequest. The all.js file can be found at the following URL for your Atlassian application: //HOSTNAME.atlassian.net/CONTEXT/atlassian-connect/all.js This URL is constructed from the following parameters:
    • HOSTNAME: The hostname for the Atlassian application.
    • CONTEXT: The application context for the application. jira is the default context (when none is provided) and wiki is used for Confluence. Note, within your iframe, you must get the all.js script from the product domain. The code within the script tag above, is an easy way to do this without a having to re-create the HTML through a template on each call. For more information, check out the Atlassian Connect JavaScript API.

Step 3. Deploy your app

You now have your first Atlassian Connect app! Let’s get it running in your Atlassian Cloud instance. To deploy it, you’ll be hosting it on a web server, using ngrok to make it available to the internet, then installing your app in your Atlassian Cloud instance.

Host your app on a web server

You’ll need a simple web server to serve the current directory containing your atlassian-connect.json and helloworld.html files. There are number of tools you can use to do this, but in this tutorial, we’ll be using http-server (available via npm).

  1. Install http-server via the following npm command, by running the following command from your terminal:

    1
    npm install http-server -g

  2. In your project directory, start your server on port 8000, by running the following command from your terminal:

    1
    http-server -p 8000

    You’ll see a message in your terminal indicating that the server is serving HTTP at the current address and port. It will look something like this: “Starting up http-server, serving ./ on: http://0.0.0.0:8000/”.

  3. Confirm that the files you created in steps 1 and 2 are being served. Visit the following URLs and you should be able to view your app files:

    • http://localhost:8000/atlassian-connect.json
    • http://localhost:8000/helloworld.html

Make your app files available to the internet

Now that your app is hosted on a local web server, you need to make it available over the internet. The following steps describe how to do this using ngrok.

  1. (Optional) For future app development, you will need to find out what port your app is running on by doing one of the following:
    • Run the app and look for the port in the logs
    • Check the project README for details

  2. Run the following command from your terminal. This will expose your web server to the internet. If your app is not running on port 8000, change the command to use your app’s port number.

    1
    ngrok http 8000

    You’ll also be shown a status page in your terminal (see next step) that shows the public URL of your tunnel and other information about connections made over your tunnel.

    {{% note %}}If your app is not running when you try to start ngrok, you’ll see a “Failed to complete tunnel connection” message.{{% /note %}}

  3. Get the HTTPS URL from the ngrok status page, as shown in the following image:

    Ngrok example with HTTPS

  4. Edit your app’s descriptor and set the baseUrl property to the ngrok HTTPS URL (from the previous step). e.g.

    1
    "baseUrl": "https://02b76172.ngrok.io"

    {{% note %}}If you build more apps in future, note that the baseUrl attribute must be unique to each app.{{% /note %}}

  5. Confirm the descriptor is available from the ngrok HTTPS URL. This is the URL you will use to install your app in your Atlassian Cloud instance in the next section. If you were using the HTTPS URL in the image above, your descriptor URL would look something like this: https://02b76172.ngrok.io/atlassian-connect.json.

Install your app

We’re nearly there! The final step in deploying your app is to install it in your Atlassian Cloud instance. You’ll do this by adding a link to your app’s descriptor file from your Atlassian Cloud instance. This allows Jira to install your app.

  1. Navigate to Jira in your Atlassian Cloud instance, then choose the cog menu > Add-ons .
  2. Click Manage add-ons >  Upload add-on.

  3. Enter the link to your app descriptor. This URL should match the hosted location of your atlassian-connect.json descriptor file. e.g.

    1
    https://02b76172.ngrok.io/atlassian-connect.json

  4. Click Upload. Jira will display the ’Installed and ready to go’ dialog when the installation is complete.

  5. Click Close.

  6. Verify that your app appears in the list of User installed. For example, if you used Hello World for your app name, ‘Hello World’ should appear in the list.

  7. Reload the page. A new item labeled ‘Greeting’ will appear in the header.

  8. Click Greeting. A “Hello World” message will be displayed on a page.

{{% tip title=“Congratulations!”%}}You’ve set up a development environment and built your first app.{{% /tip %}}

Next steps

You now know enough to start developing apps with Atlassian Connect. If you’d like to keep learning about app development for Jira Cloud, see the following pages: