Templating

Templating is supported for Inputs, Instances, and Flows. Templating is a quick way to create 100’s of configuration objects when each object differs by only a small amount. For example, if an OPC UA Server has 100 machines and the addressing of each machine only differs by a unique machineID, a single Input can represent all 100 machines.

Template Settings

The template settings for Inputs, Instances, and Flows are described below. Note that templates can be statically defined or dynamically defined. When dynamic templates are used the template definitions come from an external source like a database or CSV file.

Static Parameter Examples

Below are examples of the different syntax supported for static template parameters.

The syntax can be chained together to provide maximum flexibility. As an example:

machineid: 1,2,3-5,11*2 transforms into 1, 2, 3, 4, 5, 10, 11, 11

If multiple parameters are used, each parameter must expand into the same number of values. The first object is created with the first value of each parameter, the second object with the second value, etc. Parameters can be used anywhere in the object configuration.

Parameters are referenced inside the configuration using the {{this.paramName}} syntax.

Dynamic Parameter Examples

The Dynamic Reference option references a source of data. The source must return an array of objects with the same schema, where the keys for each object are the parameter names and the values are the replacement values. Below is an example.

Assume reference {{Connection.SQL.templateParams}} returns the following two rows from a SQL table.

[
    {
        "param1": 1,
        "param2": 2,
    },
    {
        "param1": 10,
        "param2": 20
    }
]

This is the same as assigning static parameters as follows.
param1: 1,10
param2: 2,20

The Dynamic reference is re-read any time the object definition is saved, or when the flow that references it is restarted. If the raw input data isn’t in the above format, use a Custom Condition to transform the input into the required format.

Viewing Templates

To view the generated templates use the Templates navigation option that can be found on the Detail page.

The Template view allows you to select one of the projected templates, view its parameters and resulting configuration, and perform a test read.

Templated objects can easily be converted into concrete objects using the Actions menu to either create the current object or create all objects. This allows the use of templating to mass create configuration objects. Once created, the resulting Input or Instance is no longer templated, but contains the name and configuration generated by its parameters.

Templated Instances and Inputs

When a templated Instance is referenced as a Flow source, it is expands using the template configuration. As an example, if a Flow source has a single templated Instance that expands into 10 Instances, on each Flow execution all 10 Instances are sent to the targets. This is equivalent to manually creating all 10 Instances and assigning them to sources of the Flow.

Templated Instances can also be referenced as Condition sources. When referenced, the templated Instance expands and each source instance provides a unique condition instance by name. This is equivalent to manually creating all 10 Instances and assigning them to sources of the Condition.

When a templated Instance is referenced as an Instance expression, it expands into an array of all the objects. If this is not desired the behavior can be overridden by manually passing the parameters through the references (ex. {{Connection.opc.tags(tagid=100)}}).

Templated Flows

Templated flows is equivalent to creating many flows with similar configuration. The flow sources, targets, or trigger expression support template parameters.

A common use case for templated flows is moving machine data on a state change of a machine. In this use case a flow is configured with a trigger expression to trigger when the machine changes state. Once the flow detects a state change, data for the machine is collected, modeled, and sent to the targets. Using flow templates, the trigger expression and sources can be templated, passing a machineID parameter like {{Connection.opc.machine(machineID={{this.machineID}})}}. The flow template settings then define all the machines. This allows a single flow configuration to flow data for 100’s of machines.

Input and Instance Parameters

Inputs and Instances can accept parameters similar to how functions in code take arguments. As an example, consider a SQL Input that queries for machine information. The following query returns data for a specific machine (123).

select * from machineTable where machineid=123

This input can be parameterized to modify which machine is queried.

select * from machineTable where machineid={{this.myid}}

Now that the input is parameterized, ‘myid’ can be passed in at the time the input is referenced. As an example, the following reference passed in a value of ‘123’.

{{Connection.SQL.machineTable(myid=123)}}

When the input is read myid gets replaced with 123, and information is returned for that machine.

Parameters don’t require the use of Templates, but Templates can be enable to provide a default argument for parameters. As an example, if the SQL input mentioned above had Templates enabled, and a single Parameter of myid=456 defined in the template configuration, an expression could reference {{Connection.SQL.machineTable}} and myid would be 456, which is the template default.

Inputs and Instances can take one or more parameters. When multiple parameters are used the references look as follows. Parameters are case-sensitive and order doesn’t matter.

{{Connection.OPC.myTag(param1=10,param2=11)}}