Back to all articlesTemplate planning

Define Every Template Variable So Different Teams Use It the Same Way

Alactic Editorial10 min read

Prepared with AI assistance by Alactic Editorial. Examples identified as hypothetical are illustrative, not customer results.

A writer uses reference to mean the order number. A reviewer assumes it means the shipment tracking number. The person preparing message data supplies a support ticket number. All three values look plausible, and none produces an obviously broken sentence.

The fix is to define every variable as a semantic contract in the content brief: what it means, who owns the underlying fact, what content is permitted, how it should appear, and which plausible substitutions are unacceptable. Include missing-value behavior and unresolved decisions, too. A variable is not ready simply because everyone agrees on its name.

The fictional worked example below provides a filled message template variable dictionary for an order-status message. It stays at the content-brief level: it defines what the message must mean, not CRM field structures, integration mappings, or validation code.

1. Start with the claim the message is allowed to make

Before listing placeholders, write the message’s purpose and its limits. Otherwise, a precise dictionary can still serve an ambiguous message.

Fictional worked example: A retailer wants to tell a customer that one shipment from their order has been handed to a carrier. The message identifies that shipment and gives the current estimated arrival date. All names, identifiers, dates, values, and operational arrangements in this example are hypothetical.

The brief establishes these boundaries:

  • Purpose: Communicate carrier handover for one shipment, not acceptance of an order or completion of delivery.
  • Unit of meaning: One shipment belonging to one customer order. An order may have more than one shipment.
  • Required facts: Customer-facing order reference, shipment reference, carrier name, handover date, and current estimated arrival date.
  • Excluded claims: The whole order has shipped, delivery is guaranteed on a particular day, or every item is in this shipment.
  • Missing-fact rule: If a required fact is unavailable or disputed, this version is not ready to use. A separately reviewed message may express a narrower claim.

That final rule matters. Leaving a variable blank is not the only failure mode. Filling it with a nearby fact can make a complete-looking message materially wrong.

2. Write the sentence before defining the slots

Here is the hypothetical draft message:

Your order {{order_reference}} has a shipment update. Shipment {{shipment_reference}} was handed to {{carrier_name}} on {{carrier_handover_date}}. Its current estimated arrival date is {{estimated_arrival_date}}. For help with this shipment, quote {{shipment_reference}}.

Descriptive names make the brief easier to discuss. If a later template uses positional placeholders, retain these names in the brief so that reviewers can still distinguish the concepts.

The sentence deliberately says “a shipment update,” not “your order has shipped.” It also identifies arrival as an estimate. Those choices carry meaning that the variables must preserve.

For this hypothetical version, the approved display language is English and dates use a spelled-out month. That is a content decision for this version, not a universal format rule. Another language version would need its own display expectations without changing what the dates represent.

3. Use this filled variable dictionary

Each entry below contains a definition, a proposed source owner, permitted content, display expectations, acceptable examples, counterexamples, and an ownership question. The roles are hypothetical assignments to confirm before release, not assumed responsibilities in every organisation.

{{order_reference}}

  • Semantic definition: The customer-facing reference for the purchase order that contains the shipment described in this message. It identifies the order, not an individual parcel or a customer account.
  • Proposed source owner: Order operations owns the authoritative customer-facing order reference. The message-data preparer obtains the value but does not redefine it.
  • Permitted content: One complete order reference already used in customer-facing order communications.
  • Formatting: Preserve its letters, digits, separators, and leading zeros. Supply only the reference; the surrounding sentence already supplies “order.”
  • Acceptable hypothetical example: ORD-004812.
  • Unacceptable substitutions: 48212 if that is an internal record identifier; TKT-004812 if it identifies a support case; or Order ORD-004812, which duplicates the label.
  • If unavailable: Hold this message version. Do not substitute a shipment reference.
  • Unresolved ownership question: Who decides which customer-facing reference to use when an order has been reissued? Proposed decision owner: the order operations lead.

{{shipment_reference}}

  • Semantic definition: The retailer’s customer-facing reference for the single shipment covered by the update. It is the reference a support colleague can use to distinguish this shipment from others in the order.
  • Proposed source owner: Fulfilment operations owns the shipment identity; support owns confirmation that the reference is usable in a customer enquiry.
  • Permitted content: One shipment reference associated with the stated order. Both appearances in the message must have the same meaning and value.
  • Formatting: Preserve the complete reference. Do not add a tracking link, explanatory sentence, or list of parcel numbers.
  • Acceptable hypothetical example: SHP-004812-B.
  • Unacceptable substitutions: The order reference, a warehouse batch number, or a carrier tracking number merely because it also identifies a parcel.
  • If unavailable: Hold this version. Do not collapse several shipments into the order reference.
  • Unresolved ownership question: If one shipment is later divided into separate parcels, does this reference remain useful to customers? Fulfilment and support must agree before including those cases.

{{carrier_name}}

  • Semantic definition: The customer-facing name of the carrier that accepted the shipment at handover, not necessarily the organisation that will perform the final delivery stage.
  • Proposed source owner: Fulfilment operations owns carrier identity. The content owner maintains the agreed customer-facing wording.
  • Permitted content: The carrier name corresponding to the recorded handover event.
  • Formatting: Use the agreed spelling and capitalisation. Supply the name only, with no delivery claim or promotional wording.
  • Acceptable hypothetical example: Northstar Parcel, a fictional carrier.
  • Unacceptable substitutions: Standard delivery, which is a service description; Our warehouse, which is not a carrier; or the name of an expected later delivery partner.
  • If unavailable: Hold this version rather than inserting “our delivery partner.”
  • Unresolved ownership question: Who approves customer-facing names when a carrier operates under several trading names? Proposed decision owner: fulfilment operations, with content review.

