Document toolboxDocument toolbox

State Evaluator

Description

This unit is a Processor unit.

It is used to coordinate the joint activity of a subset of units of a flow. It has a set of states and rules. These rules allow changing the state according to the reception of events or the evaluation of certain expressions.

The rules are added in the unit configuration. The states are not listed explicitly; they are inferred of the ones that participate in the rules. The rules may also be used to define the unit input ports (which activate the rules) and output ports (which notify the activation of the rules).

The rules have antecedents and consequents:

  • The antecedents may be the following: the unit is in a certain state, a new event arrives (optional), or certain conditions are satisfied (optional).

  • The consequents may be the following: changing to a different state or emitting an event through an output port (optional).

When the unit finds active rules, it chooses the first more complex one, emits an event through an output port (if it has one), and changes to the destination state. The rules are evaluated in a specific order: a rule with a test is more complex than another one without a test.

A rule can be fired after the unit consumes multiple events. Even if the rules consume only some of them, the rule fired will consume only one.

Every time an event is emitted, it can be enriched with the following information:

  • Date when the rule fired.

  • Date of the initial state of the rule.

  • Date of the destination state of the rule.

Configuration

After dragging this unit into the Flow canvas, double-click it to access its configuration options. The following table describes the configuration options of this unit:

Tab

Field

Description

Tab

Field

Description

General

Name

Enter a name for the unit. It must start with a letter, and cannot contain spaces. Only letters, numbers, and underscores are allowed.

Description

Enter a description detailing the scope of the unit.

Polling time interval

Time for the polling interval (in milliseconds).

Language

Language in which expressions/statements are written.

Initial state

The initial state of the execution. If it is blank, the default value will be __INITIAL__

Rule name field

The name of the field that would contain the rule name in the output events, if any output port is defined.

From state name field

The name of the field that would contain the previous state in the output events, if any output port is defined.

To state name field

The name of the field that would contain the next state in the output events, if any output port is defined.

Rules

Click the + icon to add rules as required. Each rule has the parameters described next to this.

You can also reorder the fields using drag and drop.

Name

Enter a unique name for the rule. 

When

Enter the details for the rule antecedent:

  • State - Enter the state that will cause the rule execution.

  • Input port - Name of the input port that will receive events that will cause the rule execution (optional). 

  • Test - Condition that executes the rule (optional). You can use event fields with the syntax event.[field]

Trigger

Enter the details for the rule consequent:

  • State - Enter the state to be applied after the rule execution.

  • Output port - Name of the outport port that will emit events after the rule is executed (optional).

Input ports

You can optionally add input ports to this unit if required. Ports are added through the creation of rules. See more info above.

Output ports

You can optionally add output ports to this unit if required. Ports are added through the creation of rules. See more info above.

Example

Imagine you wish to create a Flow to enrich a Lookup table with username data every time new data is loaded compared to the previous day. For this, we will use a State Evaluator unit to compare the results with those in the lookup unit and reload new events.

First, we will add a State Controller unit to define the rules.

In the General tab of the properties, set the initial state to _ _INITIAL_ _

In the Rules tab, we need to configure the input and output ports as follows:

When the state is _ _INITIAL_ _, trigger LOADING to the load output port

When the state is LOADING via the load input port, trigger WORKING to the work output port

To add the fields containing the timestamps to compare the current time with one day ago, we will use a Map unit.

In the Fields to add tab of the properties, add the expressions to check for data at the current time, as well as one day ago:

One day ago:

Current time:

Link the out output port to the in input port of a Devo Full Query unit.

In the properties, enter the query to check for usernames in the Query field:

from siem.logtrust.web.activity group every - by username

Next, we need to add another Devo Full Query unit to the Flow to enrich the username data with the timestamp information:

from siem.logtrust.web.activity select eventdate, username

Now we add the Lookup unit to receive this data.

In the properties, we must specify the key - value fields to look for:

Finally, we need to specify the links. The order here is important.

The State Evaluator will first send events from the load port to the Map unit and then to the Devo Full Query unit. This unit will then signal to the lookup unit to first begin, and then clear any existing data. For this, we need to add two links from the init out port of the Devo Full Query in the following order:

Once the lookup is clear and ready, it can receive data from the data port of the Devo Full Query to the update port of the Lookup.

To signal the Lookup to finish collecting data and initiate the comparison of the State Evaluator for the next flow of data, we need to add two links from the end output port of the Devo Full Query unit. Again, the order is important:

The State Evaluator has now been signalled to begin loading new events via the load input port. Link the work output port to the do input port of the Devo Managed Query containing the timestamp username values. From this unit, link the data output port to the in port of the Lookup unit to enrich it with this working data.

Download this example

You can try this flow by downloading the following JSON file and uploading it to your domain using the Import option: