CiviCRM upgrade oddities: message template mods

You’re probably familiar with Message Templates in CiviCRM. They’re CiviCRM’s way of providing you with customizable and re-usable content to place into emails such as contribution receipts, event confirmations, and more.

What you might not know is that customizing these templates — while very useful for your communications strategy — can create a nasty headache when upgrading CiviCRM.

The reason is very similar to the problem with file overrides:

You may customize a message template from CiviCRM version A, but if CiviCRM version B includes changes to that message template, you’ll have a tough time getting both the latest changes and your own customizations into one cohesive template.

Why is this an upgrade oddity?

Non-technical site administrators aren’t likely to enjoy this highly technical task, but it’s a required part of some upgrades — if the upgrade includes changes to any message templates that you’ve customized.

Can you just skip this?

You might get away with it, but I don’t recommend it. Message Templates represent important content that your constituents will see.

If you care about your communications strategy, you’ll want to ensure your Message Templates are in good shape.

How can you handle this oddity?

Here are some tips for minimizing the headaches around this oddity:

• Document your customizations. When you’re eding a Message Template, you can add a comment directly in the Message Template like so:
  {* I’m changing X, Y, and Z because of A, B, and C *}
  and that comment won’t be seen by your users. But you (and future site admins) will see it when it’s time to clean up the Message Template.

• Use the excellent extension Better Message Templates. This beautiful add-on will allow you to see exactly how your customized Message Templates differ from the original version provided by CiviCRM — very useful if you never bothered to document your customizations in the first place.

• Take note of your customizations before an upgrade. After the upgrade, CiviCRM may still remind you that some Message Templates need your attention, but by then it can be hard to figure out what your customizations were, and why you made them.

If that’s all too much for you, then do your best to avoid customizing your Message Templates. Just use what CiviCRM gives you out of the box.

Customization is fun. But supporting it properly is work — especially at upgrade time.

All the best,
A.