Contents
A customer rebrands. New logo, new letterhead, slightly different blue. Somebody has to go through fifty-two document templates and update the image in each one.
That was the position until this summer, and the reason was a decision made years earlier that looked entirely sensible at the time.
How the logo used to get into the document
Templates are HTML. When a document was generated, any image referenced in the template was fetched from object storage, base64-encoded, and inlined into the markup before rendering.
It works. It's also the reason for the fifty-two edits, because an image handled that way has no identity beyond the string sitting in each template. There's no list of what your brand assets are, no way to change one in a single place, and no way to see what a template will look like without generating a document to find out.
It's slow, too. Every generation pays for a fetch and an encode of bytes that never change.
So brand assets became things in their own right, with an upload and management panel inside the template editor. Upload a letterhead once, use it in every template, replace it in one place. The editor lists what exists, so you pick from your actual assets instead of remembering a filename.
Which raises the question that made this a fortnight of work rather than an afternoon.
A letterhead and a medical report are different things
SwiftCase holds client documents. Medical reports, engineer's assessments, settlement letters, correspondence about people's claims. A letterhead has nothing in common with any of those beyond happening to be a file, and the whole job was making that difference something the system enforces rather than something it assumes.
Case documents are excluded structurally, so nothing belonging to a client is reachable as a brand asset whatever anyone does to it. And an asset becomes one because an administrator deliberately made it one, so nothing gets published by being uploaded to the wrong place.
The checks refuse by default at every step. That means the failure mode is a missing logo rather than a file that should never have been served, and a missing logo gets spotted in about a minute.
Fonts and stylesheets, which is where it gets useful
Once assets are managed properly, a template stops being limited to images.
A brand typeface can be uploaded and referenced from the template. A shared stylesheet can carry the house rules for headings, tables and spacing, so fifty-two templates stop each carrying their own slightly divergent copy of the same CSS. That's the change that makes a rebrand a one-file job.
What a rebrand touches now, and what it doesn't
Replace the file behind the asset. Every template referencing it picks up the new version on the next generation.
Documents already produced keep the old logo, which is correct behaviour and worth saying out loud. A settlement letter sent in March was sent on March's letterhead. If somebody requests that document during a complaint two years later, it should look like the document that was sent, and a system that retroactively rebrands its own archive is a system with an evidential problem.
So the generated output still contains the rendered image. The asset is resolved at generation time, and after that the document stands on its own.
The caching detail
The list of available assets is cached for five minutes.
That number came from watching the two failure modes. Uncached, the template editor queries for the asset list on every render, which is a lot of identical work for something that changes when somebody uploads a file. Cached for too long, an administrator uploads a logo, does not see it, uploads it again, and now you have two.
Five minutes is long enough to absorb the editor traffic and short enough that the second upload has not happened yet.
The general shape
The version of this feature that gets described in a changelog is "upload and manage assets from the template editor", which sounds like a panel with a file input.
The work was deciding what a brand asset is allowed to be, then making sure that decision still holds when somebody uploads the wrong file in the wrong place. Everything else was a panel with a file input.
That ratio is normal. The feature is small and the boundary it crosses is not, and the boundary is where the time goes.
Further reading:
- Document generation: templates, merge fields and batch output
- Documents and email: creating templates and inserting task information tags
- The complete guide to document generation: the longer walkthrough
- Security: how access is gated across the platform