.NET RuleEngine pipeline configuration API
The RuleEngine API is a .NET library that allows you to programmatically create, load, modify, and save RuleEngine pipelines for the TwinCAT Analytics StorageProvider – without using the graphical configurator. A typical use case is the automated creation of many similar pipelines (e.g., one for each machine or plant component). You'll find an example of this in the next chapter. The key components are described below.
PipelineHandler: Managing pipelines
Central entry point. You can use it to manage your pipeline inventory.
Property | Description |
|---|---|
LocalRuleEnginePipelineTemplates | List of all locally available pipeline templates. The templates are reloaded from the local storage directory (%AppData%\Beckhoff\TwinCAT Analytics Storage Provider\LocalRuleEnginePipelineCmds, JSON files) each time they are accessed. |
Method | Description |
|---|---|
CreateRuleEnginePipeline() | Create a new, empty pipeline. |
LoadPipelineFromPipelineID(Guid) | Load an existing pipeline by its ID. |
LoadPipelineFromPath(string) | Load a pipeline from a configuration file. |
LoadPipelineFromJson(string) | Load a pipeline from a JSON string. |
LoadPipelineFromInfo(IPipelineInfo) | Load a pipeline using summary information. |
RemovePipeline(Guid) | Delete pipeline |
IPipelineInfo provides you with concise metadata about the existing pipelines (e.g., name and ID) without having to load the full configuration.
RuleEngine pipeline (IRuleEnginePipeline): The configuration
The pipeline is the container for a complete recording and processing configuration.
Property | Description |
|---|---|
PipelineAlias | A descriptive name for the pipeline. |
PipelineID | Unique GUID of the pipeline. |
StorageProvider | GUID of the StorageProvider on which the pipeline runs. |
MqttInputSources | All MQTT InputSources included. |
Rules | All rules included at the pipeline level. |
Recordings | All recordings included at the pipeline level. |
Method | Description |
|---|---|
SetPipelineAlias(string alias) | Sets the display name of the pipeline. |
SetPipelineID(Guid pipelineID) | Sets the unique ID of the pipeline. When saving, the ID determines whether an existing pipeline is overwritten (same ID) or created as a copy (new ID). |
SetStorageProvider(Guid storageProvider) | Specifies the target StorageProvider. |
AddMqttInputSource(out IMqttSource source) | Adds a new MQTT InputSource and returns it. |
AddRule(out IRule rule) | Adds a new rule at the pipeline level and returns it. |
AddRecording(out IRecording recording) | Adds a new recording at the pipeline level and returns it. |
RemoveNode(IPipelineNode node) | Removes a node (InputSource, Rule, or Recording) from the pipeline. |
SaveConfig(string directory = null) | Saves the pipeline as a JSON configuration; if no directory is specified, the default directory is used. |
ValidateConfiguration() | Checks the pipeline for completeness and consistency. |
InputSource (IMqttSource): The data source
The MQTT source describes where the data in a pipeline comes from.
Property | Description |
|---|---|
ID | Internal identifier for the node within the pipeline. |
NodeAlias | Display name of the InputSource |
Broker | GUID of the MQTT broker through which the data is received. |
Topic | MQTT topic being subscribed to. |
SystemID | GUID of the source system to which the data is assigned. |
CycleTime | Cycle time of the incoming data. |
ParentNodes | Higher-level nodes |
ChildNodes | Child nodes |
OutputSymbols | The symbols output by the node. |
Method | Description |
|---|---|
SetNodeAlias(string alias) | Sets the display name of the InputSource. |
SetBroker(Guid brokerGuid) | Specifies the MQTT broker to be used. |
SetTopic(string topic) | Sets the MQTT topic |
SetSystemID(Guid systemID) | Assigns the source to a source system. |
SetCycleTime(TimeSpan cycleTime) | Sets the cycle time for the incoming data. |
AddRule(out IRule rule) | Creates a new rule as a child node and returns it. |
AddChild(IRule rule) | Attaches an existing rule as a child node. |
CreateSymbol(string symbolName, string dataType, out IConfigSymbol symbol) | Creates a new input symbol with name and data type, and returns it. |
ValidateConfiguration() | Validates the node's configuration. |
Rule (IRule): Processing
A rule defines how the data from an InputSource is processed.
Property | Description |
|---|---|
ID | Internal identifier for the node within the pipeline. |
NodeAlias | Display name of the rule |
Nodes | All nodes contained in the rule (conditions and actions). |
Trigger | All triggers associated with the rule. |
TriggerEnable | Specifies whether the rule is executed in response to a trigger. |
DataProcessingRange | The timeframe of data to be processed when the rule is triggered. |
ParentNodes | Higher-level nodes |
ChildNodes | Child nodes |
OutputSymbols | The symbols output by the node. |
Method | Description |
|---|---|
SetNodeAlias(string alias) | Sets the display name of the rule. |
AddCondition<T>() | Adds a condition of the specified type (e.g., IEventbasedCondition, ITimebasedCondition) and returns it. |
AddAction<T>() | Adds an action of the specified type (e.g., IMinMaxAvgAction, IDownsamplingAction) and returns it. |
RemoveNode(IRuleNode node) | Removes a condition or action from the rule. |
AddTrigger<T>() | Adds a trigger of the specified type (e.g., ITimebasedTrigger, IEventbasedTrigger) and returns it. |
RemoveTrigger(ITrigger trigger) | Removes a trigger from the rule. |
SetDataProcessingRange(TimeSpan dataProcessingRange) | Specifies the timeframe to be processed. This is only possible if a recording serves as the InputSource for the rule. |
SetUseAllData() | Specifies that all generated data is processed rather than only data from a limited timeframe. This is only possible if a recording serves as the InputSource for the rule. |
AddRecording(out IRecording recording) | Creates a new recording under the rule and returns it. |
AddChild(IRecording recording) | Attaches an existing recording as a child node. |
RenameSymbol(IConfigSymbol symbol, string name) | Assigns a different name to an output symbol of the rule. |
ResetSymbolName(IConfigSymbol symbol) | Resets a previously changed symbol name to its original name. |
ValidateConfiguration() | Validates the node's configuration. |
Recording (IRecording): The recording
The recording specifies which data is written to which storage.
Property | Description |
|---|---|
ID | Internal identifier for the node within the pipeline. |
NodeAlias | Display name of the recording |
RecordName | Record name of the recording |
StorageGuid | GUID of the target storage to which data is written. |
CycleTime | Cycle time used for recording. |
CleanupMode | Active cleanup strategy (no cleanup, time-based, or data-volume-based) |
CleanupInterval | Size of the ring buffer for time-based cleanup. |
CleanupSizeMB | Maximum data volume in MB for data-volume-based cleanup. |
InputSymbols | Available input symbols from the higher-level node that can be selected. |
ParentNodes | Higher-level nodes |
ChildNodes | Child nodes |
OutputSymbols | The symbols output by the node. |
Method | Description |
|---|---|
SetNodeAlias(string alias) | Sets the alias for the recording. |
SetRecordName(string recordName) | Sets the record name. |
SetStorageGuid(Guid storageGuid) | Specifies the target storage. |
SetCustomCycleTime(TimeSpan cycleTime) | Sets a different cycle time. |
RemoveCustomCycleTime() | Removes the deviating cycle time; the original cycle time is restored. |
SetTimebasedCleanup(TimeSpan ringbufferSize) | Enables time-based cleanup with the specified ring buffer size. |
SetDatabasedCleanup(int cleanupSizeMB) | Enables data-volume-based cleanup with the specified maximum size in MB. |
RemoveCleanup() | Disables automatic cleanup. |
UseSymbol(IConfigSymbol symbol) | Includes a single symbol in the recording. |
RemoveSymbol(IConfigSymbol symbol) | Removes a single symbol from the recording. |
UseAllSymbols(int lastConditionID = 0) | Includes all available symbols. Optionally, you can specify the ID of a condition so that all symbols associated with that condition are recorded. |
RemoveAllSymbols() | Removes all selected symbols. |
AddRule(out IRule rule) | Creates a downstream rule below the recording and returns it. |
AddChild(IRule rule) | Creates a new rule as a child node and returns it. |
ValidateConfiguration() | Validates the node's configuration. |