The action script is executed differently depending on the selected type of scope for the task or rule - device scope or system scope, as outlined in the Tasks topic.

Here is a comparison of the two scope types:

Device scope is applicable when you work with each of the devices on a mass scale, for example when you send commands to them.
System scope is applicable when the action should be executed once off in the whole system of devices, i.e. the execution does not happen on a per-device basis. For example, you may regularly count the number of registered devices and send such statistics to a third-party system

Therefore, the main difference between the two scope types is that:

the action in the context of device scope is executed once for each device defined by the respective device scope. It is important to consider, that in the case of device scope the system adds a target object which corresponds to the respective device on which the script is executed (1,000 devices in the scope => 1,000 executions of the script, i.e. one execution for each device, and in each execution this device is bound as a target).
the action in the context of system scope is executed once-off, whereas

Running in device scope

Device scope is the necessary scope option for the execution of mass device management actions. In device scope, devices are bound as targets. When you use target as the API method entry point (for example target.exec), the system will first list the devices which satisfy the criteria to be included in the scope and will then bind each device as target. After that it will execute the action script once on each target, i.e. on each device in the scope. For example, if the scope includes 1,000 devices, the action script will be executed 1,000 times and the system will report execution results, including partial execution results, for each of them. With this combination of device scope and target, you will have detailed monitoring information on device level and you will also be able to manage the execution - for example cancel a partial execution for a particular device, or retry the execution for a particular device (see the sections on monitoring and management).

The code snippet below provides an example action script for this device scope scenario.

In the following examples, lets assume that:
- featureId : "Lamp"
- operationId: "switch(boolean state)"
and the Groovy script will be:

target.exec("Lamp", "switch", true)

Valid use cases for device scope with DI

Generally, you should execute mass device management actions through the combination of device scope and target. However, in very particular cases, it is possible to execute an action script in device scope context entering with di, which is the binding of the Device Inventory. For example, if you want to get a particular device, you can only do this through the Device Inventory. Here is a valid use case for the combination of device scope and di:

You can get a well-configured device which is bound as exemplaryDevice and then apply its configuration to all other devices in the scope one by one. This will provide you with detailed execution monitoring information on device level. This is what the code for it would look like:

Device exemplaryDevice = di.device("deviceID") String exemplaryDeviceValue = exemplaryDevice.attribute("configuration") String myValue = target.attribute("configuration") if (exemplaryDeviceValue != myValue) { // we set myValue }

Running in system scope

System scope arranges the execution of the action script in a different way - outside the context of a device. In system scope context, in order to access any device you should use di as your entry point. Then you should specify the relevant method from the Groovy DI API in order to get devices by ID or to list devices. Once the relevant devices have been listed, the system will execute the action script once on the whole list of devices and will report the result of one execution.

Valid use cases for system scope are usually in the area of statistics. For example, you may list devices and count how many are online and how many are offline (the script will return x online and y offline). Another option would be to count the number of devices in a particular state such as:

devices in state 1 -> Х count
devices in state 2 -> Y count

This is an example of a recurrent rule which counts the number of devices and potentially reports some statistics:

return "Totally registered devices: " + di.devicesCount(null /*or some filtering here*/)

Using the wrong scope type

This chapter is intended to further illustrate the differences between the two scope types by showing the potential problems you will face if you execute a script intended for one scope type in the context of the other.

Using device scope with a script designed for system scope

When writing an action script, you should always consider the context in which it will be executed, namely the context of device scope or system scope. In particular, consider that device scope will cause the script to be executed once on each target (device), whereas system scope will cause the script to be executed once in the system, i.e. once on a list (of devices).

Therefore, if you write a script which is intended for system scope, as in the code block below, but you execute it in a device scope context, you will experience an unwanted situation.

List<Device> devices = di.devices() for (d : devices) { d.exec("Lamp", "switch", true) }

Let's say that there are 1,000 devices in the scope. You write an action script which should list these devices and execute a device management action once on the list. You start your code with di as an entry point to access the Device Inventory and the devices method to list the relevant devices.

If for some reason you execute such a script in combination with device scope, the listing operation will be executed 1,000 times, i.e. you will have 1,000 identical lists of 1,000 devices each. Then the system will execute the device management action on each of those lists. This will significantly overload the system and does not bring any value. This is why the right approach is to apply system scope.

Using system scope for device management actions

With system scope, even if a list includes 1,000 devices, there will be just one execution of the action script. The system will not provide detailed monitoring information and you will not be able to adjust the execution on device level. Therefore, you will not know what has been executed, on which devices, and how it has finished.

Here is an example action script, similar to the top one, however, written for system scope:

List<Device> devices = di.devices() for (d : devices) { d.exec("Lamp", "switch", true) }

For device management actions therefore it is not recommended to use system scope but rather follow the logic described in the Running in Device Scope chapter.