How Confluence API powers the release flow of a SaMD product

This is a real story about a SaMD company (Software as a Medical Device) that wanted to achieve high release cadence. They hired us to develop a custom Confluence extension that would remove a blockage from their release flow. We used the Confluence API to deliver a custom Confluence extension to solve their problem.

Powertags is a custom extension for Confluence Server and Data Center.

Each time the team shipped a new product release, they needed to link it to a collection of Confluence pages. Product description, risk management document, specifications, test results, traceability report, essential requirements checklist, and some more.?For each software release, we make an index page that links the release to the correct pages. The index page is like a checklist table. The first column lists the required document categories. The second column- links to the documents themselves.?The third column has metadata about each page: the official version number and the effectiveness date. With the index table it is easy to do regulatory submissions, pass audits, and find the document that you need.

But making the index table itself used to be very hard. Confluence is a great platform to author our?documents, and also to keep them organized. But it is a pain and almost impossible to create index tables in?Confluence. I mean, not if you have very frequent releases and your documents change. We avoid duplicating Confluence pages across releases. So, we have a single page for requirements specifications for each of our products, and we update the page as the product evolves.

The index table for a version needs to link to a page that relates to that version. Like the requirements document of that version. If we link to the page in the regular Confluence way, it will always link to the current version of the page. Yet, given our release cadence, that link will soon not link to the requirements applicable to that old release. It will link the requirements of the most recent release. Why? Because each time we update the requirements we create a new version of the same page, burying the old requirements in the page history. Also, filling up that third column with the page metadata information was taking ages. A lot of manual copy/paste with the inevitable errors it creates.

The Powertag extension for Confluence transformed index tables into a piece of cake.?

Powertags are like the supercharged version of Confluences’ native page labels. Unlike labels, a powertag sticks to a specific version of the page. Also, powertags have a hierarchy, which means they provide a complete taxonomy.?It’s great that the Confluence API allows us to extend Confluence in such a way!

How do Powertags solve our index pages agonies? First, with each update to a page, like the specification page, the author of the new version powertags it. If this version is for our SpaceMed product version 2.3, then it will get the powertag “product/spacemed/2.3”. Also, because it belongs to the specification section in the Medical Device Records (MDR) index, it will be powertagged with “MDR/specification”.

The beauty of it is that it’s the page author’s responsibility to powertag their page. This helps a lot because, at the time of authoring the page, the author knows exactly the product version it applies to. It’s in her context as she finalizes the page.

Moving forward to when it’s time to release the new version, we create the MDR index page for the new version using a Confluence blueprint. Blueprints are another extension point provided by the Confluence API. The layout of the checklist is part of the blueprint and the user needs only to specify the product version this index is for. The Powertag mechanism fills the checklist with the?

links to the related page versions. Sometimes some of the checklist items do not exist immediately when the MDR is first created. Either someone forgot to powertag, or a page was not updated. The Powertag MDR index table makes it easy to spot what’s missing and why. A nice example of good human-machine collaboration.

With Powertags, this is how we release a new version:

1. Once we start work on a new release we add it to the powertag taxonomy.
2. As we prepare documents for this version we assign powertags to them.
3. Whenever during the work on the new version, we create the new MDR index page for that release. As more documents are completed, the?MDR index table shows our progress.
4. We are likely to have missing items in the MDR table after we updated all pages that needed an update. The missing items are pages that do not need an update. For example, our product description page rarely changes, so we want to use the same page version as we used before. In those situations we need we add the new powertag to the existing page, and voila! Our MDR is complete and we can give a thumbs up to the release.

How Powertags are the supercharged version of Confluence labels

We bring here an explanation for the power users and the geeks.

Teams use labels in many situations in Confluence. Labels are recognised by Confluences search engines and help you categorise and search for pages. Labels are always linked to the current page version. Historic page versions have no labels and are never picked by Confluences’ search. But, under the hood, Confluences’ API does provide access to all historic page versions. Using these methods powertags are not assigned to pages, but rather to a page version. You can assign Powertags to historical versions and to current versions. Even when updating a page, the Powertags of the previous version remains associated with it.

The second difference is that powertags create a taxonomy because they are hierarchical. For the MDR index use case, two taxonomies are in play:

• The first captures the association with a product. These powertags associate pages with the product version. Like:
• Products
• Products/SpaceMed
• Products/SpaceMed/V1.0
• Products/SpaceMed/V2.0
• Products/Galaxy
• Products/Galaxy/V1.0
• Products/Galaxy/V1.2
• Products/Galaxy/V3.0
• The second captures the document type. This organizes the pages within the MDR checklist. The risk analysis page will land in the location allocated for risk analysis. Like:
• Medical Device Records (MDR)
• Medical Device Records (MDR)/Risk Analysis
• Medical Device Records (MDR)/Labeling
• etc.

Powertags administration

Powertagging a page version

The MDR Blueprint Leverages Powertags to Create Index Tables

The MDR Blueprint brings the solution home, right to the hand of a busy team member that pushes a release out of the door.?

A Confluence blueprint is a way of creating new pages with defined logic prebaked into them. ‘Meeting Notes’ and ‘Decisions’ are examples of blueprints. Using Confluence API, we added the MDR Blueprint to make MDR indexes easy to create.

Using a Blueprint to create the MDR index tables is saves precious time reduces errors and ensures all our index tables look the same. There is nothing that impresses auditors more than a consistent set of documents.

Create MDR table with Powertag blueprint

The Impact

Since its introduction in April 2022, the customer has shipped many releases, and all have their proper MDR index pages. The index pages are an easy part of the release flow and are never a cause for release delays.?

With the help of Confluence API and a smart design, Powertags removed the bottleneck from the release process.?

Do you have bottlenecks in your process? Contact us to check if a custom extension could help you resolve it.