# Working with Rules

## How to Create Rules in Widgelix Rule Engine

### Overview

The Rule Engine in Widgelix allows you to define automated alerts and actions based on device data. Each rule follows an **IF → IS → THEN** logic: you define *when* a condition is met on a device, and *what* should happen as a result.

***

### Step 1: Navigate to the Rule Engine

In the left sidebar, click **Rule Engine**. The Rule Engine list page shows all existing rules with their name, alert type, configured actions, and last execution time.

To create a new rule, click the **+ Create** button in the top-right corner.

***

### Step 2: Enter Basic Rule Information

The **Create Rule** form opens with the following fields at the top:

#### Rule Name *(required)*

Enter a descriptive name for the rule (e.g., `Temperature Too High`).

#### Alert Type *(required)*

Click the dropdown to choose the severity level of the alert. Three options are available:

| Value       | Description                   |
| ----------- | ----------------------------- |
| **Info**    | Informational alert (default) |
| **Warning** | Moderate severity             |
| **Danger**  | Critical severity             |

#### Custom Message *(optional)*

Enter a custom message to include in the alert notification. If left empty, a default message is used.

#### Pass Payload *(optional checkbox)*

Enable this to include the full raw device data payload in the alert notification.

***

### Step 3: Configure Rule Behavior Settings

Below the basic fields is the **Rule Behavior Settings** section with three toggle options:

#### Enabled *(default: ON)*

Activates or deactivates the rule. Disabled rules will not be evaluated.

#### Trigger Once *(default: OFF)*

When enabled, the rule fires only once per condition match. It resets automatically when the condition becomes false again.

#### Execute Every – Rate Limiting *(default: ON, 15 minutes)*

Limits how frequently the rule can fire. Available intervals:

* 1 minute
* 5 minutes
* **15 minutes** *(default)*
* 30 minutes
* 1 hour
* 1 day

***

### Step 4: Add a Trigger Condition (IF / IS)

Below the Behavior Settings, click **+ Add Trigger** to add a condition. This opens the **Configure Condition** panel on the right side of the screen.

The condition is split into two sections: **IF Configuration** and **IS Configuration**.

***

#### IF Configuration — What to Monitor

| Field                       | Required | Description                                                                                                   |
| --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| **Device Type**             | Yes      | Select the device type to monitor                                                                             |
| **Offline Alert**           | No       | Check to trigger when a device goes offline. Data field and comparison are not required when this is checked. |
| **Data Field**              | Yes      | Select which data field to evaluate (e.g., temperature, humidity)                                             |
| **Device Selection Method** | Yes      | Choose **Select from list** to pick devices manually, or **Select from map** to select from a geographic view |
| **Devices**                 | Yes      | Select one or more specific devices to monitor                                                                |

***

#### IS Configuration — What Value to Check

Scroll down in the panel to reach the IS Configuration section.

**Comparison Type** — choose one of:

| Option                              | Description                                                        |
| ----------------------------------- | ------------------------------------------------------------------ |
| **Compare with constant**           | Compare the device reading to a fixed number you enter             |
| **Compare with device measurement** | Compare against another device's live reading                      |
| **Geofence**                        | Trigger based on geographic position (latitude/longitude boundary) |

**Comparison Operator** — choose from:

* Less Than
* Less Than Or Equal
* Equal *(default)*
* Greater Than Or Equal
* Greater Than
* Not Equal
* In Range
* Out Of Range

**Value** — enter the numeric threshold that the data field is compared against.

***

#### Switching Threshold Range *(new feature)*

At the bottom of the IS Configuration section you will find the **Switching threshold range** toggle.

**What it does**

Normally, a condition fires **every time** the value crosses the trigger threshold. This can cause rapid on/off alert flickering when the value fluctuates near that threshold.

**Switching threshold range** solves this by adding a separate **reset threshold**. After the condition fires, the value must first satisfy the reset comparison before the condition is allowed to fire again.

> **Example:** Trigger when `Temperature > 80°C`. Reset when `Temperature < 75°C`. Alerts stop flickering near 80°C because the value must drop below 75°C before the rule can fire again.

**How to enable it**

Toggle the switch from **Disabled** to **Enabled**. Two new required fields appear:

| Field                | Required | Description                                                                   |
| -------------------- | -------- | ----------------------------------------------------------------------------- |
| **Reset comparison** | Yes      | The comparison operator used to evaluate the reset condition                  |
| **Reset threshold**  | Yes      | The numeric value the measurement must satisfy before the rule can fire again |

**Reset comparison** options:

* Less Than *(default)*
* Less Than Or Equal
* Equal
* Greater Than Or Equal
* Greater Than
* Not Equal

**Typical configuration pattern**

| Setting                       | Example value |
| ----------------------------- | ------------- |
| Comparison Operator (trigger) | Greater Than  |
| Value (trigger threshold)     | 80            |
| Reset comparison              | Less Than     |
| Reset threshold               | 75            |

With this setup the rule fires when the reading goes above 80, and will not fire again until the reading drops below 75.

***

Click **Apply** to save the condition, or **Cancel** to discard it.

