.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.