Classification in Confluence… done right.

TL;DR

We did a thing and built a classification app for Confluence that runs with minimal rights. This means the app cannot access the contents of the page itself, ever. We’ve made it available for free in the Atlassian Marketplace.

The why

We all feel the need to classify information at some point. Every business has sensitive information that needs to be labelled as such — even in small businesses like ours. It does not matter if you run a software development company, a marketing business or if you are a government entity. And especially in the Atlassian suite, which boasts that 83% of the Fortune 500 companies use Atlassian products, in over 190 countries. Every organization has a company policy that they must adhere to, whether the reason is to remain certified and/or to streamline and protect internal communications.

Now, there are multiple classification apps available in the Atlassian Marketplace, which we sampled before we decided to write our own. Why that decision?

Because all the classification apps that we sampled required excessive rights to the information that we wanted to classify. Every app wanted access to the full body of the page, thus making sensitive information available to the app developer. This is counterintuitive. The app developer should not require to access the information itself, right?

So, what we did was develop a classification app that runs with the minimal rights needed to adjust the page classification. See the page Confluence Product Scopes for more information or continue reading. Let’s dive into the technical stuff!

The how

This section focuses on the technical side of the classification app. If, like us, you don’t trust apps from other developers (even though we are of course super trustworthy), you can develop your own version of this app by copying ours using the steps below.

We built the app using the Forge platform for Atlassian’s cloud products:

Forge makes it possible to build a fully-functional app in just a few hours, with hosting, multiple development environments, and API authentication built-in. Forge can be used to build custom apps and integrations or apps distributed through the Atlassian Marketplace.

The requisites you need to get started:

• The Forge CLI
• An Atlassian API token
• Our (open) source code
• A Basic understanding of ReactJS

What it does

What the app does is simple: it lets you create custom labels for a dropdown after which you can assign a single label from the dropdown to the page. The custom labels (and the active label you set) are saved in the properties of your Confluence’s global namespace.

Note: After you selected a label from the dropdown and clicked ‘Save’, you have to click anywhere outside of the popup to hide it after which the page label will update a second later.

Made a typo while creating your custom labels? No worries! You can ‘clear saved labels’ and start over.

Necessary permissions

The other classification apps we tested asked for A LOT of permissions (looking at you, Bertly). Some even requested to become an administrator of our organization.

Our app is different. It only requires access to the page properties since that’s where we save the custom labels and the classification status. We don’t need any access on the contents of the Confluence page!

After installing our app from the Atlassian Marketplace but before you can use it, it will ask you for the necessary permissions. As you can see in the screenshots below, the only scopes this app needs are:

• Read content properties; and
• Write content properties.

As you can see, our domain chapter8.com is also mentioned in the permissions confirmation. This is because we fetch an app icon (SVG image) from an external source: our website. This image is displayed on your Confluence page as shown in the example image.

If you want to use your own image, change these lines or the source code accordingly:

• manifest.yml#L24
• src/index.jsx#L103

The where

You can find our classification app for Confluence in the Atlassian Marketplace.

Any questions? Feel free to reach out!