Getting started with Connect

This tutorial will teach you the basics of developing apps for Confluence Cloud using Connect. TheConnect framework handles discovery, installation, authentication, and seamless integration into theConfluence 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
• installingAtlassian 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 this tutorial, the app server will run on your local development machine. A tunneltunnel is necessary to allow Jira or Confluence Cloud to send requests to the server running on your machine and install the app. ACE creates tunnels using thengrok Node.js module, which can be used free of charge after creating anngrok account. In order to use ngrok in ACE, an auth token is all that's required. Follow this process to obtain one:

1. Create a new ngrok account
2. Obtain an 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 testingapps. To create your site:

1. Go togo.atlassian.com/cloud-dev and sign up. It may takeseveral 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 thatAtlassian 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, clickApps thenManage your apps. IfApps isn't visible,clickMore first.
2. UnderUser-installed apps, clickSettings.
3. SelectEnable development mode, and then clickApply.

After the page refreshes, you'll see theUpload app link. This link enables you to install appswhile 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):

   12
   $ node -vv12.12.0$ npm -v6.11.3

2. Installatlas-connect by running:

   12
   npm install -g atlas-connect

3. Verify the installation by running:

   12
   atlas-connect --help

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

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

Step 5: Create a basic app

Now, we're ready to create a basic app using ACE. The app is ageneral page, accessible in theApps drop-down menu in Confluence's top navigation, that displays aHello World message.

1. Create a new app using ACE. ThegeneralPages module is added by default:

   12
   atlas-connect new confluence-helloworld-addon

2. Switch to the app directory:

   12
   cd confluence-helloworld-addon

3. Install dependencies for the app using npm:

   12
   npm install

4. Add acredentials.json file in your app directory with your information:
   • your-confluence-base-url: Use the scheme and domain of your cloud development site (for example,https://your-domain.atlassian.net).
   • username: Use the email address of yourAtlassian account.
   • password: Specify theAPI token.

     12
     {  "hosts": {    "<your-confluence-base-url>": {      "product": "confluence",      "username": "<user@example.com>",      "password": "<api_token>"    }  },  "ngrok": {     "authtoken": "your-ngrok-token"  }}

5. Start the server:

   12
   npm start

You should see something similar to the following at the bottom of the app logs:

12
POST /installed 204 186.061 ms - -Registered with host at <your-confluence-base-url>/wiki

Starting the service causes the app to be installed in the Confluence instance describedin thecredentials.json file.

Step 6: Test your app

Now that the sample app is installed, let's see the app in action. Navigate to your Confluence instance and click on 'Hello World' under Apps. You should be greeted with the following page:

Next steps

Now that you have set up your cloud development site, you're ready to get started building apps. Check outthis guide to learn more about thegeneralPages module, which was used in this tutorial. To explore all Connect has to offer, check out ourother tutorials, or take a look at theREST API docs.