Basic Units in AKIRO Flows
Basic Components:
These are the building blocks to build and deploy a flow successfully.
- Node
- Configuration node
- Flow
- Context
- Message
- Wire
- Palette
- Workspace
- Sidebar
Node
A Node is the basic building block of a flow.
Nodes are triggered by either receiving a message from the previous node in a flow, or by waiting for some external event, such as an incoming HTTP request, a timer or GPIO hardware change. They process that message, or event, and then may send a message to the next nodes in the flow.
A node can have at most one input port and as many output ports as it requires.
Configuration node
A Configuration (config) Node is a special type of node that holds a reusable configuration that can be shared by regular nodes in a flow.
For example, the MQTT In and Out nodes use an MQTT Broker config node to represent a shared connection to an MQTT broker.
Config nodes do not appear in the main workspace, but can be seen by opening the Configuration nodes sidebar.
Flow
A Flow is represented as a tab within the editor workspace and is the main way to organize nodes.
The term “flow” is also used to informally describe a single set of connected nodes. So a flow (tab) can contain multiple flows (sets of connected nodes).
Context
Context is a way to store information that can be shared between nodes without using the messages that pass through a flow.
There are three types of context;
- Node - only visible to the node that set the value
- Flow - visible to all nodes on the same flow (or tab in the editor)
- Global - visible to all nodes
By default, Akiro Flows uses an in-memory Context store so values do not get saved across restarts. It can be configured to use a file-system based store to make the values persistent. It is also possible to plug-in alternative storage plugins.
Message
Messages are what pass between the nodes in a flow. They are plain JavaScript objects that can have any set of properties. They are often referred to as msg within the editor.
By convention, they have a payload property containing the most useful information.
Wire
Wires connect the nodes and represent how messages pass through the flow.
Palette
The Palette is on the left of the editor and lists the nodes that are available to use in flows.
Extra nodes can be installed into the palette based on the business request.
Workspace
The Workspace is the main area where flows are developed by dragging nodes from the palette and wiring them together.
The workspace has a row of tabs along the top; one for each flow and any subflows that have been opened.
Sidebar
The sidebar contains panels that provide a number of useful tools within the editor. These include panels to view more information and help about a node, to view debug messages and to view the flow’s configuration nodes.
Working with Flows
A flow is represented as a tab within the editor workspace and is the main way to organize nodes.Each flow can have a name, and description that is displayed in the Information sidebar.
Adding a flow
To add a new flow, click the + button in the top bar.
Editing flow properties
To edit a flow’s properties, double-click on its tab in the top bar. This will open the Flow Properties dialog.
- Properties - set the flow's name and description.
- Environment Variables - properties that are exposed as environment variables within the flow.
- To Delete the flow click on the delete button
Enabling or disabling a flow
The flow can be enabled or disabled using the toggle button in the Information sidebar . If a flow is disabled, none of the nodes it contains will be created when the flow is deployed.
Working with Sidebar
Below is the sidebar that shows information information sidebar about the flow, such as nodes added in the flow and their properties
We have options to view messages that are received by debug nodes in the flow using Debug messages sidebar
All global configurations used by the flows will be displayed in configuration nodes sidebar
The Context sidebar displays the contents of the context data store.The panel is split into three sections, one for each context scope; node, flow and global. The refresh button must be clicked to load the context contents. The Node and Flow sections both have a checkbox next to their refresh button to turn on automatic refreshing of the contents whenever the selected node or flow changes.
To Deploy the created flow use the Deploy Button at the top of the workspace above the sidebar.
Flows can be hidden in the workspace with icon besides the flow name in information sidebar
Working with Nodes
Nodes can be added to the workspace by either:
- dragging them from the palette,
- using the quick-add dialog,
Nodes are joined together by wires via their ports. A node can have at most one input port and many output ports. A port may have a label that is displayed when the mouse hovers over it. A node may specify labels, for example, the Switch node shows the rule that matches the port. The labels can also be customized in the node edit dialog.
Some nodes display a status message and icon below the node. This is used to indicate the runtime state of the node - for example, the MQTT nodes indicate if they are currently connected or not.
If a node has any undeployed changes, it displays a blue circle above it. If there are errors with its configuration, it displays a red triangle.
Some nodes include a button on either its left or right edge. These allow some interaction with the node from within the editor. The Inject and Debug nodes are the only core nodes that have buttons.
Quick-Add dialog
The Quick-Add dialog provides an easy way to add a node to the workspace wherever the mouse is, without having to drag it over from the palette.
The dialog is opened by holding the Ctrl or Command key when clicking on the workspace.
The dialog contains a complete list of all nodes available to add. It shows the five main core nodes at the top of the list, followed by any recently added nodes and finally a complete, alphabetical, list of the remaining nodes.
We can add nodes between the wires with ctrl + command after selecting the wire
Editing node properties
A node’s configuration can be edited by double clicking on the node. If multiple nodes are selected, the first node in the selection will be edited.
The edit dialog contains three tabs:
- Properties - the edit form specific to the node type being edited. If it is a function node then the js code to process the incoming message goes here.
- Description - per-node documentation formatted using Markdown.
- Appearance - options to customize the appearance of the node.
The Appearance tab provides options to:
- select whether the node’s label is shown
- change the icon of the node
- provide custom port labels.
Enabling or disabling a node
A node can be enabled or disabled using the toggle button at the bottom of the dialog. If a node is disabled it will not be created when the flow is deployed. If a disabled node sits in the middle of a flow, no messages will pass through it.
Working with Configuration nodes
A Configuration (config) Node is a special type of node that holds a reusable configuration that can be shared by regular nodes in a flow
For example, the MQTT In and Out nodes use an MQTT Broker config node to represent a shared connection to an MQTT broker.
Configuration nodes are added through the edit dialog of a node that requires the config node. It will have a field to select from the available config nodes of the required type or to add a new instance.
Clicking the button next to the select box will open the edit dialog for the selected node, or add a new instance.
The config node edit dialog only has the node properties and description tabs - as a config node has no icon or ports to set labels on.
In the footer of the dialog is an indication of how many nodes use this config node. It also provides a select box to set the scope of the config node. The scope determines which flows the config node is available on. By default it is available on all flows, but the select box can be used to make it local to just one flow.
As with normal nodes, it can also be enabled or disabled using the toggle button in the footer.
The Configuration Nodes Sidebar can be used to manage all config nodes.
Working with Wires
Nodes are wired together by pressing the left-mouse button on a node’s port, dragging to the destination node and releasing the mouse button.
Alternatively, if the Ctrl/Command key is held down, the left-mouse button can be clicked (and released) on a node’s port and then clicked on the destination. If the Ctrl/Command key remains held and the just-wired destination node has an output port, a new wire is started from that port. This allows a set of nodes to be quickly wired together.
This can also be combined with the Quick-Add dialog that is triggered by a Ctrl/Command-Click on the workspace to quickly insert new nodes and have them already wired to previous nodes in the flow.
Working with Groups
Nodes can be joined together to form a group. They can then be moved or copied as a single object within the editor.Groups can be given a border and background color, as well as an optional label.
Creating a group
To create a group, select the nodes and press ⌘-Shift-g. Group properties can be edited by double clicking the group which allows us to choose colors for the border and color to fill the group area.
Inject
The Inject node can be used to manually trigger a flow by clicking the node’s button within the editor. It can also be used to automatically trigger flows at regular intervals.
The message sent by the Inject node can have its payload and topic properties set.
The payload can be set to a variety of different types:
- a flow or global context property value
- a String, number, boolean, Buffer or Object
- a Timestamp in milliseconds since January 1st, 1970
Debug
The Debug node can be used to display messages in the Debug sidebar within the editor.
The sidebar provides a structured view of the messages it is sent, making it easier to explore the message.
Alongside each message, the debug sidebar includes information about the time the message was received and which Debug node sent it. Clicking on the source node id will reveal that node within the workspace.
The button on the node can be used to enable or disable its output. It is recommended to disable or remove any Debug nodes that are not being used.
Function
The Function node allows JavaScript code to be run against the messages that are passed through it.
Switch
The Switch node allows messages to be routed to different branches of a flow by evaluating a set of rules against each message.
The name 'switch' comes from the 'switch statement' that is common to many programming languages. It is not a reference to a physical switch. The node is configured with the property to test - which can be either a message property or a context property.
There are four types of rule:
- Value rules are evaluated against the configured property
- Sequence rules can be used on message sequences, such as those generated by the Split node
- A JSONata Expression can be provided that will be evaluated against the whole message and will match if the expression returns a true value.
- An Otherwise rule can be used to match if none of the preceding rules have matched.
The node will route a message to all outputs corresponding to matching rules. But it can also be configured to stop evaluating rules when it finds one that matches.
Mqtt In
Mqtt In node can be used as a MQTT Client which subscribes to a topic and is connected to a broker (MQTT Broker) that can either be created in this node properties or can be done via configuration nodes. On clicking the node , the properties tab opens where we can configure the MQTT Broker, Topic, Qos, Node Name etc.
Mqtt Out
Mqtt In node can be used as a MQTT Client which publishes a message to a topic and is connected to a broker (MQTT Broker) that can either be created in this node properties or can be done via configuration nodes. On clicking the node , the properties tab opens where we can configure the MQTT Broker, Topic, Qos, Node Name etc.
Kafka In
The Kafka In node acts as a kafka consumer which is connected to a kafka broker and listens to a kafka topic. A Kafka broker can be created and configured in properties of this node. On clicking the node the properties tab pops up where we can add the kafka Broker, Topic, Name etc.
Kafka Out
This acts as a kafka producer which sends messages to a particular topic. This node should also be connected to a kafka broker which can be created new or the broker that was created in the previous step can be used here. This asks for broker details, topic to send the message, ack etc.
Send Email
This node is used to send mail to the configured mail id. Usually alerts can be sent if the received payload matches a certain condition. The properties needed are mail ids to which we need to send mail, smtp server and port number.
geoFence
This uses the geolib node to check if points fall within a given region. Points are taken from the first of the following msg properties in this order:
1. msg.location.lat & msg.location.lon
2. msg.lat & msg.lon
3. msg.payload.lat & msg.payload.lon
Regions can be circular, rectangular or polygons and are drawn on to a map in the config node.
Messages can be filtered depending on if they fall inside or outside the given region or the node can append the node name to a list of areas the msg falls in (to allow the chaining of geofence nodes).
The list is stored in msg.location.isat in the following format:
And also includes the distance in meters from the center (or centroid for polygons) of the region.
WorldMap Support
If the check box is ticked then a second output port will be added to the node. The msg output from this port will include the shape of the geofence zone that can be fed directly into a WorldMap node so that it will be drawn on the geofence layer.
This output is triggered by a message with msg.payload.action set to send. This can be initiated by using the WorldMap in the node when a new browser connects.
Advanced Features
Additional nodes can be added based on the business requirement. We can have nodes for the following operations in our Akiro flows such as Parsers, Sequencing operations (Sort, Join, Split, Batch) , Http Client, Websocket Client, TCP Client, UDP Client, Json , Elastic Search Client, Filters (Regex, Cron, Json), Sql Client, Cassandra Client