Runners

Introduction

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 SmartCore 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

1. Simple Runner

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

You will be able to execute the listener using the URL: https://api.altairsmartcore.com/runner/{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:

  • Simple Runner Listener example

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:

Request

Response

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 SmartCore 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 SmartCore platform:

https://api.altairsmartcore.com/runner/{listener_id_developer}/run? persist={true/false}&device={device_id_developer}

Payload

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.

  • 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:

Request

Response

Stream Runner

  • New Stream created

This could be useful to have a custom URL that generates a stream in Altair SmartCore 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:

https://api.altairsmartcore.com/runner/{listener_id_developer}/run

Payload

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

  • Payload Listener example

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

Request

Response

False

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:

https://api.altairsmartcore.com/runner/{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 to return and show the structure of "context.meta._q":

  • Query String Listener example

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

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 SmartCore.



In all the previous examples don't forget to provide your ApiKey as in any other request to Altair SmartCore 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.