The saved condition appears in the main form as a **Statement** showing the IF / IS logic:

You can add up to **10 conditions** per rule using the **+ Add Condition** button.

***

### Step 5: Add an Action (THEN)

Below the conditions, in the **THEN** section, click **+ Add Action** to define what happens when the rule fires.

The **Select Action Type** modal appears with the following options:

| Action Type    | Description                                               |
| -------------- | --------------------------------------------------------- |
| **Email**      | Send an email notification                                |
| **Discord**    | Send a message to a Discord channel                       |
| **Slack**      | Send a message to a Slack channel                         |
| **Webhook**    | Call an external HTTP webhook URL                         |
| **SMS**        | Send an SMS text message                                  |
| **Signl4**     | Send an alert via the SIGNL4 mobile alerting platform     |
| **Downlink**   | Send a downlink command back to a device                  |
| **Event Only** | Log the event only — no external notification *(default)* |

#### Example: Email Action

After selecting **Email**, fill in:

* **Recipients** — one or more email addresses
* **Subject** — the email subject line
* **Message** — the email body (supports dynamic placeholders for device data)

Click **Add Action** to confirm. You can add multiple actions to a single rule, and use **← Change Action Type** at any time to switch to a different notification type.

***

### Step 6: Configure the Schedule *(optional)*

The **Schedule** section at the bottom restricts when the rule is allowed to execute. By default it is set to **Any time**.

Click the Schedule card to open the **Configure Schedule** panel.

***

#### Any Day (No Restrictions)

When the **Any day (no schedule restrictions)** toggle is **ON**, the rule will execute at any time of day on any day of the week. This is the default setting.

***

#### Custom Schedule

Toggle **Any day** to **OFF** to reveal the weekly timeline grid, where you can define exactly which hours on which days the rule is permitted to run.

The timeline shows 24 hours (00–23) across the top and one row per day of the week. Each day has a **checkbox** on the left to enable or disable it, and a **time range display** on the right showing the currently selected hours.

**Quick-setup buttons**

| Button                    | Action                                                           |
| ------------------------- | ---------------------------------------------------------------- |
| **Select All**            | Enables all days and selects the full 24-hour range for each     |
| **Clear All**             | Removes all selections and disables all days                     |
| **Business Hours (9–18)** | Applies a 09:00–18:00 range to every day of the week as a preset |

**Drawing a time range by dragging**

1. Click the **checkbox** next to a day to enable it.
2. **Click and drag** left-to-right across the timeline row for that day to select the active hours. The selected range is highlighted in blue and the start/end times are shown on the right.

> The timeline snaps to 30-minute intervals. Drag further right to extend the range, or drag left to shorten it.

***

#### Right-Click Context Menu on a Time Range

Once a time range has been drawn for a day, you can **right-click on the time display** (the `HH:MM – HH:MM` text on the right side of the row) to open a context menu with two options for fine-tuning the schedule.

***

**Option 1 — Edit Time**

Click **Edit Time** to open the **Edit Time Range** dialog, which lets you set the start and end times with exact minute precision instead of relying on drag snapping.

The dialog shows:

* **Edit schedule for \[Day name]** — confirms which day you are editing
* **Start Time** — enter the start time in `HH:MM` 24-hour format (e.g., `08:15`)
* **End Time** — enter the end time in `HH:MM` 24-hour format (e.g., `17:45`)

Click **OK** to apply the changes to that day, or **Cancel** to discard.

***

**Option 2 — Copy to All Days**

Click **Copy to All Days** to instantly duplicate the current day's time range to all other days of the week. All days will be enabled and assigned the same start and end times.

> This is useful when you want a uniform schedule across the entire week — configure Monday precisely using **Edit Time**, then use **Copy to All Days** to propagate it everywhere at once.

***

#### Per-Day Toggle (Precise Time Input)

On the right side of each day row, next to the time display, there is a small toggle switch. Enabling this toggle opens an inline precise time input for that day, allowing you to type start and end times directly without opening the context menu.

***

Click **Apply** to save the schedule and return to the rule editor.

***

### Step 7: Save the Rule

Once everything is configured, click the **Save Rule** button at the bottom of the page.

> If any required fields are missing (e.g., Device Type, Data Field, Devices, or Reset threshold when Switching threshold range is enabled), validation errors will appear in red on the affected fields. Resolve all errors before the rule can be saved.

***

### Summary Checklist

Before saving, verify you have completed:

* [ ] **Rule Name** entered
* [ ] **Alert Type** selected (Info / Warning / Danger)
* [ ] **Custom Message** written *(optional)*
* [ ] **Behavior Settings** configured (Enabled, Trigger Once, Rate Limiting)
* [ ] At least one **Trigger Condition** added with:
  * [ ] Device Type selected
  * [ ] Data Field selected
  * [ ] At least one Device selected
  * [ ] Comparison Operator and Value set
  * [ ] **Switching threshold range** configured *(if needed — set Reset comparison and Reset threshold)*
* [ ] At least one **Action** added *(or kept as default "Event Only")*
* [ ] **Schedule** set *(optional — defaults to Any time)*