1. Scope

Current template rendering is used for:

• uplink topic (e.g., Kafka/Pulsar uplink.*.topic)
• uplink key/partition key (e.g., Kafka record key / Pulsar partition_key)

Not Applicable Scope (Must Remember)

downlink topic must be exact topic, does not support template/wildcard/regex. Reason: To maintain operable, predictable subscription behavior (Avoid wildcard introducing uncontrollable fan-in). See: Downlink Overview

---

2. Basic Syntax

Template variables use {{var}}:

ng.uplink.{{event_kind}}.{{device_name}}

Template engine uses Handlebars, and:

• Non-strict mode: Missing variables do not error, but render as empty string
• No HTML escaping: topic/key is plain text

Common Pitfall: Missing variable causes topic/key to be empty

If you write {{channel_name}}, but current data type cannot get channel_name, it becomes an empty string. Recommend using default helper to provide fallback value (See below).

---

3. default helper

Syntax:

{{default value "fallback"}}

Example:

ng.uplink.{{event_kind}}.{{default device_type "unknown"}}.{{device_name}}

When value does not exist, is null, or is an empty string, fallback will be used.

---

4. Where do template variables come from

Template variables come from runtime RenderContext. Available fields vary slightly by event type. Full variable table see:

• Template Variable Table

---

5. Recommended topic/key Planning

5.1 topic used to express "Routing Dimension"

Prioritize putting "Routing/Isolation" dimension on topic, e.g.:

ng.uplink.{{event_kind}}.{{device_name}}

Or split by business domain/tenant (If you did isolation at App layer):

tenant.{{app_id}}.ng.uplink.{{event_kind}}.{{device_name}}

5.2 key used to express "Partition & Ordering"

Kafka/Pulsar key/partition_key affects partitioning:

• Want ordering by device: {{device_id}} or {{device_name}}
• Want ordering by point: Usually not recommended (Partitioning too fine affects throughput)

Deeper suggestions:

• Kafka: Partition & Ordering (Kafka)
• Pulsar: Partition & Ordering (Pulsar)