When you’re building an IoT Project, you know that tools flexibility to meet different needs requirements is key. Following the current approach that enables custom arbitrary code execution in Altair SmartWorks platform using Listeners and Rules, Runners now add that extra degree of flexibility and power that brings the possibility to create new endpoints with fully customized logic.

From the execution of an already existing Listener code, to providing a full payload, passing by internal data stream generation (just like if it was sent from a device), Runner feature provide an additional connectivity level to what is already available in the platform.

How powerful are the runners? What can I do with them? These are just a few use cases that can help inspire you.

Use Cases

We have enhanced the listener creation process with our Flow Tool.

1. Simple Runner

The simplest use case of a Runner is its execution to get a response.

You will be able to execute the listener using the URL:{listener_id_developer}/run

First we need to create a Listener with the "Event Only Runner” selected. For example, let's create a simple Listener that returns a string. We will use the "Function" node that allows us to introduce our custom Goovy code:

  • Simple Runner Listener example
  • Resulting listener

Note: The main goal of the event "Event Only Runner" is to prevent the accidental activation of your listener by other logics.

You can execute the runner making a GET/POST request to the "Run URL" shown in our Listener. For example:



Hello World!

This could be useful to have a custom URL that returns a different response depending on the value of a property stored in a Altair SmartWorks device.

2. Stream Runner

In this case we will build a runner that sends a stream together with the execution request and, of course, will return a response. For this purpose we have to use the runner to create a persistent or non-persistent data stream in the Altair SmartWorks platform:{listener_id_developer}/run? persist={true/false}&device={device_id_developer}


First we need to create a Listener with the event “Event Only Runner” selected. This Listener will have a very simple logic that returns a specific string. Same as above, we will use a "Function" node with the simple Groovy code return "Stream Runner".

  • Stream Runner Listener example

Now let's make the GET/POST request to the streamRunner URL adding the proper fields to specify the persistence of the generated stream and the target device:



Stream Runner

  • New Stream created

This could be useful to have a custom URL that generates a stream in Altair SmartWorks as well as returning a customized response based on any desired analysis.

3. Payload Runner

You can also create runners with a more complex logic by sending a payload with some additional parameters that can be used in the execution:{listener_id_developer}/run


Again, we will create a Listener with the event “Event Only Runner” selected. For example, let's use a simple expression included in a "function" node to evaluate the payload information:

  • Payload Runner example

Now we perform the request sending the key “runner” with the value “true” or “false” and check the appropriate response.




This could be useful to have a custom URL that can evaluate the parameters received in the payload in the execution logic.

4. Query String Runner

Finally, you can use the query string to send additional parameters which will be stored in "context.meta._q" property as an array. The URL would be:{listener_id_developer}/run? custom_parameter={custom_data}&another={some_data}

Let's create again a Listener with the event “Event Only Runner” selected and a very simple logic stored in a "Function" node to return and show the structure of "context.meta._q":

  • Query String Runner example

Now we perform the request sending some parameters in the query string to check how they are returned in the response:


{"data": ["1", "2"], "another": ["3", "4"], "last": ["5"]}

This could be useful for old / simple devices that can only send information by query string. A set of the temperatures collected during the day could be an example of data to send to a Query String Runner for further operation in Altair SmartWorks.

In all the previous examples don't forget to provide your ApiKey as in any other request to Altair SmartWorks API.

Please refer to our API documentation for a more detailed explanation of the URLs and responses or read the "How to create a listener" tutorial if you are not used to work with them.