Andra Dinu
30th April, 2020
Confluence
Use a Confluence labels system to keep content under control
Creating content in Confluence is easy. Managing it, especially in large volumes for large numbers of users? Tricky, but ScriptRunner can help.
Any Confluence admin will tell you that while creating content in Confluence is easy, managing it — especially in mature instances with hundreds of thousands of pages and thousands of users — can be very difficult.
As you scale to meet growing business needs, the tried-and-tested tips in this post will help you better structure content on your pages and spaces, using Confluence's native features, and some more advanced tricks you can do with ScriptRunner for Confluence.
Keep labelling consistent across your Confluence instance
Confluence can quickly become a jungle where you end up wasting hours looking for the page you need, and a quick way for making content easier to group and find is by adding labels to pages and attachments. Having all pages labelled makes it a lot easier to find content later, simply by filtering search results based on the label.
However, the trick for efficient label usage is to make sure that all team members follow the same conventions when creating labels. Without a document labelling convention that is clearly communicated to all users, you will end up with a chaos of similar-but-not-identical labels that will do more harm than good:
3 things to keep in mind about Confluence labels:
- Confluence labels are case-sensitive. ‘Content’ and ‘content’ will be 2 different labels in Confluence, so if you decide to use lower-cases in your instance, make sure everybody knows.
- Take note of regional spelling differences. This is particularly relevant when you have distributed teams across the world. For example, colleagues in the UK would use ‘programme’ whereas colleagues in the US would use ‘program’.
- Have a policy for compound words. Confluence only supports single word labels, so if you need to create compound words you will need to decide on how to separate them. If you go with hyphens, stick to hyphens; otherwise, ‘support_team’ and ‘support-team’ will be 2 different labels.
Beyond labels specific to each team and space, it is a good idea to create a series of very generic labels like ‘video’ or ‘release_notes’, in case you, as a global or space admin, need to quickly list all pages that have videos on them, or all pages that are release notes.
Highlight organised content with the ‘Content by Label’ Macro
Having a consistent labelling system goes a long way towards sorting the Confluence chaos, but you can do so much more.
Confluence offers a way to collect related pages together and display them according to your criteria. Just remember that labels are useful for creating lists of pages that appear in different sections of your space or in different spaces altogether. You can use the Content by Label macro to display lists of pages, blog posts or attachments that have particular labels. In the example below, we used this macro to present a list of page links to all proposals created by the App teams in 2019.
Use CQL to display info based on complex label combinations
You have seen how ‘Content by Label’ displays all content that has a particular label. However, if these pages were labelled with ‘proposal’ but also had other labels associated with them, such as ‘2018’, ‘2019’ and you only wanted to see those proposals submitted in 2019, this macro cannot filter based on the combination of ‘proposal’ AND ‘2019’. It will simply display all content labelled ‘proposal’, regardless of the year.
If you’re a ScriptRunner for Confluence user, you can use the Custom CQL Macro to display search results based on complex CQL searches. For the example above, you would use a simple search inside the Custom CQL Macro:
The results would be displayed on the page like this:
Help your users know which labels to use
A clear labelling system that is understood and applied consistently by every team is the key to long term content management success. While the labelling system is something which needs to be agreed internally within the various teams, as a Confluence admin you can help your users choose the right labels when they are creating new pages.
The Choose Label Macro in ScriptRunner displays a set of predefined label suggestions for users to pick from, based on the content of the page. You can include the choose label macro on a template, so when your users are creating a page from that template, they can quickly choose the relevant label, in its proper format/spelling, which keeps things properly organised!
Save precious admin time by managing labels in bulk
Having loads of pages mislabelled or not labelled at all can make it very hard to organise things, especially in the initial stages of a cleanup/structuring operation. ScriptRunner offers a series of easy-to use tools that allow you to perform bulk actions such as adding, removing or renaming labels or pages in bulk, which will save you a lot of time on initial cleanup/structuring operations.
You can even give access to some of these ScriptRunner functions to your space admins.
Explore what you can achieve with a 30-day free trial
ScriptRunner for Confluence is an amazingly versatile tool that lets you customise, extend and automate Confluence as much as you need.