Last updated Jul 10, 2018
Improve this page

Getting started

This tutorial will teach you the basics of developing apps for Confluence Cloud using Atlassian Connect. The Atlassian Connect framework handles discovery, installation, authentication, and seamless integration into the Confluence user interface.

By the end of this tutorial, you’ll have everything you need to start developing apps, including:

  • setting up a cloud development site
  • validating your setup by deploying a basic app

Before you begin

To complete this tutorial, you’ll need a basic understanding of Confluence and the following:

Cloud development site

We’ll start by getting a free Confluence Cloud development site that you can use for building and testing apps.

  1. Go to go.atlassian.com/cloud-dev to sign up. It takes several minutes to provision your site.
  2. Once your site is ready, sign in, and complete the setup wizard.

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

Enable development mode

Development mode allows you to install app descriptors from any public URL in your development site. This means that you do not need to list the app in the Atlassian Marketplace before installing it.

  1. In the left-hand navigation menu, click Settings. settings
  2. Scroll to the Atlassian Marketplace section, and then click Manage add-ons. settings
  3. Under User-installed add-ons, click Settings.
  4. Select Enable development mode, and then click Apply. settings

After the page refreshes, you’ll see the Upload add-on link. This allows you to install apps while you’re developing them.

Confluence Cloud has a new look and feel, including updated navigation. Learn more about the recent changes.

Install ACE

ACE is a Node.js toolkit for building Atlassian Connect apps. As the name suggests, it utilizes the Node.js Express framework, allowing you to leverage routing, middleware, and templating within a Node.js environment.

  1. Verify that you have Node.js and npm set up correctly (the version numbers returned may vary):

    1
2
3
4
    $ node -v
v5.5.0
$ npm -v
3.5.3

  2. Install atlas-connect by running :

    1
    npm install -g atlas-connect

  3. Verify the installation by running:

    1
    atlas-connect --help

If ACE installed successfully, you’ll see the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
 Usage: atlas-connect [options] [command]


 Commands:

  new [name]  create a new Atlassian app
  help [cmd]  display help for [cmd]

 Options:

  -h, --help     output usage information
  -V, --version  output the version number

Create a basic app

Now, we’re ready to create your first app. The app is a simple macro
that prints Hello World on Confluence pages.

Now we’ll clone a repository that contains the source code for the Hello World app.

1
git clone https://bitbucket.org/atlassian/confluence-helloworld-addon.git

Now that we have the source code, we’re ready to get to work:

  1. Switch to the app directory:

    1
    cd confluence-helloworld-addon

  2. Install dependencies for the app using npm:

    1
    npm install

  3. Add a credentials.json file in your app directory with your information:

    • your-confluence-domain: Use the domain of your cloud development site (e.g., your-domain.atlassian.net).
    • username: Use the email address of your Atlassian account.
    • password: Specify the API token
    1
2
3
4
5
6
7
8
9
    {
    "hosts" : {
        "<your-domain>": {
            "product" : "confluence",
            "username" : "<user@example.com>",
            "password" : "<api_token>"
        }
    }
}

  4. Start the server:

    1
    npm start

    You should see something similar to the following:

     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
    npm start

> helloworld-addon@0.0.1 start /home/ubuntu/workspace/confluence-helloworld-addon
> node app.js

Watching atlassian-connect.json for changes
Initialized memory storage adapter
Add-on server running at http://<your-machine-name>:8080
Local tunnel established at https://<example>.ngrok.io/
Check http://127.0.0.1:4040 for tunnel status
Registering add-on...
GET /atlassian-connect.json 200 11.418 ms - 633
Saved tenant details for <example> to database
{ key: 'confluence-helloworld-addon',
  clientKey: 'example',
  publicKey: 'example',
  sharedSecret: 'example',
  serverVersion: 'example',
  pluginsVersion: '1.3.19',
  baseUrl: 'https://<your-cloud-dev-site>.net/wiki',
  productType: 'confluence',
  description: 'Atlassian Confluence at https://<your-cloud-dev-site>.net/wiki ',
  eventType: 'installed' }
POST /installed?user_key=example 204 49.872 ms - -
Registered with host at https://<your-cloud-dev-site>.net/wiki

Test your app

Awesome! You’ve just installed your first sample app. Let’s see it in action:

  1. Edit any page, and type {hello:

    type {hello

  2. Select Hello World Macro, and save the page. You should see the following content:

    hello world macro

Next steps

Now that you have set up your cloud development site, you’re ready to get started building apps. Check out the other tutorials, or take a look at the REST API docs.