PlantUML for Confluence (Avono)

We support migrating from Avono PlantUML for Confluence into Capable for Confluence or Diagrams for Confluence using our migration tool, which is currently in beta.

Introduction

If you're currently using Avono PlantUML for Confluence Data Center and looking to move to Confluence Cloud, you're in the right place.

Our migration tool is designed to help you bring your existing PlantUML diagrams over with minimal effort and zero headaches. This guide will walk you through the process step-by-step so you can move fast and preserve your team's visual documentation.

What is supported?

Currently only macros on Confluence Pages are supported, not Blog Posts.

Macros

Diagram Types

Notes

Some of the macros have options related to how they render the diagrams, like rounding, connector types, shape preferences and shadows - these are not supported.

We migrate:

• The diagram type

• The diagram code itself

• The diagram title (if provided)

Pre-CCMA Steps

1. Determine whether your source data is compatible

First, to find out what macros are in use, you can either open the ‘Macro Usage’ page in the Confluence Administration, or run this SQL query:

Query

WITH matches AS (
  SELECT 
    bodycontentid,
    unnest(ARRAY[
      CASE WHEN body ~* '<ac:structured-macro[^>]*ac:name="plantuml"' THEN 'plantuml' ELSE NULL END,
      CASE WHEN body ~* '<ac:structured-macro[^>]*ac:name="plantumlrender"' THEN 'plantumlrender' ELSE NULL END,
      CASE WHEN body ~* '<ac:structured-macro[^>]*ac:name="flowchart"' THEN 'flowchart' ELSE NULL END,
      CASE WHEN body ~* '<ac:structured-macro[^>]*ac:name="flowchartrender"' THEN 'flowchartrender' ELSE NULL END,
      CASE WHEN body ~* '<ac:structured-macro[^>]*ac:name="linkgraph"' THEN 'linkgraph' ELSE NULL END,
      CASE WHEN body ~* '<ac:structured-macro[^>]*ac:name="spacegraph"' THEN 'spacegraph' ELSE NULL END
    ]) AS macro_type
  FROM public.bodycontent
)
SELECT macro_type, COUNT(*) AS row_count
FROM matches
WHERE macro_type IS NOT NULL
GROUP BY macro_type
ORDER BY row_count DESC;

Output

Next, we need to determine if there are any unsupported diagram types in use by the plantuml diagram macro to ensure they are compatible.

This query won’t find diagrams with the default plantuml type, but will detect the unsupported ones for you.

Query

SELECT matches.type_value, COUNT(*) AS count
FROM (
  SELECT 
    regexp_matches(
      body, 
      '<ac:parameter ac:name="type">(ditaa|wbs|dot|gantt|nw|salt|jcckit|mindmap|json|latex|math)</ac:parameter>', 
      'gi'
    ) AS match_array
  FROM public.bodycontent
) AS sub,
LATERAL (
  SELECT match_array[1] AS type_value
) AS matches
GROUP BY matches.type_value
ORDER BY count DESC;

Output

2. Migrate the data to Confluence Cloud

Use the Confluence Cloud Migration Assistant (CCMA) to migrate your Spaces and Pages to Confluence Cloud, then follow the step-by-step below.

Do not edit pages in Confluence Cloud before you run the migrator or the diagram data may be removed, preventing us from migrating the data (this is due to it being in a legacy format).

Post CCMA Steps

Migration is a complex process:

• Always do a test run of the migration on a copy of the space and verify it’s success.

• Always make a backup before performing a migration.

1. Ensure that the current account has full read/write access on all pages

The migrator runs as your current account, therefore you must ensure that your user account has full read and write priveledges on the spaces and pages that you intend to migrate.

2. Open the Confluence Administration page from the top-right

3. Click on Apps → Capable from the left sidepanel

4. Click on the ‘Migration’ tab, select Avono

You can change the scope of the migration by using the CQL filter in the options panel.

5. Click ‘Migrate’ to start the migration

During migration, you will see a log of the operations being performed. As this log gets quite long, it is limited in length after a certain amount of lines. You can download logs throughout the migration which can help with debugging, but likewise, is not unlimited in length and encourage you to take frequent snapshots to aid in debugging later.

6. Your diagrams are now migrated!