3. Using flow builder

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

Nota

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

3.1. Dojot nodes

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

Nota

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

3.1.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.2 : 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.3. 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.3 : 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.4. 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.4 : 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.5. 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.5 : 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.1.6. 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.6 : 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

Nota

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

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

Nota

  • 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.8. Template

Nota

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.8 as example: the field a of payload will be replaced with the value of the payload.b

template_node_cfg

Fig. 3.8 : 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.9. Email

email_node

Sends an e-mail for a given address.

email_node_cfg

Fig. 3.9 : Email configuration

Fields:

  • From (required): The source email.
  • To (required): Destination email.
  • Server (required): The server of the email destination.
  • Subject (required): Subject of the email.
  • Body (required): Message on the email. The message can be writen in a variable using the template node, for example.
  • Name (optional): Name of the node.

3.1.10. Geofence

geofence_node

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

geofence_node_cfg

Fig. 3.10 : 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.11. 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.2. Learn by examples

3.2.1. Using template and email nodes

To explain these nodes, the flow below will be used:

using_email_node_flow

Fig. 3.12 : Flow using template and email nodes

Wonder a system that sends an email to somebody when an order arrive at his mail box. The email would be sent with the name of the sender, his phone number and the content of the order. A device with the order finder template has the attributes: sender, phone and content.

The template node will fill the message with the attributes that came in the message. The attributes sent by the entry-point device can be accessed on the variable payload. So, using the mustache template language, the node configuration would be like Fig. 3.13.

using_email_node_template

Fig. 3.13 : Template configuration

Then, the email body on the email node should be assigned to the variable that is on the field Set property on Fig. 3.13:

using_email_node_email

Fig. 3.14 : Email node configuration

Then, the result of the flow, is an email arrive, problably at the spam box, to the destination address:

using_email_node

Fig. 3.15 : Sent email

3.2.2. 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.16 : 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.17 : 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 .

Nota

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.18 : 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.19 the token that came in the response is assigned to the attribute token of the virtual device.

using_http_node_change

Fig. 3.19 : Template node configuration

using_http_node_deviceout

Fig. 3.20 : 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.21 : Device updated

3.2.3. Using geofence node

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

using_geofence_node_flow

Fig. 3.22 : Flow using geofence

The geofence node named in area is set like seem in Fig. 3.23. 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.23 : 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.

Nota

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.24 : Template node configuration if the car is in the marked area

using_geofence_node_result

Fig. 3.25 : Output in device out