What is the migration story for Cloud to DC when Forge is involved?

Confluence Development
1

Preamble

For obvious reasons, much of the discussion over the past few years around Forge and/or migrations has been in the context of either:

  1. DC (Server) → Cloud migrations, where Cloud is clearly the preferred platform that Atlassian wants customers to move to, and/or
  2. Connect → Forge migrations, where Forge is clearly the preferred app development environment that Atlassian wants developers to move to

What doesn’t seem to have really been discussed much is when customers choose to go the other way, from Cloud → DC.

As a vendor, we occasionally get questions from customers regarding steps for moving from Cloud to DC, so it definitely seems to be something that does happen from time to time, despite all the “cloud is the future” rhetoric swirling about for the past many years.

Migration scenarios

To quickly summarise, vendors that support both platforms (DC, Cloud) and all three app environments (P2, Connect, Forge) now have ensure their apps cater for the following possible migration paths:

  1. P2 → Connect (DC → Cloud)
  2. Connect → P2 (Cloud → DC)
  3. Connect → Forge (App adopting Forge)
  4. P2 → Forge (DC → Cloud)
  5. Forge → P2 (Cloud → DC)

(Forge → Connect is not considered, as typically the Forge version of an app supercedes/replaces the Connect version, and there’s no going back)

A simple Confluence macro example

Imagine a simple Confluence macro that doesn’t store any data outside of the Confluence page it lives in. Maybe it has some macro parameters, maybe it has a plain text body, but all of that configuration data is stored as part of the page content.

(Note: what I’m about to briefly describe below has been previously explained more comprehensively by @clouless , so I would encourage you to read that post as well).

Because P2 and Connect macros share the same underlying storage format, migrations between DC and Cloud (in either direction) do not require the vendor or customer to do anything special.

For DC → Cloud migrations, the Confluence Cloud Migration Assistant (CCMA) takes care of exporting the page content from DC and importing it into the target Cloud instance. Any instances of the macro that were created using the P2 app seamlessly work with the Connect app after migration.

For Cloud → DC migrations, my understanding is there is no CCMA-like tool; but customers can simply export pages/spaces from their Cloud instance and import them into their DC instance manually, and the effect is the same: any instances of the macro created using the Connect app seamlessly work with the P2 app after migration.

So that’s the P2 → Connect and Connect → P2 scenarios covered.

Enter Forge

As per Bernhard’s post linked above, when introducing Forge, Atlassian chose to use a completely new storage format (one that initially did not support bodied macros at all, and only recently added support for rich-text bodies, but to this day still does not support plain-text bodies).

To support macros created using Connect, Forge apps understand macros stored using Connect storage format (with the caveat that any plain-text body content will be available in a special config.__bodyContent property in Forge). This means that a Forge app can render macros stored in Connect storage format, and later if/when the macro is edited and saved, from that point onwards it will be stored in Forge storage format.

Recently, the app migration platform announced support for Forge migrations from P2, and the working assumption is that just like Connect above, any macros created in P2 that have plain-text bodies would convert to config.__bodyContent.

So that largely solves the Connect → Forge and P2 → Forge scenarios.

Leaving the cloud

That just leaves one migration scenario not yet covered: Forge → P2

Unlike Connect → P2, simply exporting page content from Confluence Cloud and importing it into Confluence DC won’t work, because P2 plugins don’t understand Forge storage format.

This suggests that some sort of migration process needs to be developed by the vendor if they want to continue supporting customers that are looking to move from Cloud → DC after adopting Forge.

Have vendors built something like that for their apps? How are other vendors handling Cloud → DC migrations when Forge is involved?

Does Atlassian have any roadmap plans for this?

3 Likes
2

Wasn’t clear what their plans were for DC either in the latest Connect retirement post.

Seems obvious that with Server retired and Connect being retired, that Atlassian would want to get rid of DC as well.

I assume the only reason they haven’t yet is because there are large paying customers on DC who don’t want to migrate to Cloud and thus the business risk is perceived to be too high to force them to migrate.

3

Awesome :rocket: summary :slight_smile:

Does the DC → Forge Cloud migration for Confluence macros really work out of the box?
My last info from the Atlassian Support was, that I would have to manually migrate the storage format. I manly tested with manual space imports (DC->Cloud) and then the macro did not render in Cloud.

I have written a script to help with that: (It could be easily adapted the other way Cloud-DC)

The support engineer told me there would be no automated way and that they have a dedicated migration team that can help customers with semi-automated migrations.
So for me that is what I am telling my customers if they are having problems.

But my initial wish from 2022/2023 would also have been a fully bi-directional automated mapping/migration by Atlassian …

1 Like