> For the complete documentation index, see [llms.txt](https://stage-precision.gitbook.io/grid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stage-precision.gitbook.io/grid/smart-group/actions-and-events.md).

# Actions and Events

## Overview of Operating Behavior

Once objects are organized into a Smart Group, the Smart Group transitions from a passive visual container into an active control hub. It acts as a single point of interaction for actions and events.

## Action Distribution

### **Broadcast Mechanism**

When an Action is executed on a Smart Group, the Smart Group automatically distributes that action with its associated parameters down to every member object in the group.

* Single Target Control: Instead of writing complex loops or firing individual actions to dozens of separate devices, you trigger the action once on the Smart Group node.
* Parameter Propagation: All input parameters provided to the Smart Group action are passed through identically to the target member objects.
* All available actions from member objects are automatically populated into the Smart Group

### **Heterogeneous Group Handling & Command Matching**

Because Smart Groups allow grouping objects of different types, not all member objects within a group necessarily support every action.

Smart Groups resolve this through Safe Action Matching:

1. When an action is sent to a Smart Group, the system inspects each member object individually.
2. If a member object supports the matching action name and parameter signature, it executes the command immediately.
3. If a member object does not support the action, it simply ignores the command and performs no action.
4. No Errors / No Halting: Non-matching objects bypass execution gracefully without interrupting the distribution chain or throwing exceptions.

{% hint style="info" %}
Example: A Smart Group contains 3 Dimmable Lights and 1 Temperature Sensor. Sending a `SetBrightness` action turns all 3 lights to the target brightness. The temperature sensor silently ignores the command, and execution completes successfully.
{% endhint %}

## Event Aggregation

### **Centralized Event Listening**

Smart Groups aggregate events generated by any of their member objects. Instead of attaching individual event to every object across the project tree, you can listen directly to the Smart Group node.

* Unified Stream: Whenever *any* child/member object fires an event, that event automatically surface up to the Smart Group.
* Simplified Workflows: Ideal for triggering automation scripts, logging, or driving user interface updates whenever any member in a group changes state.

### **Event Metadata & Source Identification**

When an event is received at the Smart Group level, the event payload contains both the standard event details and crucial origin metadata:

| **Payload Field**  | **Description**                                               | **Example**                         |
| ------------------ | ------------------------------------------------------------- | ----------------------------------- |
| `Event Name`       | The specific event triggered by the subobject.                | `OnMotionDetected`, `OnFault`       |
| `Event Data`       | Parameters or state variables associated with the event.      | `{ "battery": 95, "temp": 22.5 }`   |
| `SmartGroupSource` | Identies the specific member object that generated the event. | `/project/project/SmartGroup4/OSC2` |

Having access to the originating `SmartGroupSource` allows event handlers to act globally at the group level or branch selectively based on which exact device triggered the event.

## Recommended Workflows & Best Practices

1. Use Search by Type for Homogeneous Device Control: Use `Search by Type` for `Light Fixture` so any new light added anywhere in the project automatically receives global commands (e.g., `All Lights Off`).
2. Use Heterogeneous Groups for Zone Management: Group lights, shades, and climate units in a room together. Firing `PowerOff` will turn off all compatible equipment in that zone while ignoring sensors.
3. Utilize Source Identification in Logic: Connect an alarm event to a Smart Group containing all sensors. Use `SmartGroupSource` from the event payload to pinpoint and report the exact device that triggered the event.