3. Using flow builder

This tutorial will show how to properly use flow builder to process messages and events generated by devices.

Note

  • Who is this for: entry-level users
  • Level: basic
  • Reading time: 15 min

3.1. Dojot nodes

3.1.1. Device Event in

device_node

This node specifies that messages received from or sent to a particular device. The message created by this node is somewhat different than the one created by DeviceIn node:

{
    "data": {
        "attrs": {
            "temperature": 10,
            "some-static-attr": "efac"
        }
    }
}

This structure can be referenced in nodes like Template such as:

Sample message {{payload.data.attrs.temperature}}

To configure the device in node, a window like Fig. 3.1 will be displayed.

devicein_node_cfg

Fig. 3.1 : Device in configuration window

Fields:

  • Name (optional): Name of the node
  • Device (required): The dojot device that will trigger the flow
  • Events (required): Select which events will trigger this flow. The Actuation option will select actuation messages (those sent to the device) and Publication will select all messages published by the device.

Note

If the the device that triggers a flow is removed, the flow won’t work anymore.

3.1.2. Device template event in

devicetemplatein_node

This node will specifies that messages from devices composed by a particular template will trigger this flow. For instance, if the device template set in this node is template A, all devices that are composed with template A will trigger the flow. For example: device1 is composed by templates [A,B], device2 by template A and device3 by template B. Then, in that scenario, only messages from device1 and device2 will initiate the flow, because template A is one of the templates that compose those devices.

devicetemplatein_node

Fig. 3.2 : Device template in configuration window

Fields:

  • Name (optional): Name of the node.
  • Device (required): The dojot device that will trigger the flow.
  • Events (required): Select which event will trigger this flow. Creation, Update, Removal are related to device management operations. Actuation will trigger this flow in case of sending actuation messages to the device and Publication will trigger this flow whenever a device publishes a message to dojot.

3.1.3. Multi device out

deviceout_node

Device out will determine wich device (or devices) will have its attributes updated on dojot according to the result of the flow. Bear in mind that this node doesn’t send messages to your device, it will only update the attributes on the platform. Normally, the chosen device out is a virtual device, which is a device that exists only on dojot.

deviceout_node_cfg

Fig. 3.3 : Device out config window

Fields:

  • Name (optional): Name of the node.
  • Action (required): Which node will receive the update. Options are:
    • The device that triggered the flow: this will update the same device that sent the message which triggered this flow.
    • Specific device(s): which nodes that will receive the update.
    • Device(s) defined during the flow: which nodes that will receive the update. This is referenced by a list of values, just as with output values (msg.list_of_devices).
  • Device (required): Select “The device that triggered the flow” will make the device that was the entry-point be the end-point of the flow. “Specific device” any chosen device wil be the output of the flow and “a device defined during the flow” will make a device that the flow selected during the execution the endpoint.
  • Source (required): Data structure that will be mapped as message to device out

3.1.4. Multi actuate

actuate_node

Actuate node is, basically, the same thing of device out node. But, it can send messages to a real device, like telling a lamp to turn the light off and etc.

actuate_node_cfg

Fig. 3.4 : Actuate configuration

Fields:

  • Name (optional): Name of the node.
  • Action (required): which device a message will be sent to. Options are:
    • The device that triggered the flow: this will send a message to the same device that sent the message which triggered this flow.
    • Specific device(s): which node the message will be sent to.
    • Device(s) defined during the flow: which nodes the message will be sent to. This is referenced by a list of values, just as with output values (msg.list_of_devices).
  • Device (required): Select “The device that triggered the flow” will make the device that was the entry-point be the end-point of the flow. “Specific device” any chosen device wil be the output of the flow and “a device defined during the flow” will make a device that the flow selected during the execution the endpoint.
  • Source (required): Data structure that will be mapped as message to device out

3.1.5. http

http_node

This node sends an http request to a given address, and, then, it can forward the response to the next node in the flow.

httpin_node

Fig. 3.5 : Device template in configuration window

Fields:

  • Method (required): The http method (GET, POST, etc…).
  • URL (required): The URL that will receive the http request
  • Request body (required): Variable that contains the request body. This value can be assigned to the variable using the template node, for example.
  • Response (required): Variable that will receive the http response.
  • Return (required): Type of the return.
  • Name (required): Name of the node.

3.1.6. ftp

http_node

