Change the copy without a deploy. Keep every version.
A file-based renderer makes every template edit a deploy, and an edit changes what every notification renders, past and future. Managed templates live in a data store instead: someone who is not a developer edits them, every edit is a new version, a version is published on purpose, and a notification can be pinned to the exact one it should render.
Templates
How it works
Wrap the renderer you have. Reference a key instead of a path.
A managed-template renderer composes another renderer rather than replacing it: it fetches the stored template and hands the engine its source. The notification service does not change. The only difference a caller sees is that body_templatebodyTemplate names a template key.
Write a draft
A template has a key, a body, a subject and an optional preheader, tags and a tenant. Its first version is created in draft. Nothing sends it yet.
>>> templates.create_template(ManagedTemplateCreateInput(key="welcome", …)) > await templates.createTemplate({ key: 'welcome', … }) Preview, then activate
Render the draft against a context you type, check the composed output, and publish it. Every status change is written to the audit trail with who made it.
>>> templates.activate("welcome", changed_by="hugo@example.com") > await templates.activate('welcome', { changedBy: 'hugo@example.com' }) Sends pick the newest active version
An unpinned send renders the highest-numbered active version, never a draft. A pinned one renders the version it was pinned to, and records the version that actually rendered either way.
>>> notification.used_template_version # 3
> notification.usedTemplateVersion // 3
Wiring it up
Three objects, and the notification service stays as it was.
- A manager backend stores the versions, the status history and the tags. The Django one ships models, migrations and an admin.The Medplum one stores them as FHIR
MessageDefinitionresources. - A managed-template renderer wraps any existing email or SMSemail renderer and feeds it stored source instead of a path.
- A managed-template service is what editors and APIs call: create, version, publish, tag, filter, preview.
- Fallbacks let the application send a key before anyone has written its template: register a default per key and sends use it until a version is activated.
- Wrap an engine that cannot run code. Liquid evaluates expressions and filters only. Pug compiles a template to JavaScript, so keep Pug for templates in your repository.
from vintasend_managed_templates.managed_template_renderer import ManagedTemplateEmailRenderer
from vintasend_managed_templates.managed_template_service import ManagedTemplateService
from vintasend_django_templates_manager.django_templates_manager import DjangoTemplateManager
manager_backend = DjangoTemplateManager() # where the versions live
renderer = ManagedTemplateEmailRenderer(manager_backend, inner_renderer) # wraps any email renderer
templates = ManagedTemplateService(manager_backend, renderer) # create, version, publish, tag
# The notification service is unchanged; only the renderer is wrapped.
service = NotificationService(
notification_adapters=[DjangoEmailNotificationAdapter(renderer, notification_backend)],
notification_backend=notification_backend,
)
service.create_notification(
user_id=user.id,
notification_type="EMAIL",
title="Welcome",
body_template="welcome", # a managed template key, not a file path
context_name="welcome_context",
context_kwargs={"user_id": user.id},
pin_template_versions=True, # record the version that is current right now
)import { LiquidEmailTemplateRendererFactory } from 'vintasend-liquidjs';
import { ManagedTemplateEmailRenderer, ManagedTemplateService } from 'vintasend-managed-templates';
import { MedplumTemplateManagerBackend } from 'vintasend-medplum-template-manager';
const managerBackend = new MedplumTemplateManagerBackend(medplum); // where the versions live
const liquid = new LiquidEmailTemplateRendererFactory<Config>().create({
renderLimit: 1_000, // an edited template cannot make a send hang
strictFilters: true,
});
const renderer = new ManagedTemplateEmailRenderer<Config>(managerBackend, liquid);
const templates = new ManagedTemplateService<Config>(managerBackend, renderer);
// The notification service is unchanged; only the renderer is wrapped.
await vintasend.createNotification(
{
userId: user.id,
notificationType: 'EMAIL',
title: 'Welcome',
bodyTemplate: 'welcome', // a managed template key, not a file path
contextName: 'welcomeContext',
contextParameters: { userId: user.id },
sendAfter: null, subjectTemplate: null, extraParams: null,
},
{ pinTemplateVersions: true }, // record the version that is current right now
);Lifecycle
Versioned, never edited in place. Published on purpose.
An update copies the latest version forward and applies what changed, so a published version's body can never change under a notification that already referenced it. Status moves follow a transition table, and anything else is refused.
- Several versions can be active. Activating v2 while v3 is active does not change what is sent: an unpinned send renders the highest-numbered active one.
- Only a never-published version can be deleted. A version that was ever active may be pinned by a notification, so it is archived instead. Status history is never deleted, and a deleted version's number is never reused.
- Tags edit in place. Tags are how a template is found, not part of what it renders, so retagging does not spawn a version. Slugs are derived by shared rules, so every store agrees on what a label becomes.
- Allowed transitions travel with the payload. A UI enables buttons from
allowedTransitionsinstead of discovering the rules by catching errors.
Composition
Bases, blocks and includes, resolved before the engine runs.
Django's extends and Jinja's include hand a name to a loader, and a loader reads files. Stored templates reach the engine as source, so those tags have nothing to load. Managed templates bring their own tags, resolve them against the store, and hand the engine one flat string with no managed_ tag left in it.
| Tag | What it does |
|---|---|
managed_extends "key" | This template is a child of key. Pin the parent with version=2. |
managed_children | In a base: where the child's content goes. |
managed_block name | A named region a child may replace. Blocks may nest. |
managed_super | Inside a child's block: the content it is overriding. |
managed_include "key" | Splice another template in, composed in full first. Pins the same way. |
- Abstract templates. A template with a
managed_childrenhole, or blocks without a parent, is a base to build on. The flag is derived from the source on every write, so "the templates I can send" is a filter, not a parse. - Pin the parent too. A notification pinned to v3 of
welcomerenders v3 ofwelcome, but an unpinned base still resolves to today's. Name the version on the reference when a child must keep composing against an exact parent. - Failures surface at edit time. Unknown tags, missing references, cycles and runaway depth are the package's own errors, raised by validation before a send ever hits them.
- One tag language, both ecosystems. The Python and TypeScript packages agree on the tags, the slug rules and the filter vocabulary, so a store written by one renders in the other.
The stack
Four packages, each on its own release cycle.
The seam and the service, a store for it, an API over it, and a dashboard on the API. Install what you need; the lower layers work without the upper ones.
vintasend-managed-templates
The BaseTemplateManagerBackend seam, ManagedTemplateService, the email and SMS wrapping renderers, composition, tags and lifecycle rules. Storage-agnostic. GitHub ↗
vintasend-django-templates-manager
DjangoTemplateManager, the models behind it, and an admin that enforces the same delete rules as the service. GitHub ↗
vintasend-templates-management-api
A Django + django-ninja REST API over a ManagedTemplateService. Mount it in your project or run it alone. Its openapi.yaml is generated from the routes and tested against them. GitHub ↗
templates-management-dashboard
A Next.js UI over that contract, with the data layer in a core package. Shared with the TypeScript ecosystem. GitHub ↗
vintasend-managed-templates
The template manager seam, ManagedTemplateService, the wrapping renderer, composition, tags and lifecycle rules. Storage-agnostic. GitHub ↗
vintasend-medplum-template-manager
Stores managed templates as FHIR MessageDefinition resources, next to the notifications that reference them. GitHub ↗
vintasend-templates-management-api
A REST API over a configured ManagedTemplateService. Mount it with createApp or run the command on its own. Shares its openapi.yaml byte for byte with the Python API. GitHub ↗
templates-management-dashboard
A Next.js UI over that contract, with the data layer in a core package. Shared with the Python ecosystem. GitHub ↗
The dashboard
A write tool for the people who own the copy.
Where the notifications dashboard is read-mostly, this one creates templates, versions them, moves them through the lifecycle, previews what they render to and manages the tags. It is a pure client of the templates API, with the key held in its own proxy route, and it is meant to be copied: the data layer is vintasend-templates-management-dashboard-core, the screens are one example in Tailwind and shadcn/ui.
- Templates screen. One row per version, collapsed to each key's current version by default. Source and composition side by side, status history, every version the key has had.
- Tags screen. Create, rename, archive, restore, delete. Renaming is flagged, because the slug is the identity the filters match on.
- Ordering is gated, filtering is not. The two capability namespaces default in opposite directions, so a column only becomes sortable once the backend says so, and a filter control is not drawn when it cannot be honoured.
- Three errors it understands.
INVALID_STATUS_TRANSITION,TEMPLATE_COMPOSITION_ERRORandPREVIEW_UNAVAILABLEget their own UI instead of a generic failure.
Wrap the renderer. Move the templates. Nothing else changes.
The notification service, the adapters and the backend stay exactly as they are. A key replaces a path, and the copy stops being a deploy.