Create a task

Settings

Name

In the Name field, enter an arbitrary name.

Scope

The scope of a task defines the target(s) on which the management action will be executed.

The targets can be devices (Device scope) or the backend system (System scope).

Scope type

In the Scope type field, choose between:

• Device scope - this is the default scope type and the most widely used.
  The action script of the task is going to be executed for each device included in the scope.
  The involved devices can be defined as targets by:

  • ID

  • Device sets and filter conditions

  • Groovy script.

Each is described in more details below.

• System scope - this is used in special cases only.
  The action script of the task is going to be executed exactly once, outside the context of any particular device.
  The target is the backend (Bosch IoT Manager) system.
  
  

For details on the differences between the two scope types, please read Concepts > ... > Action execution depending on the scope.

Device selection

If you chose the Device scope type in the previous step, there will be a field called Device selection by.

Open its combobox and select how you would define the devices to be involved in the task execution.

The involved devices can be defined as targets by:

• ID: use the check boxes to directly select the relevant devices via device ID. Use the search bar to find a device more easily.
  

  

• Device sets and filter conditions
  This option allows you to select a filtered set of devices by:

  • Directory path
    Enter a directory path in the input field.
    Alternatively, click the folder icon to select one of the existing directories. Only one directory can be selected.
    Optionally you can include its subdirectories.
    

    

  • Tags
    Click on the input field or the tag icon to select one of the existing tag groups. Multiple tags can be selected.

  • RQL/Groovy filter
    Click the funnel icon to apply any of your saved filters.
    Alternatively, enter a filter in the input field.
    Example RQL: exists(features/lamp)
    Example Groovy: return target.feature("lamp") != null

  • Additionally, specify if only gateway devices should be involved as targets.
    Check the box for Select only gateways if this serves your use case.

• Groovy script:

  • Enter a Groovy listing script which returns a list of device IDs.
    Example:

    def devices = []

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

    devices.add("my.namespace:id-" + i)

    }

    return devices

  • Enter a Groovy filter condition which is expected to evaluate something to true or false.
    Example: return target.feature("lamp") != nullThis example will filter only devices which are lamps.

Execution options

Execution options allow to adjust the execution of the action in order to achieve better performance or control of the mass execution behavior.

Concurrency limit

Defines the maximum number of devices for which the task will be executed simultaneously.

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

Concurrency timeout

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

Defines the time slot in which the 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 resumed based on a time-schedule.

The time constraint is declared by means of a Cron Expression.

Example:

* * 12-13 * * ?

With this example, events will be triggered at every second in the period between 12 p.m. and 14 p.m., i.e. the task execution will run for two hours.

When you are ready with these Settings, click Next in the left column.

This will open the Action wizard.

Action

Enter your Groovy action script in the Action field.

For help, click on the Groovy API explorer.

This will evoke a list of the available API methods based on which you can build your action script.

You can also use the search bar to search for a suitable method.

When you select a method, on the right you will see a description and a link to the API doc.

Example

Let us assume you want to make sure all devices have a manufacturer attribute.

If you want to express setting an attribute in Groovy, the script would look like in the following snippet.