Advanced Action Flows – Part 1. Basics

This post covers the basics of the Proximi.io action flows. The same content is discussed in the Zero to Hero tutorial series part 2.6. If you’ve read that, feel free to skip to the next chapter.

Action flows are optional event chains that are processed within the Web Portal instance. Action flows can include interactions with third party systems as well as with the visitor’s mobile device. Action flows are stored in our backend database, but performed within the Web Portal instance.

Our action flow editor is based on the Node-RED project which is a creation of IBM Emerging Technologies. We’ve added our own storage driver and improved the overall stability of the system, but it’s still compatible with the original Node-RED project and especially with all the community built nodes that are available.

1. Overview of the Action Flow editor

Please note: Web Portal works best with modern browsers like Google Chrome and Mozilla Firefox.

When you open up the action flow editor the very first time, you see a blank slate as you don’t have any action flows defined. On the left side you can see all the available nodes (all the Node-RED project stock nodes as well as some custom ones from Proximi.io).

In the middle you can see the sheets which are visual representations of the action flows. You can add as many sheets as you want to make the code easier to read. press on the little “+” symbol on top-right corner to add a new sheet.

On the right side you can see the help descriptions for the selected node as well as the debug tab which comes handy in case you’re experiencing any issues with your action flows, or you want to see what’s happening during the triggered actions. Showing data in the debug tab requires that you add debug nodes throughout the critical parts of your action flow chains.

Please note that you can also display debug messages within the browser console as well.

Action flow editor

2. What does a basic action flow consist of?

Adding new logic in a form of action flows is really simple; you start your flow usually with the Proximi.io Event Receiver which triggers the flow when a visitor enters any of the geofences. After that you add some custom logic with the available nodes, like delivering a push notification. In case you want to send a JSON payload (content) to the visitor’s mobile device, you finish up the flow with the Proximi.io Event Transmitter.

Example action flow

3. Building the first action flow

This example action flow will contain the most common nodes you’ll use in your action flows. Here’s what we’re going to build:

simple_push_flow

You can use the following snippet to import the example action flow into your editor:

[{"id":"c8a5de91.3743","type":"proximiio-event-receiver","z":"c2107610.bc4918","delete_event":true,"x":150,"y":82,"wires":[["b716d6b5.826ff8","ccb60590.2c4778"],[]]},{"id":"35cac499.23ef5c","type":"function","z":"c2107610.bc4918","name":"Example push notification","func":"return {\n    type: 'push',\n    title: 'Welcome to the demo!',\n    _proximi_id: msg._proximi_id,\n    _proximi_visitor_id: msg._proximi_visitor_id\n}","outputs":1,"noerr":0,"x":531,"y":188,"wires":[["b1b73fba.bf8c2"]]},{"id":"b1b73fba.bf8c2","type":"proximiio-event-transmitter","z":"c2107610.bc4918","x":807,"y":237,"wires":[]},{"id":"ccb60590.2c4778","type":"debug","z":"c2107610.bc4918","name":"Debug the event","active":true,"console":"false","complete":"true","x":419,"y":73,"wires":[]},{"id":"b716d6b5.826ff8","type":"switch","z":"c2107610.bc4918","name":"Check the event type","property":"event","propertyType":"msg","rules":[{"t":"eq","v":"enter","vt":"str"},{"t":"eq","v":"exit","vt":"str"}],"checkall":"false","outputs":2,"x":207,"y":157,"wires":[["35cac499.23ef5c"],[]]}]

Import can be done via clipboard using the menu on the top right corner of the editor:

actions_5

Here’s the full walk-through of each of the steps and what’s happening:

Proximi.io Event Receiver
This node listens for visitors entering or exiting any of the defined geofences. When a proximity event occurs, the node get’s triggered and it will pass all the event data as an output payload.

Debug node
Debug node can output the whole payload or just the selected properties into the debug tab on the right side of the editor as well as to the browser console. Useful feature to get insights about the things that happen during the action flow execution.

Switch node
Switch node can be used to segment the action flow based on the event type, department and a lot of other properties as well. You can check out all the properties from our REST API documentation. In this case we’re reacting only to “enter” events.

Switch node

Note: This is actually just a standard Switch-node that has been renamed to “Check the event type”. It’s a good practice to name your nodes so that you remember what each of them does.

Function node
Function node allows you to use JavaScript to add custom logic which might not be possible with other nodes. In this case we’re defining a push message payload to be sent to the Proximi.io Event Transmitter, which passes the push message to the mobile device.

Please note that you can pass any kind of valid objects to the Event Transmitter. In this case we’re using a predefined syntax due to the fact that we want to show an actual push notification to the visitor. Proximi.io Management Applications include a helper that will show a local push notification when it receives a payload with type: ‘push’.

actions_4

Proximi.io Event Transmitter
Event Transmitter sends a payload to the visitor’s device. Node requires _proximi_id and _proximi_visitor_id to be present in msg object which are present in every received event from Event Receiver.

4. Deploying the action flow

That’s it! You’ve created your first action flow and it’s now time to deploy it and try it out with our management applications and/or with your own. You can deploy the action flow from the top right corner of the editor. Usually it’s good idea to select the first option “Full”:

Deploying the action flow

Make sure you get the confirmation that your deployment has been successful. This may take a few seconds.

successfully_deployed

Some other things worth pointing out:

Proximi.io Resource
A faster way of retrieving some information from the Proximi.io system, for example the information about the place. Essentially the same as an Http Request.

The little blue dot
The little blue dot is a sign that this node in your action flow has not been deployed yet. The dot will disappear, once you do they deployment.

Disconnected / Waiting text
Don’t be alarmed about the “Disconnected” text on the first node. That is the default mode, until your account starts receiving position updates, in other words, when you login to the management app or connect your account to your own app. After that the first node will turn to “Connected”
node_connected
The last node will remain “Waiting”, which means that it is waiting for events to be processed.

Exporting flows
One little drawback in the NodeRED system is the fact that in the case there is a break in the Internet connection, or two people try to access the same flow simultaneously, it sometimes gets messed up. That may end up in duplicated/multiplied flows similar to this:
messed_up

Therefore we warmly recommend you to export your and store the code somewhere safely. In order to export a flow, select it first by holding down your mouse and moving it over all of your nodes. Then click on the topright menu button and select “Export” – “Clipboard”. This will open your flow in a new window, where you can copy the code, and store it in safe.

export_nodes2

About Annina Koskiola

CEO and Co-founder of Proximi.io. Loves exploring new ways for technology to intertwine with our everyday lives. Passion for history, traveling, eating and the Valais Blacknose sheep.