Building blocks of the flow editorFlow Elements
This chapter provides references for available flow elements. Flow elements are split into three groups that describe their general purpose.
These groups are:
Each element will be accompanied by a small application example. Elements shown with green title bars are starting elements of the Flow snippet. Further explanations are provided in the following articles.
Action Elements
Elements that have an active role within a flow and determine the majority of the execution flow are referred to as Action Elements.
Action
The Action element represents an action within the flow. It is one of the viable start node types and upon being called, the given script will be evaluated. When a source of data is linked to this element, it’s value will be made available in the scripting context under the keyword data.
Parameters
| Name | Description |
|---|---|
Prev | Accepts another element’s Next socket |
Next | Connects to another element’s Prev socket |
DataSource | Accepts another element’s DataTarget |
DataTarget | Connects to another element’s DataSource |
Script | Given script will be executed with data in it’s context. |
Aggregate
The Aggregate element is used to aggregate data within loops in the Flow Engine. It works similar like reduce functions in other languages. In it’s scripting context the keywords data and currentData become available. Data represents the initial value for the aggregation and currentData contains the dataset of the current loop iteration. The script must then process and return the aggregation result and in the next iteration data will contain the result of the previous aggregation.
Parameters
| Name | Description |
|---|---|
Prev | Accepts another element’s Next socket |
Next | Connects to another element’s Prev socket |
CurrentData | Accepts another element’s DataSource. Given data is made available as currentData within the scripting context. |
Data | Accepts another element’s DataSource. Given data is start value of the aggregation and used to set it’s initial value. |
DataTarget | Connects to another element’s DataSource socket. Contains the aggregated data of the element. |
ExceptionHandler | If connected to an ExceptionHandler, exceptions thrown in the scripting context will be handled by the referenced handler. |
Script | context used to aggregate the data. Return value will be written to the element’s data. |
Call
The Call element allows a flow to be called from a flow. It is a flow based alternative to calling the scripting function flow().
Parameters
| Name | Description |
|---|---|
Prev | Accepts another element’s Next socket |
Next | Connects to another element’s Prev socket |
Parameters | Accepts multiple ParameterInput element connections |
DataTarget | Connects to another element’s DataSource |
Flow | Allows the selection of a Flow to call with this element |
ExceptionHandler
Exception handling within Flows can be realized using the ExceptionHandler element. If a Flow contains such element and the element is not connected via a red exception handling relationship, it will act as a global exception handler for all uncaught exceptions thrown within the flow. If an ExceptionHandler is connected to a supported element via a red connecting, it will act as handler for exceptions thrown by related elements.
Parameters
| Name | Description |
|---|---|
Next | Connects to another element’s Prev socket |
HandledNodes | Accepts connections from other element’s ExceptionHandler sockets. |
DataTarget | Connects to another element’s DataSource socket. Passes on the exception details. |
Filter
The Filter element allows easy filtering of collections. On evaluation each element of the connected collection will be checked against the connected logic elements and only if those return true, the specific element is allowed to remain in the collection. Once evaluated the Filter element will return the filtered collection on it’s data output socket.
Parameters
| Name | Description |
|---|---|
Prev | Accepts another element’s Next socket |
Next | Connects to another element’s Prev socket |
DataSource | Accepts another element’s DataTarget |
DataTarget | Connects to another element’s DataSource |
Condition | Acceps connections from logic elements and uses connected logic to determine whether an element of the given collection gets filtered |
Log
The Log element allows to write to the Structr log. It will additionally prefix the given message content with the current flow name and the log element’s UUID.
Parameters
| Name | Description |
|---|---|
Prev | Accepts another element’s Next socket |
Next | Connects to another element’s Prev socket |
DataSource | Accepts another element’s DataTarget |
Script | Given script will be executed as StructrScript with data in it’s context. |
Loop
The Loop or ForEach element are used to iterate over collections of data.
Parameters
| Name | Description |
|---|---|
Prev | Accepts another element’s Next socket |
Next | Connects to another element’s Prev socket |
DataSource | Accepts another element’s DataSource. Represents the collection to iterate. |
DataTarget | Accepts another element’s DataSource. Contains the object of the current iteration. |
FirstAction | Connects to another element’s Prev socket. Represents the first node to be called for each iteration of the collection. |
Return
The Return element allows a flow to return results. By default the element will return the data provided by the data input relationship. Supplying a custom script allows the transformation or post-processing of the data before returning it.
Parameters
| Name | Description |
|---|---|
Prev | Accepts another element’s Next socket |
DataSource | Accepts another element’s DataSource |
Script | Given script will be executed as StructrScript with data in it’s context. If no script is given, Return will just use the given data as return value. |
Data Elements
Data Elements are a group of passive flow components that provide data in some form.
Constant
The Constant element represents a data source with constant value.
Parameters
| Name | Description |
|---|---|
DataTarget | Connects to another element’s DataSource |
Value | Constant value that will be passed as data |
CollectionDataSource
The CollectionDataSource is used to provide collections. With no connected data sources, it will pass on an empty collection and every instance of given data will be added as element of the collection.
Parameters
| Name | Description |
|---|---|
DataTarget | Connects to another element’s DataSource |
DataSources | Accepts multiple DataTarget connections |
DataSource
The DataSource element represents a passive source of data. It can not directly be evaluated by the general execution flow, but instead it will be evaluated on demand by connected nodes, when the data is requested.
Parameters
| Name | Description |
|---|---|
DataSource | Accepts another element’s DataSource |
DataTarget | Connects to another element’s DataSource |
Script | Given script will be executed as StructrScript with data in it’s context. |
First
The First element can be used as a shortcut to quickly retrieve a collection’s first element.
Parameters
| Name | Description |
|---|---|
Prev | Accepts another element’s Next socket |
Next | Connects to another element’s Prev socket |
DataSource | Accepts another element’s DataSource |
DataTarget | Connects to another element’s DataSource |
GetProperty
The GetProperty element extracts a property referenced by key from a given object.
Parameters
| Name | Description |
|---|---|
DataTarget | Connects to element’s DataSource |
NodeSource | Accepts connection from another element’s DataTarget and expects a node |
PropertyNameSource | Accepts connections from DataTarget sockets and represents the name of the property to extract |
PropertyName | Represents the name of the property to extract. Has lower priority than a connected PropertyNameSource. |
KeyValue
The ObjectDataSource is used to build objects from a number of connected KeyValue elements.
Parameters
| Name | Description |
|---|---|
DataTarget | Connects to a ObjectDataSource’s DataSource. |
DataSource | Accepts another element’s DataTarget. |
Key | Key identifier under which given data will be added to the object |
ObjectDataSource
The ObjectDataSource is used to build objects from a number of connected KeyValue elements.
Parameters
| Name | Description |
|---|---|
DataTarget | Connects to another element’s DataSource |
KeyValueSources | Accepts multiple DataTarget connections from KeyValue elements. |
ParameterDataSource
The ParameterDataSource element is used to retrieve parameters supplied to a flow.
Parameters
| Name | Description |
|---|---|
DataTarget | Connects to element’s DataSource |
Key | Key for the parameter to retrieve |
ParameterInput
The ParameterInput element is used to supply a Call element with parameters.
Parameters
| Name | Description |
|---|---|
Call | Connects to a Call’s Parameters socket. |
DataSource | Accepts another element’s DataTarget as value for the parameter |
Key | Key for the represented parameter |
Store
The Store element is a two way data storage element used to store or retrieve data within the current flow’s context.
Parameters
| Name | Description |
|---|---|
Prev | Accepts connection from another element’s Next socket |
Next | Connects to another elements Prev socket |
DataTarget | Connects to element’s DataSource |
DataSource | Accepts connection from another element’s DataTarget |
Operation | Switches between storing or receiving data. When receiving DataSource is ignored and when storing DataTarget is ignored. |
Key | Key under which to store or from which to retrieve data |
TypeQuery
The TypeQuery allows to easily query data by Type and features an optional QueryBuilder to specify additional query operations.
Parameters
| Name | Description |
|---|---|
Type | Allows to select a type to query |
DataSource | Accepts connections from DataTarget outputs and makes a data object available in scripting contexts opened within attribute queries. |
Logic Elements
Logic elements are a special group of components that are used to construct logic expressions used in conjunction with other flow elements. Examples of this are Decision or Filter elements.
And
The And element performs a boolean and operation on all given logic data sources.
Parameters
| Name | Description |
|---|---|
DataSources | Accepts multiple logic node DataTarget connections |
Result | Connects to a logic node DataSource or a Decision Condition |
Comparison
The Comparison element accepts multiple data sources and compares them with given operator against the given value. The result will be the total result of all comparisons made.
Parameters
| Name | Description |
|---|---|
DataSources | Accepts multiple DataTarget connections. Data that will be compared. |
ValueSource | Accepts DataTarget connection. Value that given data will be checked against. |
Operation | Defines boolean operator to be applied. |
Result | Connects to a logic node DataSource or a Decision Condition |
Condition
The Condition element evaluates given script to create a logic data result. The script must return a boolean value.
Parameters
| Name | Description |
|---|---|
DataSource | Accept another element’s DataTarget |
ScriptSource | Accepts another element’s DataTarget. Can be used to dynamically supply a script |
Script | Supplies script given for evaluation. Only used when ScriptSource is not connected |
DataTarget | Connects to a logic node DataSource or a Decision Condition |
ExceptionHandler | Connects to an ExceptionHandler’s HandledNodes socket |
Decision
The Decision element allows to split execution paths by deciding for a path depending on the given condition elements.
Parameters
| Name | Description |
|---|---|
Prev | Accepts a connection from a Next socket |
Condition | Accepts a connection from a Result socket |
Next If True | Connects to a node’s Prev socket. Executed when condition is true |
Next If False | Connects to a node’s Prev socket. Executed when condition is false |
IsTrue
IsTrue is a simple logic element that checks if given data is the equivalent of true.
Parameters
| Name | Description |
|---|---|
DataSource | Accepts another element’s DataSource |
DataTarget | Connects to another logic element’s DataSource |
Not
The Not element negates a given logic data source.
Parameters
| Name | Description |
|---|---|
DataSources | Accepts multiple logic node DataTarget connections |
Result | Connects to a logic node DataSource or a Decision Condition |
NotEmpty
The NotEmpty element accepts multiple data sources and evaluates whether they are empty or not. This is used with collections and strings.
Parameters
| Name | Description |
|---|---|
DataSources | Accepts multiple DataTarget connections |
Result | Connects to a logic node DataSource or a Decision Condition |
NotNull
The NotNull element accepts multiple data sources and evaluates whether they are not null.
Parameters
| Name | Description |
|---|---|
DataSources | Accepts multiple DataTarget connections |
Result | Connects to a logic node DataSource or a Decision Condition |
Or
The Or element performs a boolean or operation on all given logic data sources.
Parameters
| Name | Description |
|---|---|
DataSources | Accepts multiple logic node DataTarget connections |
Result | Connects to a logic node DataSource or a Decision Condition |