> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/rules-engine/creating-rules.md).
# Creating Rules
Create a new automation rule from scratch in the Kilo IoT Rules Engine — name it, design the workflow, save first.
Creating a rule means saving the workflow that Kilo will run in response to a sensor reading or a signal from a saved trigger. Its connected steps define what to check and what to do, such as raise an alarm or run a configured device command. This guide takes you from a new rule to its first saved draft.
If you need to **create a trigger**, use **Rules Engine → Triggers → Add trigger**. A trigger is the separate monitoring condition and can be saved before a rule exists. [Triggers](/rules-engine/triggers.md) explains how to connect it to the responding workflow.
Have the source sensor or saved trigger ready, along with any alarm definition or device command the workflow will use. Saving the draft preserves the design; [building and deploying](/rules-engine/builds-artifacts-and-deployment.md) are separate steps before it runs.
## Prerequisites
* You have edit permissions for the Rules Engine in your organization
* Your organization has not reached its subscription rule limit
## Step by step
### 1. Open the rule creation page
From the Rules Engine page, click **Add Rule**. This opens a new rule editor at `/rules/create`, with an empty name field and a starter diagram — a **Start** event already connected to an **End** event.
### 2. Name your rule
The rule name field is at the top of the editor. Click it and type a descriptive name — up to 60 characters. Choose a name that tells your team what the rule monitors and why.
Good naming conventions for operations:
* "Cold storage — temperature breach"
* "Warehouse B — humidity alert"
* "CO2 monitor — threshold escalation"
### 3. Add a description (optional)
Click the three-dot menu (⋮) next to the rule name and select **Edit description**. A dialog opens with a text area — up to 1,000 characters. Use this to explain the rule's purpose, which facility or zone it covers, or any operational context your team should know.
### 4. Build the workflow
The editor opens with a Start event and an End event already on the canvas. A complete rule needs at least:
1. A **Start Event** — the entry point that uses either one sensor's readings or a saved trigger condition
2. One or more processing nodes (Script Tasks, Gateways, Enrichment, [Set Alarm](/rules-engine/node-reference.md#set-alarm))
3. An **End Event** — at least one termination point
Drag nodes from the palette on the left side of the canvas. Connect them with flows (arrows) to define the execution order.
For many rules, this visual structure is the main work: Start Event, one or two decision or transformation steps, then Set Alarm or End Event. When the rule needs exact logic, specific fields accept CEL expressions — for example gateway conditions, Script Task logic, alarm motivation messages, or advanced inputs/outputs. Through CEL, even complex scenarios are possible: multi-step escalation, cross-sensor comparisons, computed derived values, and dynamic alert messages that include live readings.
For a detailed walkthrough of the canvas and available tools, see [Visual Editor](/rules-engine/visual-editor.md). For the full list of node types and their configuration, see [Node Reference](/rules-engine/node-reference.md).
### 5. Configure the Start Event
Select the Start Event node and click the **pencil** icon that appears beneath it — that opens its properties panel on the right. First choose what starts the rule:
* **Start source** — **Sensor reading** uses incoming readings from one selected sensor. **Trigger condition** uses signals from a saved [trigger](/rules-engine/triggers.md), including further signals while it remains active. The rule must be running; its schedule and execution-rate limits still apply. A trigger can act immediately or after a duration, and it can evaluate one device or several devices independently.
A Start Event uses one source or the other, never both.
**With Start source set to Sensor reading**, configure:
* **Device** — Select the device that triggers this rule (searchable dropdown)
* **Sensor** — Select which sensor on that device to monitor (dropdown, enabled after choosing a device)
**With Start source set to Trigger condition**, the Device and Sensor fields are replaced by a single **Trigger condition** selector. Pick the trigger you built on the [Triggers](/rules-engine/triggers.md) tab. This is the path for a condition that must be evaluated before the rule starts, whether that condition is immediate or delayed and whether it watches one device or many. The trigger signal does not contain one sensor-event value, so `vars.value` is unavailable; `vars.device_name` identifies the watched device that met the condition.
The selector does not create a trigger. If the trigger does not exist yet, save your work before leaving the editor, open **Rules Engine → Triggers**, create it, and then return to this rule. After selecting it, click **Save** at the bottom of the Start Event panel to apply the source to the diagram.
Optionally, you can:
* **Enable Schedule** — Toggle to restrict the rule to a specific window. Click **Change schedule** to pick the days and the From/To times, and set the **Time Zone** they are measured in. Schedule is not another start source: it limits when the source you already chose may run the rule. With a duration trigger, the trigger decides when its condition becomes active and the schedule decides whether the rule may run when it processes a signal. Reaching the start of a schedule does not itself run the rule.
* **Add inputs/outputs** — Advanced CEL expressions for data transformation at the Start Event
See [Node Reference](/rules-engine/node-reference.md) for full Start Event configuration details.
### 6. Save your rule
After saving the Start Event panel, click the separate **Save** button in the top-right corner of the editor. The rule is saved as a new version (version 1). The autosave indicator shows "Saved" when the save completes.
After saving, the editor switches from creation mode to edit mode. You now have access to the **History** tab, the **Build** button, and the full actions menu.
### 7. Build and deploy (when ready)
Saving a rule does not deploy it. To run the rule against live sensor data, you need to build and deploy it. See [Builds, Artifacts, and Deployment](/rules-engine/builds-artifacts-and-deployment.md) for the deployment workflow.
## What happens after creation
* The rule appears in the Rules tab of the Rules Engine page
* Version 1 is recorded in the version history
* You hold an edit lock on the rule — others will see the lock icon
* Autosave is active — changes are saved periodically while you work
* The rule is **not running** until you explicitly build and deploy it
## Next steps
* [Visual Editor](/rules-engine/visual-editor.md) — Learn the canvas tools, palette, and properties panel
* [Node Reference](/rules-engine/node-reference.md) — See all available node types and how to configure them
* [Builds, Artifacts, and Deployment](/rules-engine/builds-artifacts-and-deployment.md) — Build and deploy your rule to production
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.kiloiot.io/rules-engine/creating-rules.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
