> 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/visual-editor.md).
# Visual Editor
Design Kilo IoT rules on the visual BPMN canvas: add nodes, connect them with flows, and configure each step.
The visual editor makes an automation's decisions visible to the people who operate it. Draw the steps, connect them with arrows, and follow each possible path from a reading to its response. You can put a threshold check, another sensor's reading, an alarm, and a device command into a workflow your team can inspect together.
The steps are called **nodes** and the arrows are **flows**. Their shapes follow BPMN (Business Process Model and Notation), a standard for workflow diagrams. You can start with the step descriptions in [Node Reference](/rules-engine/node-reference.md); no prior BPMN knowledge is needed to follow the editor guide.
Create or open a rule before editing. Most setup uses form fields; short expressions using CEL (Common Expression Language) provide comparisons and calculations where needed.
## Getting there
The editor opens when you:
* Click **Add Rule** to create a new rule (at `/rules/create`)
* Click **Edit** on a rule from the Rules list (at `/rules/:id/edit/editor`)
* Switch the mode selector from **Viewing** to **Editing** while viewing a rule
## Editor layout
The editor has four main areas:
1. **Toolbar / Palette** — On the left. Contains draggable node types and canvas tools.
2. **Canvas** — The central area. Your BPMN diagram lives here.
3. **Properties panel** — On the right. Opens when you select a node, showing its configuration fields.
4. **Header bar** — At the top. Shows the rule name, mode selector, autosave status, and action buttons.
## Palette
The palette provides tools and draggable elements you can place on the canvas.
### Tools
| Tool | What it does |
| ----------------------- | --------------------------------------------- |
| **Hand Tool** | Pan the canvas without selecting anything |
| **Lasso Tool** | Draw a selection box around multiple elements |
| **Space Tool** | Create or remove space between elements |
| **Global Connect Tool** | Draw a connection (flow) between two nodes |
### Draggable elements
| Element | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| **Start Event** | Entry point of the rule — starts from one device sensor or a saved trigger condition. One is placed automatically on a new rule. |
| **End Event** | Terminates a flow path |
| **Exclusive Gateway** | Decision point — routes to one branch based on conditions |
| **Script Task** | Evaluates a CEL expression to transform or classify data |
| **Set Alarm** | Triggers an alarm definition with a dynamic message |
| **Execute Command** | Sends a command to a device when the rule fires — control hardware, not just alert |
| **Enrichment** | Fetches the latest reading from another sensor |
| **Boundary Error Event** | Attaches to a task to catch errors and route to a fallback path |
Drag an element from the palette onto the canvas to add it. Each element type and its full configuration are documented in [Node Reference](/rules-engine/node-reference.md).
## Working with the canvas
### Adding nodes
Drag elements from the palette onto the canvas. Position them in the order you want the rule to execute.
### Connecting nodes
Use the **Global Connect Tool** from the palette, or hover over a node until connection handles appear, then drag from one node to another. This creates a **sequence flow** — an arrow showing the execution order.
Rules for connections:
* Start Events and task nodes can have one outgoing flow
* Exclusive Gateways can have multiple outgoing flows (one per branch)
* Every flow from a Gateway (except the default) must have a condition expression
* End Events have no outgoing flows
### Selecting and configuring nodes
Click a node to select it. The properties panel opens on the right, showing fields specific to that node type. Configure the node, then click **Save** at the bottom of the properties panel to apply your changes.
### Deleting nodes
Select a node and press the Delete key, or use the context menu to remove it. Deleting a gateway flow requires confirmation since it also removes the corresponding canvas connection.
## Properties panel
Each node type has its own properties panel with specific fields. When you click a node, the panel opens on the right side of the editor.
Common fields across most node types:
* **Name** — A descriptive label for the node
Many node types also expose CEL-based **Inputs** and **Outputs** sections for advanced data shaping. Node-specific fields are covered in detail in [Node Reference](/rules-engine/node-reference.md).
After editing properties, click **Save** at the bottom of the panel to apply changes. Click **Cancel** to discard.
## Header bar
### Rule name
Click the rule name at the top to rename it inline (max 60 characters). The name is saved when you click away or press Enter.
### Mode selector
A dropdown that shows the current mode:
* **Editing** — Full access to the canvas and properties. Acquires an edit lock.
* **Viewing** — Read-only view of the diagram. No lock acquired.
Switching from Viewing to Editing acquires the edit lock (if available). Switching from Editing to Viewing navigates to the read-only route. If you have unsaved diagram changes, the platform asks you to confirm unlocking the rule and, in normal exit flows, attempts to persist the latest diagram state before releasing the lock.
### Autosave indicator
Shows the current save state:
* **Saving...** — A save is in progress (with spinner)
* **Saved** — The latest changes have been saved
* **Autosave Failed** — The automatic save failed. A dialog offers to retry or go back.
### Actions menu
The three-dot menu (⋮) provides:
* **Rename** — Opens the inline name editor
* **Edit description** — Opens a dialog to edit the rule description (max 1,000 characters)
* **Duplicate rule** — Creates a copy of the rule
### Action buttons
* **Save** — Manually save the current state. Creates a new version. Disabled when there are no unsaved changes.
* **Build** — Opens the build sidebar to validate and create a build artifact. See [Builds, Artifacts, and Deployment](/rules-engine/builds-artifacts-and-deployment.md).
### Tabs
When editing an existing rule, two tabs appear below the header:
* **Editor** — The BPMN canvas (default)
* **History** — The version history table. See [Version History and Restore](/rules-engine/version-history-and-restore.md).
These tabs are shown only while you are editing an existing saved rule. They do not appear in Viewing mode or while creating a brand-new unsaved rule.
---
# 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/visual-editor.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.
