Templating

Templating is supported for Inputs, Instances, and Flow Triggers in Pipelines. 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 Flow Triggers 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 source, it expands using the template configuration. As an example, if a Flow Trigger source has a single templated Instance that expands into 10 Instances, on each Flow Trigger execution all 10 Instances are sent through a pipeline. This is equivalent to manually creating all 10 Instances and assigning them to sources of the Flow Trigger.

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 Flow Triggers

Templated Flow Triggers are equivalent to creating many Flow Triggers with similar configuration. The Flow Trigger sources and trigger expression support template parameters.

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