Upload Templates and Message Formats

Define variable scope, routing, field names, and types before changing templates. This page uses MQTT client forwarding to explain common upload templates. Addressing, acknowledgement, and delivery rules remain specific to each target plugin.

Open Development Configuration → Data Forwarding, edit the target’s properties, and open Upload Template Configuration. Establish default messages with the MQTT client first.

Configure and preview a template

Separate the configuration layers

Records generally pass through group selection and entity shaping before Topic and content generation. Referenced fields must exist in the resulting object.

Generate JSON with numeric values

1. Enable Variable List Upload, disable dictionary upload, and use one test variable.
2. Select Json for variable content and enter the template below.
3. Preview, fix syntax or field errors, then save the target.
4. Inspect a new raw message at an independent subscriber. Check that value is numeric and quality is Boolean.

{
  "tag": "${Name}",
  "device": "${DeviceName}",
  "value": ${Value},
  "quality": ${IsOnline},
  "raw": ${RawValue},
  "address": "${RegisterAddress}"
}

This is template text; ${...} is replaced during generation. Keep numbers and Booleans outside quotes and strings inside quotes. "value":"${Value}" produces "1234", while "value":${Value} preserves numeric 1234.

Preview uses sample objects. Actual delivery must be checked against the selected device, variable, and new sample.

Template and message reference

Lists, dictionaries, and individual messages

Dictionary without a content template: read each leaf’s Value for the value. Other entity fields are omitted below.

{
  "Demo_Modbus_Device": {
    "Demo_Modbus_Value": {
      "Name": "Demo_Modbus_Value",
      "DeviceName": "Demo_Modbus_Device",
      "Value": 1234,
      "RawValue": 1234,
      "IsOnline": true
    }
  }
}

Dictionary keys cannot represent every historical change of the same variable. For replay, check batch/model merging and preserve source times; see Offline Compensation.

With default entity serialization, JSON Ignore Null omits null object properties while numeric 0, Boolean false, and empty strings remain. Explicit null values generated by a content template are not automatically removed; Text content is not rewritten either. Compare those four values in the same script object without a content template, then inspect the actual payload for any custom template.

An entity script only changes upload objects. For example, it can output Value=123.4 and RawValue=1234 while collection still displays 1234. Use the variable read expression to change its engineering value, and avoid applying conversion twice.

Placeholder formats

Formatting does not correct clocks or change sample time. Agree on timestamp units and time zones with the receiver.

Devices, alarms, and plugin events

The four entity types have separate templates. Variables expose fields such as Name, DeviceName, Value, RawValue, CollectTime, and IsOnline. Device, alarm, and event templates use their own fields.

1. Fill the Topic for each required type; an empty Topic does not publish that route.
2. Configure that type’s list, dictionary, and content settings.
3. Generate a real device-state change, alarm lifecycle, or plugin event.
4. Match identity and event time at the receiver. Variable messages do not verify alarm delivery.

See Available entity fields for the complete field list and Script Management for type selection. Device scripts can expose routing states; alarm scripts should retain identity, severity, and lifecycle. Plugin events read the actual ObjectValue, for example ${ObjectValue.count}.

Target-variable Data1–Data10 are additional settings. Default entities do not automatically include them. Read and output them explicitly in an entity script, then reference that output from the template. Verify saved settings, script execution, and receiver fields separately.

Confirming the template dialog still requires saving the target. Reopen it to verify persistence. To restore default messages, clear unused content templates and entity scripts and restore list/dictionary settings, then verify new data.

Common upload settings

These are the shared MQTT target defaults. Connection, routing and delivery acknowledgements remain specific to each plugin.

Available entity fields

After an entity script runs, placeholders resolve against its output. Device, variable, alarm and event templates use their own fields; an empty Topic disables publication for that entity.

Troubleshooting