A guide to versioning controlled documents in Confluence

Written by Rina Nir

Versioning controlled documents in Confluence
This is an updated version of the post: “Versioning controlled documents in Confluence” which proposes solutions both for Cloud, Server and Data Center Confluence instances.

Versioning controlled documents with Confluence

Confluence comes with built-in tools for versioning controlled documents. Each time you modify a document and save it, it adds a new version to the history. This version is automatically tagged with a version number, starting at v.1, then progressing through v.2, v.3, etc.

This innate versioning mechanism provides a host of features:

  • The document history is easily accessible through the tools menu on every page. This provides details such as which users made each change and its modifications.
  • Each time they save the document, users have the opportunity to add comments summarising the changes they’ve made. These will appear together with the history.
  • Each previous version is still accessible, and it’s possible to compare any two historic versions.

Let’s call this version saved with Confluence’s own versioning mechanism the ‘internal version’ of a document.



How does this apply to controlled documents?

In the case of controlled documents, a new version of the document usually means a new approved and finalised version. Let’s call this the ‘official version’.

In between two official versions there are typically a few internal versions of a document, brought about by authoring and review iterations.

How you register and maintain the official version of controlled documents is one of the essential decisions you should make before making the switch to Confluence. I’ve seen several methods implemented in different organisations, ranging from simple to complex.

  • You could stick with version number 1, 2, 3.
  • Or you could apply multilevel numbering similar to software releases: 1.1, 1.2 to 2.0, etc.

There’s no right or wrong approach, and the best method for you will be unique to your organisation. You will need to find a way to name and manage these official versions of a page. Here are a couple of options for implementing official version numbering that you might like to consider:

Option #1: Using Page Properties (Applicable for Cloud, Server and Data Center versions of Confluence)

Page Properties is a built-in feature of Confluence. It allows you to add your own properties to Confluence pages. You can add a property called ‘Version’ and update the value of this property for each new official release.

Add this property to each of your controlled pages wherever you choose – typically right at the top of the page. You can use the same mechanism to set other properties, such as the document number, department and product, in a single table. Making this metadata part of your page template is the best way to ensure that everyone uses it consistently across all controlled documents.

If you then want to export a document to Word or PDF, we always recommend using K15t’s Scroll Exporter apps, rather than the native Confluence export facility. This will enable you to easily incorporate your Page Properties information into the header or footer of the exported document.


  • It’s easy to implement, using built-in Confluence functionality
  • It’s easy to use.
  • The version information is accessible for reports through the Page Properties mechanism.
  • The Page Properties table can be located anywhere on a document.
  • Using Scroll Exporter apps makes it possible to view the metadata whilst the document is exported to Word or PDF.


  • Each author or editor is responsible for manually inputting or updating the version number. This may lead to errors, such as inputting the wrong version value or failing to update it to a new publication.
    However, that is more likely to be a problem in larger organisations where many authors participate in releasing documents, making it more difficult to enforce uniformity.
  • Works “as expected” with Confluences’ page history: when viewing older versions of the page, the property will show its value as it was at the time of the old version.

Option #2: Using Comala Workflows app (Applicable to Confluence Server and Data Server)

You can avoid the manual inputting of the version number required by Option #1 by using the Comala Workflows app. Workflows can automate the process of page release and updating the page version. As long as the version numbers increase in straightforward consecutive order – 1, 2, 3, etc – it’s possible to adjust the script to automate the process using this technique. If you’re looking for more guidance on using Comala Workflows app to manage your controlled documents, you can check out our article on the topic.

The solution relies on a workflow accessing and manipulating Page Metadata information. This Comala documentation explains in detail in the Comala documentation here.


  • Offers all the advantages of option #1.
  • It also enables automated version numbering.


  • It requires a Comala Workflows license and the implementation of a Comala Workflows release process (this is not a downside if you need to implement it anyway) and the cost of yet another App.
  • It requires one more app: the Comala Metadata App. Note that this App is very handy and a useful addition in your Confluence toolbox – so you might already have it anyways.

Option #3: Using The Scroll Versions App (Applicable to Confluence Server and Data Server)

The Scroll Versions app is a good solution for when you need to manage your versions on a space-wide level – for example, if you collaborate on a technical manual with your team. If your manual is a large piece of content, you can manage it as a space which comprises only this manual: for example, each page is a section in the manual.

Scroll Versions can’t help with managing the version of each and every Work Instruction. If you want to publish new versions of it without applying a version change on your complete QMS, you may still find it a valuable addition to your Confluence. I recommend this for the specific situations which require a Space wide version management in mind.


Blog posts in this series:

  1. Why the Controlled Document Lifecycle Matters
  2. Using Comala Workflows for Approval of Controlled Documents
  3. Sick of Repeating Yourself? Try Engineering Your Procedures in Confluence

Have an idea for your Quality Management System?

We’d love to learn more about your project.

Let’s have a chat