Migrating Confluence Cloud Whiteboards

Whiteboard migration can be enabled in the WikiTraccs settings:

This will export Confluence whiteboards as image to SharePoint.

It’s a Gray Setting which means it might not be fully supported by a vendor.

Whiteboard Export is Not Supported by Atlassian

Let’s get that out of the way. Exporting whiteboards in a programmatic, automated manner is not possible at the moment.

The only way to export a whiteboard as image is to click the right buttons in the browser.

Here is one of the many whiteboard-related issues in the Atlassian Jira: Ability to export/import whiteboards (CONFCLOUF-76634). Please vote.

So…

How Does WikiTraccs Export Whiteboards?

WikiTraccs can export whiteboards as images.

It does it exactly like any user would do: by clicking the right buttons.

That means, WikiTraccs knows how the current Confluence Cloud user interface looks, how to find the right buttons, and how to click them, to start the image export.

After clicking the export button, it grabs the exported image from the download folder and that’s it.

Sounds rickety? It kind of is.

The export works, as long as the user interface does not change.

It can break if Atlassian changes the user interface of Confluence Cloud.

This video shows how it looks like, when WikiTraccs exports a whiteboard (32 seconds):

The following happens in this video:

• WikiTraccs discoveres a whiteboard to migrate
• WikiTraccs opens a remote-controlled browser and navigates to the whiteboard (note: I had to move the browser window over from the second monitor)
• WikiTraccs clicks all the right buttons to export the whiteboard
• Chrome saves the downloaded image as Whiteboard.png
• WikiTraccs migrates Whiteboard.png to SharePoint, as page attachment

Everything that happens inside the browser is done by WikiTraccs, there was no user interaction (apart from moving the browser into view).

The resulting SharePoint page shows the exported image:

(Note: the whiteboard image can be huge, depending on the size of the original whiteboard. Clicking the image in SharePoint will expand it. It can also be downloaded to view it in full size.)

What Could Go Wrong?

As long as Atlassian doesn’t change the Confluence Cloud UI in a way that changes the buttons needed for the export, the process is pretty stable (although quite slow). So far, it broke about once in three months.

What sometimes happens is that remote-controlling the Chrome browser window fails for some reason. Might be a Chrome update, might be some Windows shenanigans. If that is the case, close WikiTraccs and all browser windows and restart the migration.

What sometimes happens is that Atlassian is showing some advertisement for a new feature in the browser. Often, this ad is an overlay that is being shown until you manually dismiss it by clicking the X or Cancel. This might interfer with the export.

If there is an overlay or dialog being shown that blocks the export, simply close it. The whiteboard migration might continue, but restarting might be necessary as well.

If the export breaks, WikiTraccs probably will require an update.

Under the Hood

To find the right button to click in the Confluence Cloud user interface, WikiTraccs uses CSS and XPath selectors.

You find those in a TOML file that is located at WikiTraccs.Console\Templates\BrowserAutomation\export-whiteboard.toml.

It contains selectors like this one:

[selectors.three-dot-menu]
description = "Three-dot menu in the upper right corner of a page"
language = "css"
query = "#more-actions-trigger"

This selector describes how to find the three dot menu button for a Confluence page.

There is a chance that, if whiteboard export breaks due to user interface changes, adjusting those selectors can fix the issue.

This approach to user interface automation is often used when programmatically testing user interfaces of web applications. WikiTraccs makes use of that approach to export whiteboards.

Authentication

Since WikiTraccs needs to open the whiteboard in the browser, this approach only works with Interactive Login where an account is logged in to Confluence to look at the whiteboard. It won’t work with Personal Access Tokens.

Wrap

In this blog post we looked at the current state of whiteboard exportability in Confluence Cloud, at how WikiTraccs does it and how it could break.

We all agree that this is a temporary solution and we hope that Atlassian provides an official export API in the near future (although I personally don’t believe that).

• ←Previous
Next→