Getting started with Connect

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

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

• setting up a cloud development site
• installing Atlassian Connect Express (ACE), a Node.js toolkit for building Atlassian Connect apps
• validating your setup by deploying a basic hello world app

Before you begin

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

• IDE or text editor
• Node.js version 12.1.0 or later
• npm (bundled with Node.js)
• Git

Step 1: Prepare for tunneling

In order to be able install an app from your local development machine into Jira or Confluence Cloud, there needs to be a way for the Cloud installation to connect to your computer. This can be done by using a tunnel. ngrok is a service that enables HTTP tunnels and can be used free of charge after creating an account. The ngrok Node.js module is already part of ACE and allows for a quick setup. In order to use ngrok, an auth token is required. Follow this process to obtain one:

1. Create a new ngrok account
2. Click on "Your Authtoken"
3. Copy your personal token value (you'll need this later)

Step 2: Cloud development site

The Cloud Developer Bundle provides a free Atlassian cloud development site for building and testing apps. To create your site:

1. Go to go.atlassian.com/cloud-dev and sign up. It may take 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 the Jira products installed. Note that Atlassian cloud development sites have limits on the number of users.

Step 3: Enable development mode in your site

With development mode you can install app descriptors in your development site from any public URL. This means you don't need to list an app in the Atlassian Marketplace before installing it.

1. In the top navigation bar, click Apps then Manage your apps. If Apps isn't visible, click More first.
2. Under User-installed apps, click Settings.
3. Select Enable development mode, and then click Apply.

After the page refreshes, you'll see the Upload app link. This link enables you to install apps while you're developing them.

Step 4: Install ACE

Atlassian Connect Express (ACE) is a Node.js toolkit for building Atlassian Connect apps. It uses 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 installed correctly (the version numbers returned may vary):

   1
   2
   $ node -v
   v12.12.0
   $ npm -v
   6.11.3
   

2. Install atlas-connect by running:

   1
   2
   npm install -g atlas-connect
   

3. Verify the installation by running:

   1
   2
   atlas-connect --help
   

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

1
2
 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

Step 5: Create a basic app

Now, we're ready to create a basic app. The app is a macro that prints Hello World on Confluence pages.

First, we'll clone a repository that contains the source code for the Hello World app:

1
2
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
   2
   cd confluence-helloworld-addon
   

2. Install dependencies for the app using npm:

   1
   2
   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 (for example, https://your-domain.atlassian.net).
   • username: Use the email address of your Atlassian account.
   • password: Specify the API token.

     1
     2
     {
       "hosts": {
         "<your-confluence-domain>": {
           "product": "confluence",
           "username": "<user@example.com>",
           "password": "<api_token>"
         }
       }
     }
     

4. Use the ngrok tunnel

• Identify to ngrok using your auth token (from the step "Prepare for tunneling"):

  1
  2
  ./node_modules/.bin/ngrok authtoken <value of your token>
  

• Important: for any recently created ngrok account there will be a warning page displayed that needs to be confirmed once before the tunnel can be used. To do this, look for the message Local tunnel established at https://<some ID>.ngrok-free.app/ and open that URL in your browser. You'll see a page like this:
• Confirm by clicking on the button labeled "Visit Site". Your tunnel is now fully operational.

1. Start the server:

1
2
npm start

You should see something similar to the following:

1
2
> helloworld-app@0.0.1 start /Users/user/repos/confluence-helloworld-addon
> node app.js

Watching atlassian-connect.json for changes
Add-on server running at http://<your-local-machine>:<port>
Executing (default): CREATE TABLE IF NOT EXISTS `AddonSettings` (`id` INTEGER PRIMARY KEY AUTOINCREMENT, `clientKey` VARCHAR(255), `key` VARCHAR(255), `val` JSON); {
  plain: false,
  raw: true,
  logging: [Function],
  timestamps: false,
  validate: {},
  freezeTableName: false,
  underscored: false,
  paranoid: false,
  rejectOnEmpty: false,
  whereCollection: null,
  schema: null,
  schemaDelimiter: '',
  defaultScope: {},
  scopes: {},
  indexes: [
    {
      fields: [Array],
      type: '',
      parser: null,
      name: 'addon_settings_client_key_key'
    }
  ],
  name: { plural: 'AddonSettings', singular: 'AddonSetting' },

  ...

}
GET /macro?xdm_e=https%3A%2F%2F<your-confluence-domain>&xdm_c=channel-confluence-helloworld-addon__helloworld-macro5506103820156894572&cp=%2Fwiki&xdm_ deprecated_addon_key_do_not_use=confluence-helloworld-addon&lic=none&cv=1.472.0&jwt=<token>
GET /css/81ea9e595fa00bf1f5f0cf9afe2a37e1-addon.css 200 3.242 ms - 277
GET /js/69447ddc6badcb86e100e45c08d3f8b2-addon.js 200 2.649 ms - 19

Starting the service causes the app to be installed in the Confluence instance described in the credentials.json file.

Step 5: Test your app

Now that the sample app is installed, let's see the macro in action:

1. Edit any page, and type /hello (or {hello):

   

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

   

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.