Rate this page:
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:
Forge is our recommended platform for building Atlassian cloud apps. See the cloud development platform overview for a comparison between Forge and Connect.
To complete this tutorial, you'll need a basic understanding of Confluence and the following:
The Cloud Developer Bundle provides a free Atlassian cloud development site for building and testing apps. To create your site:
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.
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.
After the page refreshes, you'll see the Upload app link. This link enables you to install apps while you're developing them.
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.
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
Install atlas-connect
by running:
1 2npm install -g atlas-connect
Verify the installation by running:
1 2atlas-connect --help
If ACE installed successfully, you'll see the following:
1 2Usage: 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
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 2git clone https://bitbucket.org/atlassian/confluence-helloworld-addon.git
Now that we have the source code, we're ready to get to work:
Switch to the app directory:
1 2cd confluence-helloworld-addon
Install dependencies for the app using npm:
1 2npm install
Add a credentials.json file in your app directory with your information:
1 2{ "hosts" : { "<your-confluence-domain>": { "product" : "confluence", "username" : "<user@example.com>", "password" : "<api_token>" } } }
Start the server:
1 2npm 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.
Now that the sample app is installed, let's see the macro in action:
Edit any page, and type /hello (or {hello):
Select Hello World Macro, and save the page. You should see the following content:
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.
Rate this page: