At the heart of the Losant Enterprise Iot Platform is the Visual Workflow Engine, which allows your team to connect any software or hardware into the Losant application with custom, complex logic backed by powerful cloud resources. In a recent report by MachNation, they stated, “Losant’s node-based Visual Workflow Engine is one of the more user-friendly and sophisticated rules engines on the market today.”
A seasoned developer may be tempted to jump into the Visual Workflow Engine with reckless abandonment, making workflows without a clear plan and eye for reusability. But a little forethought and planning can go a long way to keeping workflows readable, reusable, and adaptable for future development.
Let’s look at some bad-practice workflows, apply some workflow hygiene to them, and compare the results of our cleaning to the original. We’ll start with an application workflow, then apply even more principles to a more complex example.
Our first demo project is a proof-of-concept for a parking garage construction company. They want to track parking spot occupancy for both internal and external purposes. They’ve installed laser distance sensors in a parking garage, each of which reports the distance directly to Losant whenever its reading changes by more than a certain threshold.
If the spot has been occupied for more than 15 minutes, this application should also record the occupancy as a billable event, tracking how many standard and premium billable hours were used (based on time of day) to determine which floors and spots generate the most revenue. This won’t be used to bill customers, but, as a part of a PoC, this data can be very helpful.
The example workflow has the following purposes:
Let’s start with a workflow without any care given to visual clarity:
This workflow accomplishes all 3 goals above. But, it’s nearly impossible to tell what’s going on without diving into each node and evaluating the parameters. We know that the device state is kicking this off, that the workflow may record more device state, that it may create an event, and that it may insert a row into a data table. That’s all.
Without knowing the goals written above, this workflow is completely unintelligible. Even knowing those goals, you can’t clearly see how its implemented or what is wrong if there’s an issue.
Losant allows you to edit the titles of nodes, and write an optional description that appears when you hover over it. Let’s apply that change first:
What a difference! Even by just renaming the nodes you gain a much better understanding of the workflow at a glance.
You can see that you’re working with the distance attribute, then considering the distance to determine if the occupied state should be “true” or “false,” or, in some cases, create an event. You can also see that the tail portion details with how long the parking spot was occupied, eventually recording a billable record.
By adding a description to the “calc. hours” Function Node, you can see a little more information without having to decipher the code it contains:
The workflow is still quite messy, though, with no clear visual structure. Let’s rearrange the nodes and group related ones together:
That’s definitely cleaner, and grouping the nodes together visually allows you to add notes describing what each major portion does.
Notice the other change in the left side, where the Event: Create node now sits in between the Conditional and the Device: State nodes, rather than on its own branch. This keeps you from having two concurrent payload branches coming off of the false path of the conditional node (see earlier screenshot), which not only creates an additional payload but is also more confusing.
Finally, perhaps the most glaring problem is that this workflow has unrelated purposes. It’s attempting to both calculate parking spot occupancy and use the parking spot occupancy to determine billable hours. Those functions relate, but only tangentially.
If you create a second workflow—triggered by the device state you just recorded in this one—you can keep your workflows cleaner:
In fact, with just one purpose per workflow, you now have little need for the notes.
These small changes make a big difference on the readability of your workflow. If another developer had to come in and work on this—or if you returned to it yourself after 6 months or so—it would take a lot less time to understand what’s going on.
Now let’s take a look at a more complicated workflow to see how these hygiene principles scale, and to pick up on a few other best practices.
The second demo is for smart gas meters that have an embedded cellular connection, with gas usage sent automatically to the utility and optionally sent to the customer.
For the customer to view their data, their utility provider must first create an account for them using their address and account number. The customer can then log in to see their current usage and history, available on a white-labeled application created as a Losant Experience.
Creating this account and correctly linking it to the right meter is a complicated process, and so a REST API endpoint is used to power the account creation and linking process for the application.
Our example workflow’s responsibilities are:
This workflow is quite a bit larger than the Parking Garage Occupancy Demo, but the principles described above still apply. Here’s a quick before and after using the steps from before:
Before:
After:
By labeling the nodes, grouping related processes, paying attention to node placement, and adding notes, the workflow becomes noticeably cleaner.
In the “after” screenshot, there are new nodes as well. There is now a debug node after every possible end result. This makes debugging the workflow easier, as the debug pane will record the payload while you have the workflow open. It even highlights the path followed by the workflow:
With only a little bit of familiarity with the workflow, you can look at the highlighted path and determine where the workflow threw an error, making debugging far quicker.
It’s also helpful to keep the overall flow of the workflow clear and consistent. If you have various success and failure conditions for an operation, let the “happy path” continue in the same direction, to make any deviations from it clear at a glance:
Here, all possible failures are to the left, while the success condition trends to the right. When you look at a highlighted debug path, you can tell instantly where the flow diverged and went left, making your debugging that much faster. The possible outcomes are marked with their HTTP response codes and separated them from the normal flow.
It’s best to try not to cross connecting lines, even if you must space nodes further out to allow room for this. It’s difficult to follow paths at a glance when they overlap. In some cases, though, it’s not practical, as in this case with two “success” paths for getting the user ready.
Finally, as in our first example, this workflow is trying to do too much. But there’s a difference from before—this time, the operations depend on each other synchronously. For instance, you have to create a user before you can register a device to it.
It’s also much more likely that some of these operations will need to be repeated in other workflows, especially the whole sequence of authorizing the user.
For these processes, you can take advantage of Losant’s custom nodes to reuse and isolate these functions. In the following screenshot, there are 3 custom nodes:
As a bonus, pulling those sections into custom nodes cleans up the workflow.
Clean workflows not only look nice, they make your work more understandable, more reusable, and less error-prone. Workflow hygiene gets to the heart of visual development itself–clean, intuitive, and fast logic. The Losant Visual Workflow Engine gives you the tools you need, and even pushes you in the right direction with smooth lines and intuitive UI elements. With some care and planning, you can create visual logic that is human-friendly and allows for a quick, intuitive overview of what each workflow is doing.
Losant offers a no-cost Developer Sandbox so you can build the example in this tutorial or any other proof of concept projects at your own pace. If you have any questions or comments about the material discussed, let us know in the Losant Forums.