How to create and setup Confluence Plugin
There is a possibility to create an app for Atlassian that will integrate and interact with Confluence Cloud’s user interface. To achieve that, developers should use the Atlassian Connect framework. Below you can find the basics that will give you a head start with Atlassian plugins.
Technologies that you need to know/have before starting:
The most popular way to create an app is to build a simple Node + Express app. To do so, you’ll need:
- Node.js (at least 4.5v)
- NPM
- Git
- IDE
Please note that this is just one of the possibilities. Atlassian provides frameworks for various languages, so you are not limited to Node.
Other frameworks are available for:
- Java
- Scala
- PHP
- Dart
- Haskell
Getting started
For development/testing purposes, Atlassian recommends using the free Confluence Cloud development site (with limited users amount). You can create one here: go.atlassian.com/cloud-dev
After installation, enter your freshly-created site, go to the settings, then find the “Atlassian Marketplace” section, and click the “Manage apps” button. A popup will show up allowing you to enable development mode.
This way you can install apps developed by you.
Installing sample app to test functionalities
Setting up an example app is really easy. You only need to clone one git repository, install all dependencies and fill credentials.json with your valid informations & credentials.
The information you need to provide inside credentials.json includes:
- confluence domain
- username
- password
Username is your Atlassian account and password is an API Token. How to generate one?
- Go to https://id.atlassian.com/manage/api-tokens
- Click create API token
- Select a label that suits your purpose
- Copy it to clipboard
For a complete step-by-step guide and repository address of the example app, visit this link:
https://developer.atlassian.com/cloud/confluence/getting-started/
Example app is a macro plugin that, by default, replaces defined words sequence into another one. By default, if you’ll write /hello it will change into “Hello Word”.
App descriptor
It’s a JSON file that is the most important part of our app configuration. General info about our plugin and modules that we want to use can be found there. When someone installs your app, the descriptor is being attached in the background to point directly to your service.
A comprehensive documentation for creating a valid descriptor can be found here: https://developer.atlassian.com/cloud/confluence/app-descriptor/
Modules
To find modules that can be pointed in the descriptor, use this page:
https://developer.atlassian.com/cloud/confluence/modules/admin-page/
Security of an app
To authenticate apps, JWT (JSON Web Token) is used. It’s built into supported libraries that can be found here: https://developer.atlassian.com/cloud/jira/platform/frameworks-and-tools/
For API requests they allow to use 3 types of authorization:
- basic by predefined credentials (not recommended)
- Atlassian Connect JWT
- Atlassian Connect OAuth JWT exchange
To read more about the last one, visit: https://developer.atlassian.com/cloud/confluence/oauth-2-jwt-bearer-tokens-for-apps/
Webhooks for Confluence Cloud
Webhooks are used to get notified about specific events via HTTP callbacks. You can register webhooks in the descriptor file.
It gives a lot of possibilities for monitoring user actions around the Confluence. Here are a few examples:
- Blog/content/page/space has been added/removed/restored/edited
- Comment has been created/removed/updated
- Page has been viewed
- User gets followed
And many, many others. Full list of available webhooks is available here: https://developer.atlassian.com/cloud/confluence/modules/webhook/
Additional help to understand API
Atlassian created the Connect Cookbook that guides you around API requests, recommended requests handling etc.
The whole documentation is available here: https://developer.atlassian.com/cloud/confluence/connect-cookbook/
If you’re looking for API examples, they are provided here:
https://developer.atlassian.com/cloud/confluence/rest-api-examples/
