Create a rule

Settings

Name

In the Name field, enter an arbitrary name.

Scope

The scope of a rule 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 rule (and respectively - of each task launched by the rule) 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 rule is going to be executed exactly once (per rule triggering), 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 here.

Device selection

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

Open its details and select the option for how you would like to select the devices which will be involved in the rule 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: This example will filter only devices which are lamps.

  return target.feature("lamp") != null

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 * * ?

In the 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.

Overlap

Defines whether multiple tasks (launched by this rule) on a device can be overlapped or should be replaced.

There are three options:

Allow overlapping: new tasks within the same rule can involve devices for which old executions are still running. This option should be used very carefully due to possible accumulation of unfinished tasks.

No overlapping - Cancel old: in case of a new rule trigger over a device, any old unfinished execution within the rule for that device will be canceled.

No overlapping - Keep old & skip new: skip launching a new task for devices with running tasks in the same rule.

Once per device

Defines whether the rule should be executed only once or multiple times per device in the scope. If set to true, once the rule execution has finished on a particular device, any subsequent triggering of the rule will be skipped and will not launch a new task involving this device. This behavior applies regardless of whether the previous rule has finished with success, error or warning.

Auto disable

Defines whether the rule should be automatically disabled after all devices in the scope have passed through the triggering condition and all launched executions have finished. When no more executions are expected, this option will stop the system from listening for events. This option must always be combined with the once-per-device option.

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

This will open the Triggers wizard.

Triggers

In the Triggers view, click the + icon.

Select a trigger type.

• For Manual fire, there is nothing else to define.

• For Event based, enter event type.
  You can also select an event from the event browser.
  

  

• For Timer based, enter a time sequence in the form of a cron expression.
  You can also use the cron expression assistant.
  

  

Then, optionally enter a condition:

• Trigger Condition - will apply to the specific trigger.

• General Condition - will apply to all triggers defined for this rule and for the rule in general.

Confirm each trigger and condition with Save.

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 that all devices have a manufacturer attribute automatically when your defined condition is satisfied and your preferred trigger occurs.

The trigger and condition should be defined in the previous view of the wizard (Triggers). The action script is the same that we saw in Create a task.

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

When ready, click Finish.