Confluence comes with built-in document version management. Each time a document is modified then saved, a new version is added to the history and automatically tagged with a version number, starting at v.1, then progress 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, providing details such as the user who made each change and the time it was modified.
- 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 consecutive official versions there would typically be quite a few internal versions, reflecting several authoring and review iterations that occur before it’s approved.
The naming convention for official versions will depend on an organisation’s preference. Some stick with 1, 2, 3. Others apply multilevel numbering, inspired by software releases. In this case whether the version number will increase from 1.2 to 1.3 or 2.0 might depend on the nature of the modifications or other factors.
How to register and maintain the official version of controlled documents is one of the essential decisions to make before making the switch to Confluence. I’ve seen several methods implemented in different organisations, ranging from simple to complex.
There’s no right or wrong approach, and what will work best for your organisation will depend on your specific circumstances. However here are three options for implementing official version numbering that you might like to consider:
Option #1: Using Metadata Plugin
Metadata Plugin is a free plugin for Confluence, which is one of those ‘must install’ plugins for any Confluence installation. As its name suggests, it makes it possible to add metadata to documents. You can add a metadata field called ‘Version’ and update the value for each new official release.
This metadata will become part of each page, and will be displayed wherever you choose – typically right at the top of the page. You can use the same mechanism to bring together other metadata, such as the document number, department and product, in a single table. Making this metadata part of your template is the best way to ensure that everyone uses it consistently across all controlled documents.
The metadata can then be pulled into reports. Metadata Plugin comes with its own reporting feature, however it’s also possible to use various other plugins to provide additional metadata reporting facilities.
If you then want to export a document to Word or PDF, we always recommend using K15t’s Scroll Exporter plugins, rather than the native Confluence export facility. This will enable you to easily incorporate your metadata information into the header or footer of the exported document.
Pros:
- It’s easy to implement, with a single free plugin and the addition of a table to your controlled document template.
- It’s easy to use.
- The version information is accessible for reports through the metadata mechanism.
- Metadata Plugin is available free through the Atlassian Marketplace and is compatible with other reporting plugins.
- Your organisation is free to choose the most appropriate naming convention.
- The metadata table can be located anywhere on a document.
- Using Scroll Exporter plugins makes it possible to keep the metadata showing when the document is exported to Word or PDF.
Cons:
- 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 when a new official version is published.
That is likely to be more of a problem in larger organisations where many authors are involved in releasing documents, making it more difficult to enforce uniformity.
Option #2: Using Comala Workflows plugin
The down side of option #1 can be avoided by using the Comala Workflows plugin to automate the page release process.
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.
The solution relies on a workflow accessing and manipulating the metadata. Unfortunately the scripting language doesn’t support mathematical operations directly, so modifying the script to increase the version number requires a creative approach.
Here’s an example, using notation based on Workflow Supplier:
Step 1: Initiating two metadata values when a page is created
officialVersionCount uses a string of a particular symbol, eg ‘+’, to represent the number of released versions.
recentOfficialVersion is the name of the last version released.
When a document is first initiated these strings will be empty, as no version has been released yet.
{comment}
**** Initializing the two metadata values (to null) upon creation of the page.
{comment}
{trigger:statechanged|state=draft|initial=true}
{set-metadata:officialVersionCount}{set-metadata}
{set-metadata:recentOfficialVersion}{set-metadata}
{trigger}
Step 2: Updating the metadata values related to the version when it’s released
The length of the officialVersionCount is extended by a single character, eg ‘+’.
recentOfficialVersion is set to reflect the size of officialVersionCount.
{comment}
**** Once the page is approved, update metadata information
{comment}
{trigger:statechanged|state=Approved and pending training}
{set-metadata:officialVersionCount}@officialVersionCount@+{set-metadata}
{set-metadata:recentOfficialVersion}@workflow:metadata > officialVersionCount > size@{set-metadata}
{trigger}
Pros:
- Offers all the advantages of option #1.
- It also enables automated version numbering.
Cons:
- It requires implementation of a Comala Workflows release process, this is not a downside if you need to implement it anyway.
- There are limitations in business logic and numbering convention.
In theory this method could be extended to support multilevel numbering, however, in that case it would be more straightforward to use Option #3.
Option #3: Using a listener
This technique is more complex to implement but makes it possible to automate more complex official version numbering.
This approach assumes that there is an agreed convention (within the particular Confluence instance) of how a document is released. For example:
- A process is implemented, which includes a specific release stage (this may be achieved using Comala Workflows, but there are other options too).
- Special labelling (eg ‘released’) is added only to released documents, but not to drafts.
- A document is released by moving it to a different space.
We can use this convention to detect the release of a new official version and automatically update the metadata of the page with a new version number.
This type of plugin is called a ‘listener’ and requires programming. The actual code for the plugin will depend on the event you want to capture (in this case, the release event) and the version numbering structure you want to apply.
Pros:
- Offers all the advantages of options #1 and #2.
- It also makes it possible to automate more complex version numbering.
- You can implement this approach without using Comala Workflows.
Cons:
- It requires the development of a dedicated listener plugin.
Whatever your version numbering convention for controlled documents, we should be able to automate it for you as part of the process of moving to Confluence.