Migration to Confluence Cloud - User macros

[Volker Weinreich]

Hello,

We are facing the task of migrating to the cloud. Apart from the platform change, version and app updates and all the problems that can arise, I am mainly concerned with the question of how we should migrate all the user macros. Interestingly enough, you can find very little about this at Atlassian and in the community. And if you do, it sounds like: "User macros are just no longer available", "Just read how to write and deploy Connect and Forge apps", "Look in the Marketplace if there is something similar" ... In short: "See how you get along".

I am somewhat flattened by this. I don't know about others, but that's not exactly how the migration to the cloud is made attractive.

I think there's a funny notion of who primarily writes user macros and cares about content being elaborated and presented in a certain way in small and medium sized companies. Administrators? No! Developers? No!! Basic users No!!! I guess it's often technical editors or other guys who wrote macros for their colleagues with a cultivated half-knowledge to make their lives easier or to improve the layout.

And now they are faced with the daunting task of "migrating" all of these user macros, which means they can plug holes in thousands of pages and make sure that the contents of the macro bodies somehow resurface, are repackaged, or replaced altogether. To cope with all this, one has to learn new topics in a very short time (which might be fun, but can't be done "on the side"). For some macros, I don't even know if I can fix any errors at all.

...Maybe migrating to another system is easier after all? I don't know.

Am I seeing this wrong or too negatively? Is it not as complicated and time-consuming as it seems?

What is your opinion? What are your experiences?

Thanks,
Volker

[Nic Brough -Adaptavist-]

Hi Volker,

The short answer is very simple - there are no user macros on Cloud.  You have to drop them all.

The long answer is not a lot longer but does imply a lot of work.  You will need to look at every user macro you are using and identify a way to do it on Cloud, then decide if it is worth the effort and cost to do a migration for it (if it is even possible).  The ways to do it may well include finding or writing Connect or Forge apps, or identifying a Cloud app from a third party that can do something similar.

I would strongly recommend that you go to an Atlassian Partner to do this - we (I'm talking all the partners, not trying to advertise just the one I work for), have spent a lot of the last few years doing Cloud migrations for a lot of all sorts of Atlassian systems, and we have run into all sorts of "interesting" problems during them.  It is probably worth leaning on that wealth of expertise, rather than trying to do everything yourself!

[Volker Weinreich]

Hi Nic,

thanks for your reply.

Yes, I know that user macros are no longer available in the cloud. That was not the question.

However, I am appalled that they don't exist anymore and how Atlassian is dealing with it. The point is that before it was possible by relatively simple means to write and include user macros - and both simple and very complex macros. This task is now made more difficult. Either you have to get more developer skills on it yourself or you have to use external, paid support. This is not satisfactory. It is especially not satisfying that for the migration there is no way to "transform" existing user macros in any way - this is especially true for simple macros.

It's already clear to me that app and macro development should also be a business area for the partners. But it can't be that we or a paid service now have to plug thousands (and I mean that literally) of holes because we were so "stupid" to take the opportunity to write macros. The migration effectively deletes content. This is not acceptable.

I don't know yet what the macros and their contents will look like in the source code after the migration. Supposedly, you can still edit them completely. But if I understand it correctly, they will not be in a kind of container, in which is recognized: This is the body, this is a parameter etc.

No, I'll probably have to do bulk replacements with regular expressions and hope that everything goes well.... And also for that I will have to buy apps again.

What I'm saying is: It's one thing to say, "Hey, new user macros are now written like this: ...".

But it is something completely different when we customers are simply left out in the cold with the existing user macros or are referred to alternatives that we have to pay for.

Then why shouldn't I just as well pay for a service that takes me completely from Atlassian Confluence to another product?

[Michael Aglas]

Atlassian Cloud is a mess... In my company we have just a few macros, but non-theless, it is unbelevieble this option is no longer existing. I mean if it is about security concerns, then they could have implemented something else, so we are able to have them available in another way.

After all the promises regarding Atlassian Cloud (Jira/Confluence/...) I am so disappointed. I can't understand how and why it is like it is... It is frustrating, especially because very basic things for formatting text are not available...

And my personal POV is that it is the wrong way to go and ask a partner company for help for such basic things. Atlassian is making the tool admins dump on purpose.

[Nic Brough -Adaptavist-]

Yep, I see that a lot.

User macros are a great feature for Confluence DC (server too, but it's almost identical code to DC and it's going away, so I'm going to stop saying Server), but there are a few of big problems with them on Cloud.

• Cloud is based on a set of technologies that are not as close to DC as we might assume.  Cloud and DC are very different bits of software that have (mostly) compatible data, similar UIs, and very different underlying functionality.
• User macros are howlingly powerful and underestimated, and I would wave the "security risk" flag, but only if your organisation gives admin rights to someone malicious.  You can write user macros (on server/dc) that could send all your data to someone else, delete it randomly, and and and.
• On DC, user macro problems are the problem of the Confluence admins
• On Cloud, Atlassian have security, compliance, and regulation to be their problem, and they, understandably, don't want to do the complex cases.   Admins getting server-like user macros wrong could cost them a fortune, and land them in court
  
  Much as I would love user macros on Cloud, I understand why Atlassian have not allowed them (yet.  There are some options)

[Roma Bubyakin]

Hi Volker,

I'm from Wombats Corp Atlassian Marketplace.

Precisely for such a case, we have developed a User Macro for Confluence Cloud app.

It still has some limitations due to Atlassian Cloud limitations, however, there are many things you can achieve with it.

Regarding migration, I will be happy to support you on the way for each of your use cases.

Regards, Roman

[Michael Aglas]

yeah, another paid app

[Roma Bubyakin]

Sad, but yes.

At least there is some possibility to substitute previous functionality.

[Volker Weinreich]

Hello Roman,
that sounds very interesting.
I have taken a different approach, roughly described: I put REST requests in loops that search in page branches containing my user macros and then use scripts to find and replace specific text parts. I did the whole thing with node.js and the newman library.
Not quite trivial for a non-developer, but it worked.

Regards,

Volker

[Roma Bubyakin]

Wow, that sounds impressive!

But it looks like just a one-time replacement before migration to not have errors.

[Volker Weinreich]

Yes, for example I've replaced own info boxes with the confluence ones or removing some no-print-macros etc. We will have to see how we proceed when it comes to creating new user macros. Your app is definitely interesting.

[Roma Bubyakin]

Migration is a good time to take out legacy and unify things around.

Several years ago I did the same thing but used Java + direct SQL queries (less safe than your method, but worked fine).

Good luck with clean-up and migration duties 🤗

[Kirstin Seidel-Gebert]

Has somebody tried to export a space to XML and then use XSLT to replace the user macros with their original content? And then import back again?

[Roma Bubyakin]

I did a similar thing but w/o import-export. With direct SQL requests.

It is not safe enough so it should be tested carefully and requires reindexing after.

[Kirstin Seidel-Gebert]

IMHO there is a difference between what you can do with SQL updates and XSLT scripts. XSLT is a very powerful tool and I have seen our developers do complex transformations with only some lines of code.
But agreed, the outcome should be tested carefully, and you pointing to re-indexing is very helpful.

I have filed a migration request at Atlassian where this came up, and the agent said that he would have a look in his test labs.