Documentation

Connect Basics

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 your JIRA Cloud development environment, 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.

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

In this step you will 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": "https://<my-addon-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: "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
script

This element is comprised of 2 values pointing toward all.js, formatted as //HOSTNAME.atlassian.net/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.
  • CONTEXT: The application context for the application. Note that JIRA is the default context (when none is provided) and wiki is used for 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">
     <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>
    
Within your iframe, you will always need to 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 on this, check out the Cookbook

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, and use ngrok to make this available on the internet.

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: http://0.0.0.0:8000
  2. Confirm the files you created in steps 1 and 2 are served. Visit:
  3. Make this add-on available on the public internet via ngrok. To see how to do this read through the developing locally guide.

Get a JIRA development environment

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 test what you have written in JIRA. For instructions on how to do this, go to the Development Setup page.

You will also need to ensure that your add-on can be reached by JIRA (i.e. hosted on the web). For an easy way to do this on your local machine, follow the instructions on Developing locally.

Install your add-on in JIRA

Now you're ready to install your add-on in your development version 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.

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

  3. Click Upload add-on from the right side of the page. If you can't see this option, make sure you have enabled development mode.

  4. Insert a link to your add-on descriptor, hosted somewhere on the internet via https.
    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 Hello World 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.

Join the Connect community

Explore Connect topics on the Atlassian Developer Community.