Templating

this guide explains how to write templates for point messages and mqtt topics in the factry historian system templates define the structure of mqtt messages and topics, enabling dynamic generation of content and paths based on specific data this guide outlines available fields, functions, and examples for common use cases overview templates are written using go’s text/template syntax each template type has a specific context object, which determines the fields and functions available placeholders ( {{ }} ) are used to dynamically insert data example point message template { "measurement" "{{(getmeasurement ) name}}", "value" {{ tojson value }}, "timestamp" "{{ timestamp }}", "status" "{{ errorstatus }}" } example topic template template types point message templates used to define the content of mqtt messages for collected data points measurement topic templates used to define the mqtt topic structure for measurements asset property topic templates used to define the mqtt topic structure for asset properties quick reference commonly used fields (point message templates) timestamp the time when the point was created value the actual value of the measurement errorstatus the status or error description for the point measurementuuid the unique identifier for the measurement commonly used functions getmeasurement fetches information about the measurement getasset fetches information about the associated asset tojson converts data to json format detailed reference point message templates field description timestamp iso 8601 formatted timestamp for the data point value the value of the measurement tags metadata tags for the point errorstatus error status of the point, if applicable measurementuuid uuid of the associated measurement assetpropertyuuid uuid of the associated asset property, if applicable available functions function description getmeasurement fetches details about the measurement getasset fetches details about the associated asset getassetproperty fetches details about the associated asset property getdatabase fetches details about the associated database getcollector fetches details about the associated collector measurement topic templates field description measurement name of the measurement database name of the associated database collector name of the associated collector uuid uuid of the measurement available functions function description getmeasurement fetches details about the measurement getdatabase fetches details about the associated database getcollector fetches details about the associated collector asset property topic templates field description assetpath path of the asset (e g , plant/area/device) asset name of the associated asset assetproperty name of the associated asset property uuid uuid of the asset property available functions function description getasset fetches details about the asset getassetproperty fetches details about the asset property getmeasurement fetches details about the associated measurement getdatabase fetches details about the associated database getcollector fetches details about the associated collector fields in function return types getmeasurement field description name name of the measurement datatype data type of the measurement description description of the measurement labels labels associated with the measurement quality quality of the measurement status status of the measurement (e g , active) collectoruuid uuid of the associated collector databaseuuid uuid of the associated database getasset field description name name of the asset assetpath path of the asset (e g , plant/area/device) description description of the asset status current status of the asset parentuuid uuid of the parent asset, if any getassetproperty field description name name of the asset property description description of the property datatype data type of the property (e g , string) assetuuid uuid of the associated asset measurementuuid uuid of the associated measurement getdatabase field description name name of the database description description of the database status status of the database getcollector field description name name of the collector description description of the collector status status of the collector ipaddress ip address of the collector buildversion build version of the collector sprig extending template capabilities these templates support sprig , a library of additional functions that extend the capabilities of go templates with sprig, you can perform tasks like string manipulation, mathematical calculations, and handling default values, making your templates more flexible and dynamic for a complete list of available sprig functions and their usage, refer to the official documentation sprig functions documentation performance considerations for templates efficient templates are crucial for maintaining system performance, especially when working with dynamic data in high throughput environments keep the following in mind while creating templates simplify template logic avoid overly complex or deeply nested expressions that can slow down rendering use default values handle missing data gracefully with defaults to prevent errors and reduce processing overhead minimize function overhead reuse computed values within the template by assigning them to variables using with , range or directly by following these guidelines, you can ensure your templates are both powerful and optimized for performance example templates point message template basic message with measurement name and value { "measurement" "{{(getmeasurement ) name}}", "value" {{ tojson value }}, "timestamp" "{{ timestamp }}" } include detailed information about the measurement, is used to remove whitespace { {{ $measurement = getmeasurement }} "measurement" { "name" "{{ $measurement name }}", "datatype" "{{ $measurement datatype }}", "status" "{{ $measurement status }}" }, "value" {{ tojson value }}, "timestamp" "{{ timestamp }}" } include the name and path of the associated asset { {{ $asset = getasset }} "asset" { "name" "{{ $asset name }}", "path" "{{ $asset assetpath }}" }, "measurement" "{{(getmeasurement ) name}}", "value" {{ tojson value }}, "timestamp" "{{ timestamp }}" } a detailed message that combines information from the point, measurement, and associated asset property { {{ $measurement = getmeasurement }} {{ $assetproperty = getassetproperty }} {{ $asset = getasset }} "measurement" { "name" "{{$measurement name}}", "datatype" "{{$measurement datatype}}", "labels" {{ tojson $measurement labels }}, "status" "{{$measurement status }}" }, "value" {{ tojson value }}, "timestamp" "{{ timestamp }}", "error" "{{ errorstatus }}", "tags" {{ tojson tags }}, "assetproperty" { "name" "{{$assetproperty name}}", "description" "{{$assetproperty description}}" }, "asset" { "name" "{{$asset name}}", "path" "{{$asset assetpath}}" } } add a category field based on the value range, making sure the numbers are compared as floats { "measurement" "{{ (getmeasurement ) name }}", "value" {{ tojson value }}, "timestamp" "{{ timestamp }}", "category" "{{ if lt (float value) 10 0 }} low {{ else if and (ge (float value) 10 0) (lt (float value) 50 0) }} medium {{ else }} high {{ end }}" } include custom labels for the measurement { {{ $measurement = getmeasurement }} "measurement" "{{ $measurement name }}", "labels" \[{{ range $index, $label = $measurement labels }} "{{ $label }}"{{ if lt (add1 $index) (len $measurement labels) }}, {{ end }} {{ end }}], "value" {{ tojson value }}, "timestamp" "{{ timestamp }}" } show asset data if it’s available { {{ with getasset }} "asset" { "name" "{{ name}}", "path" "{{ assetpath}}" }, {{ else }} "asset" null, {{ end }} "measurement" "{{(getmeasurement ) name}}", "value" {{ tojson value }}, "timestamp" "{{ timestamp }}" } measurement topic template asset property topic template