Tasks

Tasks are one of the two mechanisms, Đ°long with rules, through which the mass device management process can be implemented. As highlighted in the Mass Management overview page, tasks can exist separately or as part of rules. In this section we will explain tasks in the sense when they are launched directly by the operator and exist separately from rules. Tasks in this sense can be defined as instantly launched, one-off executions of a management action script on a set of devices (i.e. scope), as adjusted by execution options.

The three main elements, namely action, scope, and execution options, are explained in details below.

Task elements

Action

The action element of a task is a Groovy script which defines the effect which the task is intended to produce, for example the execution of device actions and/or the calling of internal or external cloud service APIs. Once a task is launched by the operator - or by an external solution using the Bosch IoT Manager API - the action script starts its execution. The action script can be executed multiple times, depending of the cardinality of the scope (see Scope below).

More details on the Groovy script topic and how to write one can be found in the Groovy actions section.

Scope

The scope element of a task defines the targets on which the management action described above will be executed. There are two scope alternatives - device scope for the cases where the action is executed on devices (targets), and system scope which denotes that the action will be executed outside the context of a particular device (target).

The scope is what turns the management process into a mass management one, as the action execution does not have to be initiated for each device separately, but the launch of a single Task can involve even a million of devices.

Device scope

Device scope defines a set of devices on which the action of the task is going to be executed. Upon the launching of a task with this kind of scope, its action script is executed once for each device in its scope, i.e. zero or multiple ti mes depending on the number of devices included in the scope. As explained in more details in the Device Inventory concept, a device means a gateway or an edge device modelled as a thing.

Conceptually, there are three ways to define device scope:

  • By directly listing device IDs, for example {"id1", "id2", "id3"}

  • By creating a Groovy script which will return a list of device IDs, for example:

    1. return ["id1", "id2", "id3"] or return externalService.listAffectedDevices()

    2. def devices = [] // start with empty list

      for (int i = 1; i <= 100; i++) {

      devices.add("id" + i) // fill list with: "id1", "id2", ... "id100"

      }

      return devices

  • By providing a group ID plus optionally a device filter and/or a Groovy condition script

In this case, the task will apply to all devices participating in a group with a particular ID, and if defined - matching the device filter and/or satisfying the condition of the Groovy script.
In particular:

- Group ID is the ID of a group created in the Device Inventory
- Device filter is an RQL filter supported by the Bosch IoT Things service
- Groovy condition script is a script which is expected to evaluate something to true or false, for example:

return target.vendor startsWith("something")

The scope can be further filtered by:
- list of tags
- using the boolean property isGateway which will target only gateways
- using the boolean property recursively, which will include all devices included in sub-groups of the given group

System scope

With the system scope option, the action script is executed exactly once, outside the context of any particular device. Use cases for system scope include reconfiguring tenant accounts in the cloud, generating daily statistics reports and sending them to external systems, etc.

Additional information and examples are available in Action execution depending on the scope.

Execution options

The inbuilt execution options allow you to adjust the execution of the action in order to achieve better performance or control the mass execution behavior, considering the conditions and constraints of the use case.

concurrency-limit

Integer

With this option you can define the maximum number of devices for which the task will be executed simultaneously. When the execution is complete for some of the participating devices, the script will automatically run on the next portion of devices, keeping the concurrent number of executing devices up to the specified limit.
The benefit of this option is that it allows you to manage and prevent simultaneous load peaks to external systems in case your mass management actions would cause millions of devices to start flooding other servers you interact with. For instance, if your command provokes all devices to contact external CMS systems and request downloading huge binaries, you might want no more than 1000 devices to do this simultaneously in order to prevent sudden peaks of overload to that external system.

concurrency-timeout

Integer

This option defines a concurrency timeout in seconds upon which a non-confirmed execution will expire and will stop occupying room in the concurrency limit.

time-constraint

Cron Expression

The time-constraint option allows you to define the time slot in which a certain task will only be allowed to run. This is useful when there is a long-running task, which might need to be automatically interrupted and automatically resumed based on a time-schedule. For example, this can be the case with updates that should run only during the night but due to the large number of devices the update process may take several nights.

In Bosch IoT Manager such time-constraints and respectively time-schedules are declared by means of Cron Expressions . To illustrate the above example, if you would like to restrict a task's execution (e.g. the update process) to the period from 8 p.m. to 8 a.m. every day until the whole task has been executed, you can declare a Cron Expression like this * * 20-7 * * ? . For precision, in this case the task execution will run from 20:00:00 p.m. to 07:59:59 a.m.

There is a slight difference between the general use of Cron Expressions and their use for time-constraint purposes in Bosch IoT Manager.

Normally Cron Expressions are used for the recurrent triggering of events at precise times, based on a declared time-schedule - for example ringing a bell every Friday at 12:30:00 p.m. , which as a Cron expression is 0 30 12 ? * FRI. In such cases the command will start to be executed at the precise time declared and the execution will continue until it is completed. Then this process will be repeated - in our example case every week.

For the needs of the time-constraint option of Bosch IoT Manager, the Cron Expression should declare active events every second during the desired period, which will ensure uninterrupted execution during this period. Therefore the field for seconds, and usually for minutes as well, should be an asterisk ('*').

When you declare a time-constraint option, be careful not to confuse the meaning of zeros and asterisks in your Cron Expression. For example, consider the difference between these two Cron Expressions: * * 12-13 * * ? and 0 0 12-13 * * ?.

In the first case (* * 12-13 * * ?), events will be triggered at every second in the period between 12 p.m. and 14 p.m., i.e. there will be active events from 12:00:00 p.m. to 13.59:59 p.m. and the task execution will run for two hours.

In the second case (0 0 12-13 * * ?), events will be triggered only exactly at: 12:00:00 p.m. and 13:00:00 p.m. Thus the task will run only in the following two one-second periods: 12:00:00 - 12:00:01 and 13:00:00 - 13:00:01.

Task life cycle at a glance

At every stage of its life cycle, a task is assigned a particular execution state which helps its monitoring and management. For example when it is launched its state becomes RUNNING, and when it is completed, its state changes to FINISHED. A RUNNING state means that the task is still ongoing for at least one device in its scope, and FINISHED means that all devices in the scope have either executed and confirmed the success of the action, or the execution has been canceled.

The possible operations on a task are launch, cancel, retry and delete.

Cancel and retry are operations applicable to the whole task or to a single device within the task. In addition, a task can be retried for a sub-set of devices, such as for example all devices FINISHED_WITH_ERROR.

Deleting a task whose state is RUNNING will automatically cancel any pending executions and remove the task.

Quick task examples:

Task example - Start telnet bundle