Examples of document refactoring

Refactoring in the brXM projects I’ve worked on generally seems to be something that the developers try to avoid. I’m not sure of the exact reason but I’d assume that it is likely due to a few reasons which I’ll list below.

  1. IDE Refactoring generally doesn’t know about references to types in .yaml and other non code files.
  2. Many of the definitions for content and such in brXM are defined outside of code and in custom .yaml files again which IDE and other refactoring tools know little about how to automatically refactor/replace.
  3. The CMS Console and CMS tools don’t appear to have any built in refactoring support for local development or production scenarios.
  4. The fact that content data exists in production which would need to be modified as part of the refactoring means that there will be a disjoint step at the end of the refactoring to deal with migrating the content data to the new shape/schema.

Although I can think of all sorts of ways to improve upon the issues from points 1-3 many of those are to do with design, architecture, and feature support within brXM itself. As for point #4 from above however I’d like point out that while there seems to be support for writing groovy updaters to achieve this type of work I’ve only come across these as part of major brXM platform upgrades and these were provided as part of the upgrade by Bloomreach.

What I’d like to ask is whether the groovy updater scripts are intended to be the right tool for the job when following up with document/content refactoring changes for brXM developers? If so are other teams using this feature for their own refactoring changes regularly; Perhaps Bloomreach has some telemetry/analytics on the usage of these they could share? Additionally, what resources or support are there beyond the two examples to suggest how to utilize the groovy updaters to automate refactoring changes?

The current trend that I’ve spotted and have followed myself is that any refactoring is done literally by hand through the CMS console one document at a time. Seeing that there are three copies of very document node in our case we have over 10 environments which would have to be manually updated it’s easy to see why at least the teams that I’ve worked with have simply avoided refactoring in general. I hope by this discussion that I may potentially shine some light on tools like groovy updaters and perhaps other techniques or tools that I’m unaware of which may make the developer experience a bit better when working with brXM projects. Any thoughts or feedback is welcome.

1 Like

The groovy updater is definitely very useful for modifying content in this manner. You should use this as manual editing is tedious and error prone. Unless the amount of nodes affected is very small I would highly discourage doing this by hand.

1 Like

Awesome, thanks @jasper.floor for the confirmation that groovy updaters are a place to look for automating content / configuration refactoring.

As a point of feedback I’d just like to emphasize that the existing documentation on how why and when to use groovy update scripts is lacking in my opinion. Given the importance and what I would guess regular necessity of refactoring in general I’d expect more material on nuances, best practices, and more examples of groovy updaters.

Perhaps there is more material than what I’ve pointed out above as well so if there are any additional links that anybody could point to then it would be a big help as our team picks up the the skills for writing updaters for brXM.

Thanks, we appreciate the feedback. I can’t promise any improvement, but we do use feedback to improve things where we can.

1 Like