Getting started

This Hello World tutorial shows you a basic preview of the Connect framework. Connect add-ons are essentially web applications that integrate with your Atlassian product. In this tutorial, you'll turn a simple web application into an Atlassian Connect add-on. You'll install it in a locally-running copy of JIRA Cloud, and access your add-on from a link in the header. Your add-on displays as an iframe of your web application.

Here's what you'll accomplish:

By the end, you'll see your web application displayed in an iframe inside of JIRA:

Note: This is a beginner tutorial. You can build this add-on even if you've never built one before. You'll need the Atlassian SDK installed and ready to go before you start.

Create the add-on descriptor (atlassian-connect.json)

In this step you'll create a JSON descriptor file. This file describes your add-on to the Atlassian application, which in this case is JIRA Cloud. Your descriptor specifies your add-on's key, name, permissions needed to operate, and the different modules it uses for integration.

Your atlassian-connect.json file will use a generalPages module, and add a link to JIRA's top navigation element titled "Greeting".

  1. Create a project directory for your add-on source files.
    You'll work in this directory for the duration of this tutorial.
  2. In your project directory, create a new file named atlassian-connect.json.
  3. Add the following text to the file:
         "name": "Hello World",
         "description": "Atlassian Connect add-on",
         "key": "com.example.myaddon",
         "baseUrl": "http://localhost:8000",
         "vendor": {
             "name": "Example, Inc.",
             "url": ""
         "authentication": {
             "type": "none"
         "apiVersion": 1,
         "modules": {
             "generalPages": [
                     "url": "/helloworld.html",
                     "key": "hello-world",
                     "location": "",
                     "name": {
                         "value": "Greeting"
    Note: "baseUrl" attribute must be unique to each add-on
  4. Save and close the descriptor file.

Note: You can validate your descriptor using this handy tool.

Create a simple web application to stand in as an add-on

Now, you're ready to create the web app. You'll use a simple, old-fashioned HTML page as an "app" to demonstrate how Connect integrates with your application. While a static HTML page doesn't represent a typical add-on, it's not that far off either. Just a few components turn any web application into an Atlassian Connect add-on.

Your simple content will use AUI (Atlassian User Interface) styling. You'll add two key pieces to an HTML file: a script tag, and an ac-content wrapper class.

Element Details

This element is comprised of 3 values pointing toward all.js, formatted as //HOSTNAME:PORT/CONTEXT/atlassian-connect/all.js. These values are provided in the URL of the request for this resource.

Let's look at the components:

  • HOSTNAME: The hostname for the Atlassian application. Here, you'll use localhost for the sake of simplicity.
  • PORT: The port number on which the Atlassian application serves its web interface. JIRA uses port 2990, and Confluence uses 1990.
  • CONTEXT: The application context for the application, such as /jira or /confluence.
  • all.js: This file is available in any Atlassian application that supports Connect. This Javascript API library provides functions you can use for your add-on. In this case, it enables iframe resizing for the JIRA page that displays your add-on.
ac-content This class wraps the content of your add-on, and dynamically resizes the iframe in JIRA. This keeps your add-on content visible without pesky scrollbars.

From the same project directory:

  1. Create the page you referenced in the url element in your descriptor file, helloworld.html.
  2. Add the following content:

    <!DOCTYPE html>
    <html lang="en">
         <link rel="stylesheet" href="//" media="all">
         <script src="//localhost:2990/jira/atlassian-connect/all.js" type="text/javascript"></script>
         <section id="content" class="ac-content">
             <div class="aui-page-header">
                 <div class="aui-page-header-main">
                     <h1>Hello World</h1>

Start your add-on

That's it as far as coding goes. The next step is to make your files available on a web server. There are many ways to do this, but in this example you'll serve the file locally.

You'll use a simple web server to serve the current directory containing your atlassian-connect.json and helloworld.html files.

  1. From the same directory, start your server on port 8000:
    npm install http-server -g
    http-server -p 8000
    The server indicates that it's serving HTTP at the current address and port. You'll see something like this: Starting up http-server, serving ./ on:
  2. Confirm the files you created in steps 1 and 2 are served. Visit:

Start JIRA Cloud using the Atlassian SDK

You've created the essential components of a Connect add-on: an atlassian-connect.json descriptor file to communicate what your add-on does to JIRA, and a web application (helloworld.html) running on a local server. Now, you need to start JIRA in cloud mode to install your add-on.

Connect support is currently only for Atlassian-hosted products like JIRA Cloud, and not yet included with downloaded or locally-hosted instances. To simulate cloud products, components like the Connect framework are included in startup commands. Without these components Connect add-ons aren't installable.

  1. Ensure you have:

    • Java 8
    • the Atlassian SDK installed

      You'll need at least SDK version 4.2.20. If you run the atlas-version command, you should see something similar to this:

      ATLAS Version: 4.2.20
      ATLAS Home: /usr/share/atlassian-plugin-sdk-4.2.20
      ATLAS Scripts: /usr/share/atlassian-plugin-sdk-4.2.20/bin
      ATLAS Maven Home: /usr/share/atlassian-plugin-sdk-4.2.20/apache-maven
  2. From a new terminal window, start a local JIRA instance matching the Atlassian Cloud environment: Loading...

    Note: If you're not using the command above, ensure all components in the --bundled-plugins argument are present in your JIRA instances. These component versions will change as Connect development continues.

    You'll see a lot of output. When finished, your terminal notifies you that the build was successful:

    [INFO] [talledLocalContainer] Tomcat 7.x started on port [2990]
    [INFO] jira started successfully in 217s at http://localhost:2990/jira
    [INFO] Type Ctrl-D to shutdown gracefully
    [INFO] Type Ctrl-C to exit
  3. Navigate to http://localhost:2990/jira/.

  4. Sign in with admin for your username, and admin for your password.

Install your add-on in JIRA

Now you're ready to install your add-on in your local instance of JIRA. In this step, you'll navigate to the Universal Plugin Manager (UPM) and add a link to your descriptor file.

When you install your add-on, JIRA retrieves and registers your atlassian-connect.json descriptor.

  1. From JIRA, choose Cog Menu > Add-ons from the top navigation menu.

    Note: If you see a message about base URL problems, choose System > General Configuration > Edit Configuration from the admin screen. Ensure your browser URL, base URL, and helloworld.html hostname match.

  2. Click Manage add-ons from the side menu.

  3. Click Upload add-on from the right side of the page.

  4. Insert http://localhost:8000/atlassian-connect.json.
    This URL should match the hosted location of your atlassian-connect.json descriptor file.

  5. Click Upload.
    JIRA displays the Installed and ready to go dialog when installation is complete.

  6. Click Close.

  7. Verify that your add-on appears in the list of User installed add-ons. For example, if you used Hello World for your add-on name, Hello World should appear in the list.

  8. Reload the page.

  9. Click Greeting in the application header.
    Your message appears on the page:

What's next?

So far, you've learned the basic architecture of a Connect add-on. The next step is to add some functionality and handle authentication.

You can add functionality using the Atlassian REST APIs. Authentication manages the handshake between your app and the Atlassian host application. You can also read about our security concepts for more information.

You can also try the next tutorial, where you can add a table of your projects to JIRA via the REST API and D3.js.

More resources

Example add-ons

We have a few sample applications you can reference. These example add-ons demonstrate authentication and many other patterns you can use to develop your own add-ons.

Tools to help you develop

We've written a few example frameworks to help you to get started. These tools help generate some of the plumbing required for your Connect add-on:

There are also a few unsupported Atlassian and community contributed tools:

Join the Connect community

Explore Connect topics on Atlassian Answers. We also encourage you to join our Connect mailing list.