This node sends or retrieves a file from/to a FTP server. When uploading a file, its name can be set by setting the “Filename” field in the same way as other output variables (it should refer to a variable set in the flow). The file encoding will set the file enconding, which could be, for instance, “base64” or “utf-8”.

httpin_node

Fig. 3.6 : Device template in configuration window

Fields:

  • Method (required): The FTP action to be taken (PUT, GET).
  • URL (required): the FTP server
  • Authentication (required): Username and password to access this server.
  • File name (required): Variable containing the file name to be uploaded or downloaded.
  • File content (required): In case of uploading a file, this variable should hold the file content.
  • File encoding (required): How the file is encoded
  • Response (required): Variable that will receive the FTP response (or file)

3.1.7. notification

http_node

This node sends a user notification to other services in dojot. This might be useful to generate application notifications that could be consumed by a front-end application. The user can set a static message to be sent or, as other output nodes, configure a variable set in a previous node which will be resolved at runtime. Also, metadata can be added to the message: it can be a simple key-value object containing arbitrary data.

httpin_node

Fig. 3.7 : Device template in configuration window

Fields:

  • Name (optional): Name of the node
  • Message (required): Static, if the notification should contain a static text, or dynamic, which will enable a variable to be set as output to this node. This variable will be substituted in runtime.
  • Value (required): message content (either static text or a variable reference).
  • Metadata (required): variable reference containing a simple dictionary (key-value pairs) containing the metadata to be added to the message

3.1.8. Change

change_node

Change node is used to copy or assign values to an output, i. e., copy values of a message attributes to a dictionary that will be assigned to virtual device.

change_node_cfg

Fig. 3.8 : Change configuration

Fields:

  • Name (optional): Name of the node
  • msg (required): Definition of the data structure that will be sent to the next node and will receive the value set on the to field
  • to (required): Assignment or copy of values

Note

More than one rule can be assign by clicking on +add below the rules box.

3.1.9. Switch

switch_node

The Switch node allows messages to be routed to different branches of a flow by evaluating a set of rules against each message.

switch_node_cfg

Fig. 3.9 : Switch configuration

Fields:

  • Name (optional): Name of the node
  • Property (required): Variable that will be evaluated
  • Rule box (required): Rules that will determine the output branch of the node. Also, it can be configured to stop checking rules when it finds one that matches other or check all the rules and route the message to the corresponding output.

Note

  • More than one rule can be assign by clicking on +add below the rules box.
  • The rules are mapped one-to-one to the output conectors. Then the first rule is related to the first output, the second rule to the second output and etc…

3.1.10. Template

Note

Despite the name, this node has nothing to do with dojot templates

template_node

This node will assign a value to a target variable. This value can be a constant, the value of an attribute that came from the entry device and etc…

It uses the mustache template language. Check Fig. 3.10 as example: the field a of payload will be replaced with the value of the payload.b

template_node_cfg

Fig. 3.10 : Template configuration

Fields:

  • Name (optional): Name of the node
  • Set Property (required): Variable that will receive the value
  • Format (required): Format template will be writen
  • Template (required): Value that will be assigned to the target variable set on Set property
  • Output as (required): The format of the output

3.1.11. Geofence

geofence_node

Select an interest area to determine wich devices will activate the flow

geofence_node_cfg

Fig. 3.11 : Geofence configuration

Fields:

  • Area (required): Area that will be selected. It can be chosen with an square or with a pentagon.
  • Filter (required): Which side of the area will be picked: inside or outside the marked area in the field above.
  • Name (optional): Name of the node

3.1.12. Get Context

getcontext_node

This node is used to get a variable that is in the context and assign its value to a variable that will be used in the flow.

getcontext_node_cfg

Fields:

  • Name (optional)*: Name of the node
  • Context layer (required)*: The layer of the context that que variable is at
  • Context name (required)*: The variable that is in the context
  • Context content (required)*: The variable in the flow that will receive the value of the context

3.1.13. Deprecated nodes

These nodes are scheduled to be removed in future versions. They will work with no problems with current flows.

3.1.13.1. Device in

device_node

This node determine an especific device to be the entry-point of a flow. To configure the device in node, a window like Fig. 3.13 will be displayed.

devicein_node_cfg

Fig. 3.13 : Device in configuration window

Fields:

  • Name (optional): Name of the node
  • Device (required): The dojot device that will trigger the flow
  • Status (required): exclude device status changes will not use device status changes (online, offline) to trigger the flow. On the other hand, include devices status changes will use these status to trigger the flow.

Note

