There are some complex device management use cases, where you need to fine-tune the Groovy script execution per device, depending on the specific device execution state. Bosch IoT Manager allows you to integrate execution self-control logic within the Groovy script source thanks to the Groovy Execution Context API (hereinafter Groovy Exec API). The relevant API methods refer to identifying the execution context and controlling it.

Methods related to execution context

When working with devices, you need to know the context in which the execution is currently running.

The Groovy Exec API provides methods which return the particular Ids for which the execution runs. They indicate the context of the execution and allow you to distinguish different contexts within the same groovy action script.

The methods are:

deviceId - Returns the id of the device on which the current script is being executed.
taskId - Returns the id of the task within which this method is invoked.
ruleId - Returns the id of the rule within which this method is invoked.
serviceInstanceId - Returns the id of the service instance (subscription) within which the current script is being executed.

These Ids could be then passed to a third party application.

Methods related to execution control

The following two methods allow you to control the execution state of the task or rule implicitly within the groovy script itself.

asyncSleep

The asyncSleep method pauses the execution for a specified period of time. Thus you can program a delay in the execution in case it is needed for the successful completion of an operation.

The code that must be executed after the delay should be supplied as a closure, as the last argument of the method. See the following code block for better understanding:

Closure toProceed = {return 'sleep is over, proceeding with next step'} 
execution.asyncSleep(3000, toProceed)

Using the asyncSleep method is suitable for commands that require a particular latency e.g. for a certain configuration to be made.

Keep in mind that such delays are maintained only at runtime. Any sudden restarts of the service might lead to loss of the timer event, leaving the method uncompleted. To prevent such cases, we suggest relying on rule re-triggering strategies.

When working with mass executions on thousands of devices, you should not block the execution of the whole Groovy script, as would happen with the Groovy embedded sleep method. In contrast to the sleep method, the asyncSleep method is executed asynchronously and will not block the whole execution and resources. It will directly complete the current stage of the script, whereas the rest of the script which belongs to the closure will continue as a new script.

stayRunning

The stayRunning method is used to control the device execution and will keep the execution running due to the method's uncompleted invocation. It causes the task or rule to continue regardless of any other conditions that may lead to the completion of the task's or rule's Groovy script.

As we mentioned in previous pages, each device involved in a task or rule has its own device task/rule execution state. This state depends on the confirmation of all asynchronous methods and their closures.

The stayRunning method never completes, thus the current execution would remain RUNNING because the finish-condition requiring all async methods to be completed would never be met.

The stayRunning method is suitable to be combined with the once-per-device execution option. That way the stayRunning method can explicitly guarantee that it will not complete within the current execution and will trigger the rule again for this specific device.

More execution context API methods will be introduced in the future.

Visit our Groovy API documentation for more in-depth technical information.