Working with Templates
Templates allow you to design many similar flows efficiently and consistently. Typical use cases include flows that differ only in specific values, such as data points, table names, IDs, or connection names.
Overview of Terms
Template
A template is the basic framework of a flow. It contains all the fixed parts of the design.
Template Variable
A template variable is a placeholder within the template. You use it to define the values that may differ between individual flows. The fields of the trigger and transfer objects then contain only the placeholder—for example, {Machine}—and the value it takes on is determined at the instance.
Each template variable has a name, a data type, and a default value. The default value is the standard setting for the typical case: When creating a single instance, the “Value” column is pre-filled with this value and can be overwritten; in the table for multiple instances, you enter each value yourself.
As soon as the template contains a variable, the OPC Router displays the “Variables” list to the left of the design area, with the columns “Name”,” “Data type”,” and “Default Value.” There, you can maintain the default value and delete any variables you no longer need. If the variable is still bound to fields, the OPC Router will prompt you and, upon your confirmation, remove these bindings as well. You cannot create a variable in this list—this is always done at the field where it is to be used; see Creating Templates .
Instance
An instance is a specific flow generated from a template. To create one, you populate the template variables with specific values. These values apply only to this instance; to understand how a subsequent change to the template affects it, see Modifying a Template When Instances Already Exist .
Dynamic Instance
A dynamic instance is a flow that is generated at runtime based on database entries. It is suitable for scenarios in which flows are not only configured once but are later created or modified automatically. The values of the template variables are provided by the corresponding row in a database table; the values entered when creating the dynamic instance serve as the default values for empty fields. See Creating Dynamic Instances .
Function (FX)
A reusable subflow located in the template tree that is not instantiated but is called from flows; see Functions (FX).
How to Work with Templates
- Create a template and design all the fixed parts of the flow within it.
- Define template variables at the variable points.
- Create specific instances from the template.
- Put the instances into production or, if necessary, create dynamic instances at runtime.
Ways to Create Instances
Depending on the use case, there are four typical approaches:
- For individual flows, create an instance manually and enter the values directly in the dialog: Create individual instances.
- For many similar flows, fill out the value table in the dialog “Create multiple instances” or import it from a CSV or Excel file: Create multiple instances from a file.
- If the values follow a pattern, have the same table populated as a series: Create instances as a series.
- For automated scenarios, create dynamic instances at runtime using the Dynamic Instances API: Create dynamic instances.
Notes on Template Variables
Template variables are type-safe. Therefore, always use the appropriate variable type for the intended purpose.
Variable Types
| Type | Usage |
|---|---|
String | Any type of text, such as data point paths, table names, or topic names. |
Int32 | Integers, such as a machine ID. |
Single | Floating-point numbers, such as a threshold value. |
DateTime | A point in time consisting of a date and time. |
TimeOffset | A time period, such as the cycle of a time trigger. The permitted units are listed at Time specifications in template variables . |
Boolean | A Boolean value. |
| Name of a plug-in | Reference to a connection for this plug-in. Each plug-in, for which there may be multiple connections, appears in the list as a separate type with its name. Specify the name of the connection as the value. |
Rules for Types
- A field accepts only template variables of the same type. The entry “Add new variable” in the field menu therefore immediately creates a variable of the appropriate type; see The field menu in the template .
- A combination of multiple template variables or a combination of template variables and additional text within an expression is only possible with variables of the type “String”, for example
bp=Objects/2:{Machine}/2:SPS/2:Heater1;. Variables of all other types completely replace the field value. - A template variable that you create in the expression editor is always of the type
String. - When creating an instance, the OPC Router replaces the placeholders with the entered values. A placeholder for which there is no template variable remains unchanged in the field.
The following pages provide step-by-step instructions on how to create templates, generate instances, and use dynamic instances.
Modifying a Template When Instances Already Exist
Instances do not store their own flow; they only store the name of the template and the values of its variables. The flow is rebuilt from the current template each time it is loaded. This explains the effect of a change to the template:
- A modified flow applies to all instances—after publication.
- A newly created template variable receives the default value from the template in every instance.
- A variable removed from the template disappears from all instances, along with the value entered there.
- The values of all remaining variables remain in the instances.
The “Put all instances into production” button in the template toolbar opens the Publish view with the instances of this template preselected; it is grayed out as long as the template has no instances. For information on how to change the values of individual instances later, see “: Creating Individual Instances” at.
Templates and Functions (FX)
In addition to the templates, the template tree also contains functions (FX). You can create a function by clicking the button with the cube icon in the toolbar or by selecting the context menu item “New function (FX)”; it is created in the currently selected template group.
The two building blocks serve different purposes:
- A template is appropriate when entire flows are identical except for individual values. You use it to create instances.
- A function is appropriate when only a portion of the process is identical across otherwise different flows. It is called from within a flow via the transfer object “Function (FX)” and is not instantiated.
Both can be combined: A template can also call a function. For more information on functions, see Functions (FX).
Dynamic instances do not receive execution copies of their subroutines upon publication; a function call or a branch in a dynamic instance cannot be executed at runtime.
Variables from subprocesses
If a template contains sub-processes —branches of a condition, an error handling block, a Change Gate, or a function call—these sub-processes bring their own variables with them. The instance dialog queries each of these variables for which no value has been set at the call site; they then appear alongside the template’s own variables—both when creating a single instance and as a column in “Create multiple instances” and in the file from “Download template”.
If the value at the call site is empty, the variable is additionally offered there as a wireable input item. The instance value replaces the variable’s default value; for information on which values apply in what order when publishing and how a wired variable handles them, see Sub-processes in Templates .
If a variable in a sub-flow has the same name as a template variable, the dialog prompts for it only once; the instance value then also applies in the sub-flow, provided that no fixed value is entered at the call site.
Names and Uniqueness
Templates, instances, and template variables each have their own naming conventions. When renaming or moving items in the tree, as well as when creating them from a file or table, the OPC Router checks these rules and rejects any name that violates them. The dialog for creating a single or dynamic instance only checks whether the name is empty or already in use in the destination folder—you must ensure compliance with the other rules yourself.
| What | Rule |
|---|---|
| Name of a template or an instance | Must be unique within the folder containing the entry—relative to the other entries and the subfolders of that same folder. The name must not be empty, must not contain a backslash \, and must be no longer than 1,000 characters. The same name may appear again in a different folder. When creating from a file, the folder is specified in the column value; see Create multiple instances from a file . |
| Name of a template variable | Unique within a single template; the same name may appear again in another template. The comparison is case-sensitive, so Anlage and anlage are two different variables. Do not use curly braces in the name—they delimit the placeholder {Name}. |
| Name of a dynamic instance | Same as for an instance. Additionally, the characters ', [, and ] must not appear, and the table name derived from the path must be no longer than 128 characters; see Creating dynamic instances . |
If you create a template variable via the field menu, the technical name of the field is already entered as a suggestion in the “Add template variable” dialog; if it is already assigned in this template, the OPC Router appends a two-digit number to the suggestion (01, 02, …). If you enter a name that already exists in the template, the dialog will reject it with the error “A template variable with this name already exists.”.”
When renaming in the tree, the OPC Router specifies the reason for the rejection: “A Flow with the same name already exists”, “A Flow group with the same name already exists”, “The Flow name contains invalid characters.”, or “The Flow name exceeds the maximum permitted length.”. When creating a single instance, an already taken name results in the error message “The entered name is already used in this Flow group.”; case is not distinguished here.
When creating multiple dynamic instances from a file, the OPC Router does not check the two additional rules for the dynamic instance; you must ensure compliance with them yourself.