If the the device that triggers a flow is removed, the flow becomes invalid.

3.1.13.2. Device template in

devicetemplatein_node

This node will make that a flow get triggered by devices that are composed by a certain template. If the device template that is configured in device template in node is template A, all devices that are composed with template A will trigger the flow. For example: device1 is composed by templates [A,B], device2 by template A and device3 by template B. Then, in that scenario, only messages from device1 and device2 will initiate the flow, because template A is one of the templates that compose those devices.

devicetemplatein_node

Fig. 3.14 : Device template in configuration window

Fields:

  • Name (optional): Name of the node.
  • Device (required): The dojot device that will trigger the flow.
  • Status (required): Choose if devices status changes will trigger or not the flow.

3.1.13.3. Device out

deviceout_node

Device out will determine wich device will have its attributes updated on dojot according to the result of the flow. Bear in mind that this node doesn’t send messages to your device, it will only update the attributes on the platform. Normally, the chosen device out is a virtual device, which is a device that exists only on dojot.

deviceout_node_cfg

Fig. 3.15 : Device out config window

Fields:

  • Name (optional): Name of the node.
  • Device (required): Select “The device that triggered the flow” will make the device that was the entry-point be the end-point of the flow. “Specific device” any chosen device wil be the output of the flow and “a device defined during the flow” will make a device that the flow selected during the execution the endpoint.
  • Source (required): Data structure that will be mapped as message to device out

3.1.13.4. Actuate

actuate_node

Actuate node is, basically, the same thing of device out node. But, it can send messages to a real device, like telling a lamp to turn the light off and etc.

actuate_node_cfg

Fig. 3.16 : Actuate configuration

Fields:

  • Name (optional): Name of the node.
  • Device (required): A real device on dojot
  • Source (required): Data structure that will be mapped as message to device out

3.2. Learn by examples

3.2.1. Using http node

Imagine this scenario: a device sends an username and a password, and from these attrs, the flow will request to a server an authentication token that will be sent to a virtual device that has a token attribute.

using_http_node_flow

Fig. 3.17 : Flow used to explain http node

To send that request to the server, the http method should be a POST and the parameters should be within the requisition. So, in the template node, a JSON object will be assigned to a variable. The body (parameters username and password) of the requisition will be assigned to the payload key of the JSON object. And, if needed, this object can have a headers key as well.

using_http_node_template

Fig. 3.18 : Template node configuration

Then, on the http node, the Requisition field will receive the value of the object created at the template node. And, the response will be assigned to any variable, in this case, this is msg.res .

Note

If UTF-8 String buffer is chosen in the return field, the body of the response body will be a string. If JSON object is chosen, the body will be an object.

using_http_node_http

Fig. 3.19 : Template node configuration

As seen, the response of the server is req.res and the response body can be accessed on msg.res.payload. So, the keys of the object that came on the responsy can be accessed by: msg.res.payload.key. On figure Fig. 3.20 the token that came in the response is assigned to the attribute token of the virtual device.

using_http_node_change

Fig. 3.20 : Template node configuration

using_http_node_deviceout

Fig. 3.21 : Device out configuration

Then, the result of the flow is the attribute token of the virtual device be updated with the token that came in the response of the http request:

using_http_node_result

Fig. 3.22 : Device updated

3.2.2. Using geofence node

A good example to learn how geofence node works ia studying the flow below:

using_geofence_node_flow

Fig. 3.23 : Flow using geofence

The geofence node named in area is set like seem in Fig. 3.24. The only thing that diffs the geofence nodes in area from out of the area is the field Filter that, in the first, is configured to only points inside and only points outside in the second, respectively.

using_geofence_node_geofence

Fig. 3.24 : Geofence node configuration

Then, if the device that is set as device in sends a messagem with a geo attribute the geofence node will evaluate the geo point acoording to its rule and if it matches the rule, the node forward the information to the next node and, if not, the execution of the branch, which has the geofence that the rule didn’t match, stops.

Note

To geofence node work, the messege received should have a geo attribute, if not, the branches of the flow will stop at the geofence nodes.

Back to the example, if the car sends a message that he is in the marked area, like { "position": "-22.820156,-47.2682535" }, the message received in device out will be “Car is inside the marked area”, and, if it sends {"position": "0,0"} device out will receive “Car is out of the marked area”

using_geofence_node_template

Fig. 3.25 : Template node configuration if the car is in the marked area

using_geofence_node_result

Fig. 3.26 : Output in device out