{{carrier_handover_date}}

  • Semantic definition: The calendar date when the shipment was recorded as accepted by the carrier. Label creation, packing completion, and planned collection do not qualify.
  • Proposed source owner: Fulfilment operations owns the event definition and the evidence used to establish that handover occurred.
  • Permitted content: A date supported by the actual handover event, expressed using the agreed calendar-date basis.
  • Formatting: For this hypothetical version, use day, full month name, and year: 14 September 2026. Supply no time or relative wording such as “today.”
  • Acceptable hypothetical example: 14 September 2026, if handover occurred on that date under the agreed date basis.
  • Unacceptable substitutions: The order date, dispatch-label creation date, planned collection date, or a date chosen because it makes the timeline look consistent.
  • If unavailable: Do not claim handover. Use a separately reviewed message only if it accurately describes the known event.
  • Unresolved ownership question: Which location’s calendar date governs a handover near midnight? Fulfilment must settle this explicitly before release.

{{estimated_arrival_date}}

  • Semantic definition: The current supported estimate for when this shipment will reach its delivery destination. It is not a guaranteed date, an original checkout promise, or a collection-ready date.
  • Proposed source owner: The delivery operations lead owns the choice of estimate source and the rule for deciding whether an estimate remains current.
  • Permitted content: One arrival date from the agreed source, applicable to this shipment at preparation time.
  • Formatting: Use the same date style as the handover date. The fixed sentence supplies “current estimated arrival date,” so the value must contain only the date.
  • Acceptable hypothetical example: 17 September 2026.
  • Unacceptable substitutions: Tomorrow; 17–19 September 2026, because this sentence expects a single date; or an old checkout estimate used because no current estimate exists.
  • If unavailable: Hold this version. A reviewed variant can omit the estimate or describe an arrival range with suitable wording.
  • Unresolved ownership question: If the carrier estimate and the retailer estimate disagree, which governs? Delivery operations must choose; the writer must not select whichever date sounds better.

4. Resolve ownership without making everyone an approver

“Owned by operations” is too broad to settle a disagreement. Separate ownership of the fact from responsibility for expressing it.

  • Fact owner: Decides what the value represents and which business source is authoritative.
  • Content owner: Decides whether the wording accurately expresses that fact and fits the sentence.
  • Data preparer: Supplies values according to the dictionary and raises exceptions rather than inventing replacements.
  • Release owner: Confirms that blocking questions have decisions before this message version is used.

One person may hold several roles. The important distinction is decision authority, not team size. A reviewer should know whom to ask about an event’s meaning and whom to ask about its wording.

For the fictional dictionary, the date basis and estimate-source precedence are blocking questions: different answers can change the message’s truth. Record the decision, responsible role, and dictionary revision when each is resolved. A discussion thread without a final decision leaves the contract ambiguous.

5. Review combinations, not just individual values

A value can satisfy its own definition while belonging to the wrong shipment. Review the assembled message as a connected claim.

Hypothetical completed example:

Your order ORD-004812 has a shipment update. Shipment SHP-004812-B was handed to Northstar Parcel on 14 September 2026. Its current estimated arrival date is 17 September 2026. For help with this shipment, quote SHP-004812-B.

Ask reviewers to confirm that both references describe the same shipment relationship, the named carrier accepted that shipment, and the arrival estimate applies to it. Correct formatting does not establish those relationships.

Then challenge the brief with hypothetical exceptions:

  • Only a shipping label exists: The handover claim is unsupported; do not substitute the label date.
  • The estimate is a range: This message version does not fit. Review range-specific wording rather than squeezing a range into a date slot.
  • The order has several shipments: Keep this update scoped to one shipment. Do not imply that every item has left.
  • The estimate precedes handover: Ask the fact owner to resolve the inconsistency; do not silently edit either date.
  • The estimate disappears: Do not preserve an older value solely to complete the message.

6. Prefer explicit variants to clever substitutions

A strict dictionary creates more exceptions than an “anything reasonable” placeholder. That is the trade-off: fewer convenient substitutions, but clearer claims and more visible gaps.

When an exception recurs, decide whether it deserves a separate message variant. A handover update without an arrival estimate can be useful if it states only what is known. A range estimate may also deserve different wording. Neither requires weakening the definition of estimated_arrival_date.

Avoid allowing values such as “not available,” “soon,” or entire sentences in a slot defined as a date. That makes the fixed wording unpredictable and transfers writing decisions to the data preparer.

If an incorrect substitution is discovered, pause use of the affected version, identify whether the definition or its application failed, and involve the fact owner. If messages have already been sent, have the responsible team assess whether recipients need a correction. Fixing the dictionary does not itself correct an earlier message.

7. Run a small interpretation test before release

Give the draft dictionary to a writer, a reviewer, and a data preparer independently. Ask each to identify the right value, reject a plausible substitute, and state the missing-value action for every variable.

Compare their answers before discussing them. Agreement reached only after a long explanation is evidence that the brief still needs work.

For a practical next action, choose one existing message and record:

  1. How many variables have a complete definition, source owner, format, counterexample, and missing-value rule.
  2. How many independent answers disagree about meaning or permitted substitutions.
  3. How many ownership questions remain unresolved, and which block use of the message.

Revise the dictionary and repeat the disputed cases. The observable outcome is not merely a completed document: it is that different teams choose the same meaning, reject the same misleading substitutes, and know who decides when the right value is unavailable.

Template planningContent operationsVariable dictionariesMessage quality

Put the next conversation to work.

Explore Alactic Communications for WhatsApp conversations, campaigns and AI-assisted workflows. Choose the product and plan that fit your team.

Explore Communications