From e48a53e16e2bbb1f8e77dfec0a6f8758b0f2a7d6 Mon Sep 17 00:00:00 2001 From: abdoruzaqi <245876665+abdoruzaqi@users.noreply.github.com> Date: Sun, 5 Jul 2026 23:28:12 +0000 Subject: [PATCH 1/3] docs: overhaul rule builder documentation with user-first terminology - Created new /rule-builder/ documentation structure. - Implemented canvas.md, add-action.md, rule-configuration.md, condition-builder.md, action-settings.md, rule-lifecycle.md, and debugging.md. - Consistently replaced internal 'FlexValueControl' with 'Smart Value Selector'. - Updated all existing internal links to reflect renamed and restructured files. - Ensured all descriptions focus on user-facing product usage and visual interactions. - Verified site integrity with a clean Hugo build. --- .../architecture/engine/execution-engine.md | 2 +- .../en/advanced-concepts/decision-trees.md | 2 +- .../advanced-concepts/reference/doctypes.md | 4 +- .../advanced-concepts/reference/glossary.md | 2 +- content/en/rule-builder/_index.md | 29 +++- content/en/rule-builder/action-settings.md | 57 ++++++++ content/en/rule-builder/add-action.md | 50 +++++++ .../rule-builder/adding-managing-actions.md | 38 ------ content/en/rule-builder/canvas-navigation.md | 47 ------- content/en/rule-builder/canvas.md | 52 ++++++++ content/en/rule-builder/condition-builder.md | 60 +++++++++ content/en/rule-builder/debugging.md | 56 ++++++++ .../en/rule-builder/lifecycle-execution.md | 124 ------------------ content/en/rule-builder/rule-configuration.md | 48 +++++++ content/en/rule-builder/rule-lifecycle.md | 60 +++++++++ 15 files changed, 415 insertions(+), 216 deletions(-) create mode 100644 content/en/rule-builder/action-settings.md create mode 100644 content/en/rule-builder/add-action.md delete mode 100644 content/en/rule-builder/adding-managing-actions.md delete mode 100644 content/en/rule-builder/canvas-navigation.md create mode 100644 content/en/rule-builder/canvas.md create mode 100644 content/en/rule-builder/condition-builder.md create mode 100644 content/en/rule-builder/debugging.md delete mode 100644 content/en/rule-builder/lifecycle-execution.md create mode 100644 content/en/rule-builder/rule-configuration.md create mode 100644 content/en/rule-builder/rule-lifecycle.md diff --git a/content/en/advanced-concepts/architecture/engine/execution-engine.md b/content/en/advanced-concepts/architecture/engine/execution-engine.md index 81c3f3e..f68ac6c 100644 --- a/content/en/advanced-concepts/architecture/engine/execution-engine.md +++ b/content/en/advanced-concepts/architecture/engine/execution-engine.md @@ -105,6 +105,6 @@ Rule conditions and templates are evaluated using `SafeFrappeAPI`, preventing un ## Related Topics -- [Rule Building]({{< relref "rule-builder/canvas-navigation.md" >}}) +- [Rule Building]({{< relref "rule-builder/canvas.md" >}}) - [Glossary]({{< relref "advanced-concepts/reference/glossary.md" >}}) - [API Reference]({{< relref "api-reference/public-apis.md" >}}) diff --git a/content/en/advanced-concepts/decision-trees.md b/content/en/advanced-concepts/decision-trees.md index 9f1b80b..fcdd91f 100644 --- a/content/en/advanced-concepts/decision-trees.md +++ b/content/en/advanced-concepts/decision-trees.md @@ -84,5 +84,5 @@ Need to process a collection? ## Related Topics - [Glossary]({{< relref "advanced-concepts/reference/glossary.md" >}}) -- [Rule Builder]({{< relref "rule-builder/canvas-navigation.md" >}}) +- [Rule Builder]({{< relref "rule-builder/canvas.md" >}}) - [Action Zone]({{< relref "action-types/" >}}) diff --git a/content/en/advanced-concepts/reference/doctypes.md b/content/en/advanced-concepts/reference/doctypes.md index 3bf783f..7d6c8af 100644 --- a/content/en/advanced-concepts/reference/doctypes.md +++ b/content/en/advanced-concepts/reference/doctypes.md @@ -54,7 +54,7 @@ The primary container for an automation flow. It defines **when** logic starts a Represents a single executable node (Step) within a Rule's graph. ### When to Use -- Rule Actions are managed via the [Rule Builder]({{< relref "rule-builder/canvas-navigation.md" >}}), which handles the creation of these child records automatically. +- Rule Actions are managed via the [Rule Builder]({{< relref "rule-builder/canvas.md" >}}), which handles the creation of these child records automatically. | Field | Type | Description | | :--- | :--- | :--- | @@ -94,5 +94,5 @@ Audit trail for every rule execution. ## Related Topics - [Execution Engine]({{< relref "advanced-concepts/architecture/engine/execution-engine.md" >}}) -- [Rule Builder]({{< relref "rule-builder/canvas-navigation.md" >}}) +- [Rule Builder]({{< relref "rule-builder/canvas.md" >}}) - [API Reference]({{< relref "api-reference/public-apis.md" >}}) diff --git a/content/en/advanced-concepts/reference/glossary.md b/content/en/advanced-concepts/reference/glossary.md index d80c12d..29e603f 100644 --- a/content/en/advanced-concepts/reference/glossary.md +++ b/content/en/advanced-concepts/reference/glossary.md @@ -48,4 +48,4 @@ Common terminology and core concepts used throughout the FlexiRule documentation - [System Architecture]({{< relref "advanced-concepts/architecture/" >}}) - [Execution Engine]({{< relref "advanced-concepts/architecture/engine/execution-engine.md" >}}) -- [Rule Building]({{< relref "rule-builder/canvas-navigation.md" >}}) +- [Rule Building]({{< relref "rule-builder/canvas.md" >}}) diff --git a/content/en/rule-builder/_index.md b/content/en/rule-builder/_index.md index e117765..557da29 100644 --- a/content/en/rule-builder/_index.md +++ b/content/en/rule-builder/_index.md @@ -1,5 +1,30 @@ --- -title: Rule Builder Guide +title: Rule Builder weight: 40 -description: Deep dive into the Visual Rule Builder UI and configuration. +description: Learn how to use the visual interface to build and manage your business rules. --- + +# Rule Builder + +The Rule Builder is the heart of FlexiRule. it provides a powerful, visual "drag-and-drop" interface that allows you to orchestrate complex business logic without writing code. + +## In this Section + +- **[Canvas Navigation]({{< relref "canvas.md" >}})**: Learn how to move around the workspace and arrange your logic blocks. +- **[Adding Actions]({{< relref "add-action.md" >}})**: Discover how to use the Action Zone to insert new logic into your flow. +- **[Rule Configuration]({{< relref "rule-configuration.md" >}})**: Set up the triggers and global settings that define when your rule runs. +- **[Condition Builder]({{< relref "condition-builder.md" >}})**: Build complex logical branches using a simple visual interface. +- **[Action Settings]({{< relref "action-settings.md" >}})**: Configure the details of individual blocks using the Smart Value Selector. +- **[Rule Lifecycle]({{< relref "rule-lifecycle.md" >}})**: Understand the stages of a rule from draft to active production. +- **[Debugging & Logs]({{< relref "debugging.md" >}})**: Test your rules safely and troubleshoot live executions. + +## Key Concepts + +### Visual Flow +FlexiRule represents logic as a flowchart. You can see exactly how data moves from a trigger event to the final outcome. + +### No-Code Configuration +Instead of writing scripts, you use the **Smart Value Selector** to pick fields, apply formulas, and set values. + +### Safety First +With built-in **Debugging** and a version-controlled **Lifecycle**, you can build and update automations with confidence, knowing that your live operations are protected. diff --git a/content/en/rule-builder/action-settings.md b/content/en/rule-builder/action-settings.md new file mode 100644 index 0000000..93f6f78 --- /dev/null +++ b/content/en/rule-builder/action-settings.md @@ -0,0 +1,57 @@ +--- +title: Action Settings +description: Learn how to configure individual blocks in your rule. +weight: 60 +--- + +# Action Settings + +When you select a block on the canvas, the **Action Settings** panel slides out from the right side of the screen. This is where you define the specific behavior for that step in your rule. + +## Common Interface Elements + +While every action has different options, they all share a consistent design: + +- **Block Title**: At the top, you can see and edit the name of the block. +- **Description**: A brief explanation of what the action does. +- **Configuration Fields**: The main area where you input data, select options, and define logic. + +## Smart Value Selector + +The **Smart Value Selector** is the most important tool within the settings panel. It appears whenever you need to provide a value—whether it's a piece of text, a number, a date, or a reference to another field. + +### How to Use It +Click into any field that supports the Smart Value Selector to see your options: + +1. **Static Input**: Just type a value (like "Hello World" or "100"). +2. **Variable Picker (@)**: Type `@` or click the variable icon to see a list of available data. This includes: + - **Document Fields**: Any field from the record that triggered the rule (e.g., `@doc.customer_name`). + - **Rule Variables**: Values created by earlier "Set Value" or "Query" blocks. + - **Global Constants**: System values like the current date or the current user. +3. **Advanced Resolvers (/)**: Type `/` or click the magic wand icon to access specialized tools: + - **Formulas**: Perform math or combine text (e.g., `{{ @doc.first_name }} {{ @doc.last_name }}`). + - **Formatting**: Change how dates or numbers appear. + - **Logic**: Use "If/Else" statements to pick a value dynamically. + +## Field Types + +In the settings panel, you will encounter different types of input controls: + +- **Dropdowns**: Choose from a fixed list of options. +- **Checkboxes**: Toggle settings on or off. +- **Data Grids**: Used for actions like "Set Value," where you need to map multiple fields at once. Each row in the grid uses a Smart Value Selector for the value column. +- **Multi-Select**: Pick one or more tags or items from a list. + +## Context Awareness + +The settings panel is "Smart." It knows where the block is located in your flow. +- **Available Variables**: You will only see variables in the Smart Value Selector that have actually been defined *before* the current block. +- **Validation**: Required fields are marked, and the panel will alert you if your configuration is incomplete or contains errors. + +## Saving Changes + +Changes in the Action Settings panel are usually drafted immediately. However, you must **Save** the entire rule using the button at the top of the canvas to commit your changes to the system. + +{{< tip >}} +**Keep it Readable**: Use the title field at the top of the settings panel to give each block a business-friendly name. Instead of "Set Value 1," use "Calculate Discounted Total." +{{< /tip >}} diff --git a/content/en/rule-builder/add-action.md b/content/en/rule-builder/add-action.md new file mode 100644 index 0000000..96658c0 --- /dev/null +++ b/content/en/rule-builder/add-action.md @@ -0,0 +1,50 @@ +--- +title: Adding Actions +description: Learn how to add new logic blocks to your rule. +weight: 20 +--- + +# Adding Actions + +Building a rule involves adding "Actions" (Blocks) to the canvas and connecting them to form a logical flow. FlexiRule makes this process intuitive with the **Action Zone**. + +## The Action Zone + +The Action Zone is the primary way to insert new logic into your rule. It appears dynamically as you work on the canvas. + +{{< video src="/images/add-action-from-action-zone.webm" autoplay="true" loop="true" muted="true" >}} + +### How to Add an Action +1. **Trigger the Menu**: Hover your mouse over any connection line (the arrows between blocks) or click the `+` icon that appears in empty spaces on the canvas. +2. **Browse or Search**: An action menu will pop up. You can: + - **Search**: Type keywords like "Email," "Update," or "Check" to find specific actions quickly. + - **Categories**: Browse through categorized lists like *Data Operations*, *Communications*, or *Flow Control*. +3. **Select**: Click the action you want to add. +4. **Auto-Insertion**: The new block will be automatically placed on the canvas. If you clicked a connection line, the new block will be inserted *between* the two existing blocks, and the connections will be automatically updated. + +## Types of Actions + +When adding an action, you will see several types of blocks categorized by their purpose: + +- **Set Value**: Used for calculations and updating variables within the rule. +- **Check (Condition)**: Creates a fork in the road based on logic (True/False). +- **Update Record**: Saves changes directly to a record in your system. +- **Notify**: Sends alerts via Email, SMS, or System Notifications. +- **Repeat (Loop)**: Runs a series of actions for every item in a list. +- **Process**: Triggers advanced system operations or external integrations. + +## Organizing Blocks + +Once an action is added, you can click and drag it to any position on the canvas. + +### Inserting Between Blocks +The easiest way to add logic to an existing flow is to hover over the arrow connecting two blocks. When the `+` icon appears, clicking it and selecting an action will "splice" the new action into the flow, saving you from manually deleting and re-drawing connection lines. + +{{< video src="/images/remove-a-node-will-dynamically-reconnet-nodes.webm" >}} + +### Quick Configuration +As soon as you add an action, it is selected by default, and its **Action Settings** panel opens on the right. This allows you to immediately configure the details of the new block without extra clicks. + +## Managing Actions +- **Renaming**: You can customize the name of any block by clicking its title in the settings panel. This helps make your flow more readable (e.g., instead of "Notify," name it "Send Approval Email"). +- **Deleting**: To remove a block, select it and press `Delete` on your keyboard, or click the trash icon in its settings panel. The builder will attempt to reconnect the preceding and following blocks automatically. diff --git a/content/en/rule-builder/adding-managing-actions.md b/content/en/rule-builder/adding-managing-actions.md deleted file mode 100644 index 428a1a6..0000000 --- a/content/en/rule-builder/adding-managing-actions.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Adding and Managing Actions -description: Learn how to use the Action Zone to build your rule logic. -weight: 20 ---- - -# Adding and Managing Actions - -Building logic in FlexiRule is centered around adding and connecting "Action" nodes. - -## The Action Zone - -The **Action Zone** is the primary way to add new logic. It provides a searchable menu of all available actions. - -{{< video src="/images/add-action-from-action-zone.webm" autoplay="true" loop="true" muted="true" >}} - -### How to Add an Action -1. **Hover**: Hover your mouse over any connection line or empty space on the canvas. -2. **Trigger**: Click the `+` icon that appears. -3. **Search & Select**: Browse categories or type to find the action you need (e.g., "Email" or "Update Record"). -4. **Insert**: The new node is automatically inserted and connected into your flow. - -## Managing Connections - -### Reconnecting Nodes -If you delete a node between two others, FlexiRule intelligently heals the connection to maintain your logic flow. - -{{< video src="/images/remove-a-node-will-dynamically-reconnet-nodes.webm" >}} - -### Manual Connections -You can also manually connect nodes by dragging from the output handle of one node to the input handle of another. - -## Intelligent Configuration - -When you select an action, a configuration panel opens on the right. - -- **Smart Pickers**: Field pickers only show variables that are actually available at that point in the rule. -- **Validation**: The builder alerts you if required fields are missing before you save. diff --git a/content/en/rule-builder/canvas-navigation.md b/content/en/rule-builder/canvas-navigation.md deleted file mode 100644 index bb87973..0000000 --- a/content/en/rule-builder/canvas-navigation.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Canvas Navigation -description: Learn how to navigate and use the visual Rule Builder canvas. -weight: 10 -aliases: - - /docs/user-guide/rule-builder/ ---- - -# Canvas Navigation - -The Rule Builder is your visual workspace for designing business logic. It provides a drag-and-drop canvas where you can orchestrate workflows while maintaining full visibility into the execution flow. - -![Rule Builder Overview](/images/flexirule-canvas-view.png) - -## Core Canvas Interactions - -### Moving and Zooming -- **Pan**: Click and drag any empty space on the canvas to move around. -- **Zoom**: Use your mouse wheel or the zoom controls in the corner to adjust the view. - -### Working with Nodes -- **Select**: Click a node to select it and open its configuration panel. -- **Move**: Drag a node to reposition it. -- **Delete**: Select a node and press `Backspace` or `Delete`. The builder will automatically attempt to reconnect the remaining nodes. - -### Bulk Actions -You can select multiple nodes by holding `Shift` and dragging a selection box. This allows you to move or copy groups of logic at once. - -{{< video src="/images/shift-click-nodes-to-copy.webm" >}} - -## Debugging on the Canvas - -The Rule Builder includes built-in tools to test your rules in real-time. - -### Visual Execution Path -When you run a test, the builder highlights the exact path taken during execution, showing you exactly which nodes were triggered. - -{{< video src="/images/debug-rule-view-execution-path.webm" >}} - -### Inspecting Results -You can click on any node after a test run to see its specific results, including modified variables and return values. - -![Debug View Return Result](/images/debug-view-return-result.png) - -## Examples {#examples} - -For more information on how to build rules, see our [Quick Start Guide]({{< relref "getting-started/quick-start" >}}). diff --git a/content/en/rule-builder/canvas.md b/content/en/rule-builder/canvas.md new file mode 100644 index 0000000..0ed08c0 --- /dev/null +++ b/content/en/rule-builder/canvas.md @@ -0,0 +1,52 @@ +--- +title: Canvas Navigation +description: Learn how to navigate and use the visual Rule Builder canvas. +weight: 10 +--- + +# Canvas Navigation + +The Rule Builder provides a visual workspace where you can design your business logic by dragging, dropping, and connecting different "Blocks." This visual approach allows you to see exactly how data flows through your system. + +![Rule Builder Overview](/images/flexirule-canvas-view.png) + +## The Visual Workspace + +The canvas is an infinite workspace that represents your rule's logic as a flowchart. + +### How Logic is Represented +- **Blocks**: Each step in your rule is represented by a Block (node). Blocks have a clear icon, a title, and often a sub-label describing their specific configuration. +- **Connections**: Arrows between blocks show the direction of execution. The flow typically moves from the **Start** block at the top towards various outcomes or a **Stop** block. +- **Entry & Exit Points**: Most blocks have a circular handle at the top (input) and one or more handles at the bottom (output). + +## Core Interactions + +### Moving Around +- **Pan**: Click and hold any empty area of the canvas, then drag to move your view. +- **Zoom**: Use your mouse wheel or the zoom controls in the bottom-right corner to get a bird's-eye view or focus on a specific section. + +### Arranging Your Logic +- **Moving Blocks**: Click and drag any block to reposition it. The connected arrows will automatically adjust to follow the block. +- **Selecting**: Click a block to select it. This highlights the block and opens its **Action Settings** panel on the right side of the screen. +- **Multi-Select**: Hold `Shift` and drag a box around multiple blocks to move them as a group. + +{{< video src="/images/shift-click-nodes-to-copy.webm" >}} + +### Connecting Blocks +To create a connection, click and drag from the bottom handle of one block to the top handle of another. +- **Valid Paths**: The builder will highlight valid connection points as you drag. +- **Auto-Healing**: If you delete a block that sits between two others, the builder will often attempt to "heal" the connection by linking the preceding block directly to the following one. + +## Visual Indicators + +The canvas uses visual cues to help you understand your rule at a glance: +- **Active State**: Selected blocks are highlighted with a distinct border. +- **Validation**: If a block is missing required configuration, a warning icon or red outline may appear to alert you before you save. +- **Logical Branching**: For decision blocks (like "Check"), paths are clearly labeled (e.g., "True" and "False") so you can follow the logic easily. + +## Tips for a Clean Canvas +- **Alignment**: Keep your blocks organized vertically to make the logic easier for others to read. +- **Labels**: Use descriptive labels for your blocks so the purpose of each step is clear without opening the settings. +- **Sub-rules**: For very complex logic, consider using a **Sub-rule** block to keep your main canvas simple and readable. + +![Ruleflow with Sub-rule](/images/flexirule-canvas-with-sub-rule.png) diff --git a/content/en/rule-builder/condition-builder.md b/content/en/rule-builder/condition-builder.md new file mode 100644 index 0000000..5fdf852 --- /dev/null +++ b/content/en/rule-builder/condition-builder.md @@ -0,0 +1,60 @@ +--- +title: Condition Builder +description: Learn how to create logical branches in your rules. +weight: 50 +--- + +# Condition Builder + +The **Condition Builder** is a visual interface used to define "Yes/No" logic. It is most commonly found inside the **Check** block, but it is also used for filters and trigger conditions. + +## How it Looks + +Instead of writing complex code, you build conditions using a structured, row-based interface. Each row represents a single logical check. + +![Condition Builder Example](/images/demo-condition-and-query.webm) + +## Building a Condition + +A single condition row consists of three main parts: + +1. **Field/Value**: What you are checking (e.g., `Status` or `Grand Total`). +2. **Operator**: How you are checking it (e.g., `is`, `is not`, `is greater than`, `contains`). +3. **Comparison Value**: What you are checking against (e.g., `Open` or `1000`). + +### Using the Smart Value Selector +For both the first and third parts of a condition, you use the **Smart Value Selector**. This tool allows you to: +- Pick fields directly from the document. +- Use variables calculated earlier in the rule. +- Enter static text or numbers. + +## Grouping Logic (AND / OR) + +Rules often require checking more than one thing at a time. The Condition Builder uses **Groups** to handle this. + +- **AND Groups**: All conditions in the group must be true for the whole group to be true. (e.g., "Status is Open" **AND** "Total > 1000"). +- **OR Groups**: Only one condition in the group needs to be true for the whole group to be true. (e.g., "Customer is VIP" **OR** "Order is Urgent"). + +### Nested Groups +You can add groups inside of other groups to create complex logic. The UI represents this with indented boxes, making it easy to see which conditions belong together. + +## Visual Structure + +- **Add Condition**: Click the `+ Condition` button to add a new row to the current group. +- **Add Group**: Click the `+ Group` button to create a new nested AND/OR block. +- **Toggle Logic**: Click the **AND/OR** label at the top of a group to switch the logic for all rows within that group. +- **Delete**: Use the trash icon next to any row or group to remove it. + +## Example: Complex Approval Logic +Imagine you want a rule to run if: +*(The Order is from a VIP Customer)* **AND** *(The Total is over $5,000 **OR** the Order is marked as "Urgent")* + +In the Condition Builder, this would look like: +- **Group (AND)** + - Row: `Customer Type` is `VIP` + - **Group (OR)** + - Row: `Grand Total` > `5000` + - Row: `Priority` is `Urgent` + +## Validation +As you build, FlexiRule checks your logic. If you leave a value empty or use an operator that doesn't make sense for the field type (like using "Greater Than" on a text field), the builder will highlight the error so you can fix it before saving. diff --git a/content/en/rule-builder/debugging.md b/content/en/rule-builder/debugging.md new file mode 100644 index 0000000..9556cf6 --- /dev/null +++ b/content/en/rule-builder/debugging.md @@ -0,0 +1,56 @@ +--- +title: Debugging & Execution Logs +description: Learn how to test your rules and understand why they run. +weight: 80 +--- + +# Debugging & Execution Logs + +FlexiRule provides built-in tools to help you understand exactly what happens when a rule runs. Whether you are testing a new idea or investigating why a live rule didn't behave as expected, these tools give you full visibility. + +## Testing with the Debugger + +The **Debug Rule** tool allows you to run your logic in a "sandbox" mode before you activate it. + +### How to Run a Test +1. **Open Debugger**: Click the **Debug Rule** button at the top of the canvas. +2. **Select a Record**: Pick a real document from your system (e.g., a specific Sales Order) to use as the test data. +3. **Simulate**: Click **Run Test**. + +### Understanding the Results +- **Visual Path Trace**: On the canvas, the path taken by the logic is highlighted. You can see exactly which "Check" blocks were true and which actions were triggered. +- **No Real Changes**: The debugger simulates the actions but **does not** save any changes to your database. It is 100% safe to use on production data. +- **Result Inspection**: Click on any highlighted block after the test to see its specific inputs and outputs (e.g., what value was calculated or what email would have been sent). + +![Debug View Return Result](/images/debug-view-return-result.png) + +## Execution Logs + +For **Active** rules, FlexiRule keeps a history of every time the rule was triggered. This is your primary tool for troubleshooting live automations. + +### Why did the rule trigger? +The logs will show you: +- **The Event**: Which document and event (e.g., Save) triggered the run. +- **The Outcome**: Whether the rule finished successfully, was skipped, or hit an error. + +### Why did the rule NOT trigger? +If you expected a rule to run but it didn't, check the logs for: +- **Trigger Condition Failed**: The high-level "gatekeeper" condition you set in the Rule Configuration wasn't met. +- **Disabled State**: The rule was set to "Disabled" at the time of the event. +- **Priority Conflict**: Another rule with higher priority might have stopped the execution chain. + +## Understanding the Visual Path + +When viewing a log or a debug run, the canvas uses color-coded highlights: + +- **Green/Highlighted**: The block was executed successfully. +- **Grey/Dimmed**: The block was skipped (e.g., it was on the "False" path of a "Check" block). +- **Red**: The block encountered an error. + +{{< video src="/images/debug-rule-view-execution-path.webm" >}} + +## Common Troubleshooting Tips + +- **Check the Variables**: If a "Set Value" block isn't working, use the debugger to see if the input variables actually have the data you expect. +- **Look for Loops**: If a rule stops unexpectedly, it might have hit the safety limit (FlexiRule stops any rule that exceeds 1,000 steps to prevent system crashes). +- **Validation Errors**: If a rule fails to activate, the builder will usually point you directly to the block that is missing a setting or has an invalid formula. diff --git a/content/en/rule-builder/lifecycle-execution.md b/content/en/rule-builder/lifecycle-execution.md deleted file mode 100644 index e49aa28..0000000 --- a/content/en/rule-builder/lifecycle-execution.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Rule Lifecycle & Execution -description: Learn how to manage rules from creation to activation and how they run in the system. -weight: 10 ---- - -# Rule Lifecycle & Execution - -Every automation you build in FlexiRule follows a specific lifecycle. Understanding these stages ensures that you can develop, test, and update your business logic safely without disrupting your live operations. - -## Rule States - -A rule can be in one of four primary states. You can see the current state in the **Status** badge at the top of the rule page. - -```mermaid -graph LR - Draft --> Active - Active --> Draft - Active --> Disabled - Disabled --> Active - Active --> Archived - Draft --> Archived -``` - -| State | Eligible to Run | Editable | Description | -| :--- | :---: | :---: | :--- | -| **Draft** | No | **Yes** | The initial state for all new rules. Use this for building and testing. | -| **Active** | **Yes** | No | The rule is live and will run automatically when its trigger occurs. | -| **Disabled** | No | **Yes** | A previously active rule that has been temporarily turned off. | -| **Archived** | No | No | A retired rule kept only for historical records and old execution logs. | - ---- - -## Managing Your Rules - -### 1. Activating a Rule -When your logic is ready for production, click the **Activate** button. -- **Validation**: FlexiRule will automatically check your logic for errors (like missing connections or incomplete configurations). -- **Locking**: Once active, the rule is **locked**. This prevents accidental changes to live business logic. - -### 2. Updating an Active Rule (Amending) -If you need to change a rule that is already live, use the **Amend Rule** button. -- **Safety First**: FlexiRule creates a new **Draft** version of your rule. -- **Continuous Operation**: The original version stays **Active** and continues to run your business until you are ready to replace it with the new version. -- **History**: This creates a clear version history, allowing you to see how your logic has evolved over time. - -### 3. Disabling a Rule -If you need to stop an automation temporarily without deleting it, you can set it to **Disabled**. This is useful during system maintenance or when a specific business policy is paused. - ---- - -## How a Rule Runs - -When a business event occurs (like a Sales Order being saved), FlexiRule follows a specific sequence to decide if and how to run your rules. - -### Step 1: Finding the Rule -The system looks for all **Active** rules that match the document type and the event. - -### Step 2: Priority Sorting -If multiple rules match the same event, they are run in order of their [Priority]({{< relref "introduction/core-concepts#16-priority" >}}). -- **Priority 20** (High) runs before **Priority 0** (Default). -- This is important if one rule depends on a value set by another rule. - -### Step 3: The "Gatekeeper" (Trigger Condition) -Before loading the full logic flow, FlexiRule evaluates the **Trigger Condition** (if you defined one). -- **Example**: "Only run if `Total Amount` is greater than `1000`." -- If the condition is not met, the rule stops immediately without using system resources. - -### Step 4: Starting the Flow -Execution always begins at the **Start** (Entry Action) block. From there, it follows the lines you've drawn to the next blocks. - -### Step 5: Branching Logic -When the flow reaches a [Check Block]({{< relref "action-types/condition" >}}), it evaluates your criteria: -- If the result is **True**, it follows the path marked "True". -- If the result is **False**, it follows the path marked "False". - -### Step 6: Completion -The rule finishes when it reaches a **Stop** block or a path with no further connections. - -{{< tip >}} -**Execution Safety**: To prevent accidental infinite loops, FlexiRule will automatically stop any rule that tries to execute more than **1,000 steps** in a single run. -{{< /tip >}} - ---- - -## Real-World Example: Order Approval -**Scenario**: Automatically approve Sales Orders over $1,000 for VIP customers. - -1. **Trigger**: `Before Save` of a `Sales Order`. -2. **Trigger Condition**: `doc.grand_total > 1000`. -3. **Check Block**: Is the customer a "VIP"? - - **True Path**: Use an **Assignment** block to set `status` to "Approved". - - **False Path**: Use a **Notify** block to alert the Manager for manual review. - ---- - -## Good to Know - -- **Test Before You Activate**: Always use the **Debug Rule** button to run a simulation with real data. It's safer than testing on live orders! -- **Priorities Matter**: If you have two rules—one that calculates a discount and one that sends an email with the total—make sure the discount rule has a higher priority so the email shows the correct final price. -- **Check the Logs**: If an automation didn't run, the [Execution Log]({{< relref "rule-builder/lifecycle-execution#execution-logs" >}}) will tell you exactly why (e.g., "Trigger Condition failed"). - ---- - -## Testing & Troubleshooting - -### Debug Rule Simulation -Before activating a rule, use the **Debug Rule** tool. -- You can pick a real document from your system and "simulate" the rule. -- You will see exactly which path the logic took and what values were calculated. -- **Important**: Debugging is a simulation; it does not change any real data in your database. - -### Execution Logs -Every time an **Active** rule runs, it creates a record in the **Execution Log**. -- You can see the **Visual Path Trace**—a highlighted view of exactly which blocks were executed during that specific run. -- Access these logs from the **Rule Execution Log** list or the dashboard on the Rule page. - ---- - -## Related Topics -- [Adding & Managing Blocks]({{< relref "rule-builder/adding-managing-actions" >}}) -- [Using the "Check" Block]({{< relref "action-types/condition" >}}) -- [Working with Variables]({{< relref "action-types/assignment" >}}) -- [Testing with the Debugger]({{< relref "rule-builder/canvas-navigation#debugging-on-the-canvas" >}}) diff --git a/content/en/rule-builder/rule-configuration.md b/content/en/rule-builder/rule-configuration.md new file mode 100644 index 0000000..f9a7c81 --- /dev/null +++ b/content/en/rule-builder/rule-configuration.md @@ -0,0 +1,48 @@ +--- +title: Rule Configuration +description: Learn how to set up the global settings for your rule. +weight: 30 +--- + +# Rule Configuration + +Before you start drawing logic on the canvas, you need to define the "Who, When, and How" of your rule. This is handled in the **Rule Configuration** section, which you can access via the **Configure** button or when creating a new rule. + +## Setup Flow + +Configuring a rule typically follows these steps in the UI: + +### 1. Basic Information +- **Rule Name**: Give your rule a clear, descriptive name (e.g., "Auto-Approve Low Value Orders"). +- **Document Type**: Select the type of record this rule applies to (e.g., "Sales Order" or "Support Ticket"). + +### 2. The Trigger (When) +The **Trigger** defines the specific event that wakes up the rule. +- **Events**: Common triggers include `Before Save`, `After Save`, `On Submit`, or `On Cancel`. +- **Trigger Condition**: You can define a high-level "gatekeeper" condition. If this condition isn't met, the rule won't even start, saving system resources. + - *Example*: `Total Amount > 500` + +### 3. Execution Order (Priority) +If you have multiple rules running on the same event (e.g., three different rules that all run "Before Save" on a Sales Order), you can control which one runs first using **Priority**. +- Rules with a **higher number** run first. +- *Tip*: Use this if Rule B depends on a value calculated by Rule A. + +## The Configuration Modal + +When you click **Configure** on an existing rule, a modal appears allowing you to adjust these settings without leaving the canvas. + +### Dynamic Setup +As you select different Document Types, the available fields for your **Trigger Condition** will automatically update to match. The **Smart Value Selector** is used here to help you pick fields and define logic easily. + +## Advanced Setup (Optional) + +### Order of Operations +In the configuration UI, you can also see a summary of how the rule is positioned relative to other rules in your system. This "execution stack" view helps you ensure that your automation doesn't conflict with other active rules. + +### Performance Settings +For advanced users, the configuration may include toggles for: +- **Asynchronous Execution**: Allowing the rule to run in the background so the user doesn't have to wait for it to finish. +- **Logging Level**: Controlling how much detail is saved in the execution logs for this specific rule. + +## Transitioning to the Canvas +Once your configuration is saved, the **Start** block on the canvas is automatically updated with your document context. Any variables or fields related to your chosen Document Type will now be available in the **Smart Value Selector** throughout your rule. diff --git a/content/en/rule-builder/rule-lifecycle.md b/content/en/rule-builder/rule-lifecycle.md new file mode 100644 index 0000000..092a328 --- /dev/null +++ b/content/en/rule-builder/rule-lifecycle.md @@ -0,0 +1,60 @@ +--- +title: Rule Lifecycle +description: Learn how to manage rules from creation to activation and update. +weight: 70 +--- + +# Rule Lifecycle + +Every automation you build in FlexiRule follows a clear path from a simple idea to a live business process. Understanding this lifecycle ensures you can safely build, test, and update your logic without interrupting your daily operations. + +## The Six Stages of a Rule + +### 1. Creation +Start by giving your rule a name and choosing the Document Type it applies to. This creates a new **Draft** rule and opens the visual canvas. + +### 2. Configuration +Define **When** the rule should run (the Trigger) and **What** it should do (the Logic). +- Use the **Rule Configuration** modal for global settings. +- Use the **Canvas** to draw your business flow. +- Use **Action Settings** to fine-tune each step. + +### 3. Activation +When your logic is complete and tested, click the **Activate** button. +- **Validation**: FlexiRule checks for missing connections or incomplete settings. +- **Locking**: Once active, the rule is locked. You cannot edit a live rule directly, ensuring that no "work-in-progress" changes affect your business data. + +### 4. Execution +The rule is now "Live." Whenever the trigger event occurs (e.g., a Sales Order is saved), FlexiRule automatically runs your logic. You can monitor this in the **Execution Logs**. + +### 5. Update (Amending) +To change a live rule, use the **Amend Rule** button. +- FlexiRule creates a new **Draft** version of your rule. +- The original version stays **Active** and continues to run. +- You can work on the new version safely in the background. When you activate the new version, it will replace the old one. + +### 6. Deactivation +If a rule is no longer needed, you can set it to **Disabled** or **Archived**. +- **Disabled**: The rule stops running but can be easily re-activated later. +- **Archived**: The rule is retired and kept only for historical reference. + +--- + +## Rule States at a Glance + +You can see the current state of a rule in the **Status Badge** at the top of the page. + +| State | Runs on Events? | Can be Edited? | Purpose | +| :--- | :---: | :---: | :--- | +| **Draft** | No | **Yes** | Building and testing new logic. | +| **Active** | **Yes** | No | Live automation. Locked for safety. | +| **Disabled** | No | **Yes** | Temporarily paused logic. | +| **Archived** | No | No | Retired logic for historical records. | + +--- + +## Best Practices for Lifecycle Management + +- **Always Test First**: Use the **Debug Rule** tool while in the **Draft** stage. It allows you to simulate execution with real data without actually changing any records. +- **Clear Naming**: When amending rules, the version history can grow. Use clear names and descriptions to help your team understand why changes were made. +- **Monitor New Rules**: After activating a new or updated rule, keep an eye on the **Execution Logs** for the first few hours to ensure it's behaving exactly as expected in the "real world." From e85b3b7437d0c00dc220389b6aa2177e6300e313 Mon Sep 17 00:00:00 2001 From: abdoruzaqi <245876665+abdoruzaqi@users.noreply.github.com> Date: Sun, 5 Jul 2026 23:38:25 +0000 Subject: [PATCH 2/3] docs: update rule builder section title to Rule Builder Guide --- content/en/rule-builder/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/rule-builder/_index.md b/content/en/rule-builder/_index.md index 557da29..003df81 100644 --- a/content/en/rule-builder/_index.md +++ b/content/en/rule-builder/_index.md @@ -1,10 +1,10 @@ --- -title: Rule Builder +title: Rule Builder Guide weight: 40 description: Learn how to use the visual interface to build and manage your business rules. --- -# Rule Builder +# Rule Builder Guide The Rule Builder is the heart of FlexiRule. it provides a powerful, visual "drag-and-drop" interface that allows you to orchestrate complex business logic without writing code. From 50a84eb0234397c525e3767ff037bd7e08309306 Mon Sep 17 00:00:00 2001 From: abdoruzaqi <245876665+abdoruzaqi@users.noreply.github.com> Date: Sun, 5 Jul 2026 23:55:53 +0000 Subject: [PATCH 3/3] docs: introduce unified Smart Value System documentation - Created smart-value-system.md to define the 3 input modes: Static, Variable (@), and Resolver (/). - Integrated variables entirely into the Smart Value System concept. - Detailed UI mappings for @ and / icons. - Explained conceptual model, scope, and isolation for variables. - Updated Action Settings, Condition Builder, and Rule Builder index to reference the unified system. - Standardized terminology across the Rule Builder documentation. --- content/en/rule-builder/_index.md | 7 +- content/en/rule-builder/action-settings.md | 26 +++--- content/en/rule-builder/condition-builder.md | 9 +- content/en/rule-builder/smart-value-system.md | 85 +++++++++++++++++++ 4 files changed, 105 insertions(+), 22 deletions(-) create mode 100644 content/en/rule-builder/smart-value-system.md diff --git a/content/en/rule-builder/_index.md b/content/en/rule-builder/_index.md index 003df81..1745cd9 100644 --- a/content/en/rule-builder/_index.md +++ b/content/en/rule-builder/_index.md @@ -13,8 +13,9 @@ The Rule Builder is the heart of FlexiRule. it provides a powerful, visual "drag - **[Canvas Navigation]({{< relref "canvas.md" >}})**: Learn how to move around the workspace and arrange your logic blocks. - **[Adding Actions]({{< relref "add-action.md" >}})**: Discover how to use the Action Zone to insert new logic into your flow. - **[Rule Configuration]({{< relref "rule-configuration.md" >}})**: Set up the triggers and global settings that define when your rule runs. +- **[Smart Value System]({{< relref "smart-value-system.md" >}})**: Master the unified system for providing inputs using static values, variables (@), and resolvers (/). - **[Condition Builder]({{< relref "condition-builder.md" >}})**: Build complex logical branches using a simple visual interface. -- **[Action Settings]({{< relref "action-settings.md" >}})**: Configure the details of individual blocks using the Smart Value Selector. +- **[Action Settings]({{< relref "action-settings.md" >}})**: Configure the details of individual blocks. - **[Rule Lifecycle]({{< relref "rule-lifecycle.md" >}})**: Understand the stages of a rule from draft to active production. - **[Debugging & Logs]({{< relref "debugging.md" >}})**: Test your rules safely and troubleshoot live executions. @@ -23,8 +24,8 @@ The Rule Builder is the heart of FlexiRule. it provides a powerful, visual "drag ### Visual Flow FlexiRule represents logic as a flowchart. You can see exactly how data moves from a trigger event to the final outcome. -### No-Code Configuration -Instead of writing scripts, you use the **Smart Value Selector** to pick fields, apply formulas, and set values. +### Unified Input (Smart Values) +Instead of writing scripts, you use the **Smart Value System** to pick fields, apply formulas, and set values. This unified approach works the same way across the entire builder. ### Safety First With built-in **Debugging** and a version-controlled **Lifecycle**, you can build and update automations with confidence, knowing that your live operations are protected. diff --git a/content/en/rule-builder/action-settings.md b/content/en/rule-builder/action-settings.md index 93f6f78..8460db3 100644 --- a/content/en/rule-builder/action-settings.md +++ b/content/en/rule-builder/action-settings.md @@ -16,22 +16,18 @@ While every action has different options, they all share a consistent design: - **Description**: A brief explanation of what the action does. - **Configuration Fields**: The main area where you input data, select options, and define logic. -## Smart Value Selector +## Smart Value Fields -The **Smart Value Selector** is the most important tool within the settings panel. It appears whenever you need to provide a value—whether it's a piece of text, a number, a date, or a reference to another field. +Most settings in FlexiRule use "Smart" fields. These fields allow you to provide data in three different ways: static text, variables, or dynamic functions. -### How to Use It -Click into any field that supports the Smart Value Selector to see your options: +To learn more about the logic behind these fields, see the [Smart Value System]({{< relref "smart-value-system.md" >}}). -1. **Static Input**: Just type a value (like "Hello World" or "100"). -2. **Variable Picker (@)**: Type `@` or click the variable icon to see a list of available data. This includes: - - **Document Fields**: Any field from the record that triggered the rule (e.g., `@doc.customer_name`). - - **Rule Variables**: Values created by earlier "Set Value" or "Query" blocks. - - **Global Constants**: System values like the current date or the current user. -3. **Advanced Resolvers (/)**: Type `/` or click the magic wand icon to access specialized tools: - - **Formulas**: Perform math or combine text (e.g., `{{ @doc.first_name }} {{ @doc.last_name }}`). - - **Formatting**: Change how dates or numbers appear. - - **Logic**: Use "If/Else" statements to pick a value dynamically. +### Quick Access +In any Smart Value field, you can use these shortcuts: + +1. **Static Input**: Just type a value directly into the field. +2. **Variable Picker (@)**: Type `@` or click the variable icon to see a list of available data, such as `@doc.customer_name` or `@rule.total_count`. +3. **Advanced Resolvers (/)**: Type `/` or click the magic wand icon to access tools like math, text formatting, and date calculations. ## Field Types @@ -39,13 +35,13 @@ In the settings panel, you will encounter different types of input controls: - **Dropdowns**: Choose from a fixed list of options. - **Checkboxes**: Toggle settings on or off. -- **Data Grids**: Used for actions like "Set Value," where you need to map multiple fields at once. Each row in the grid uses a Smart Value Selector for the value column. +- **Data Grids**: Used for actions like "Set Value," where you need to map multiple fields at once. Each row in the grid uses a Smart Value field for the value column. - **Multi-Select**: Pick one or more tags or items from a list. ## Context Awareness The settings panel is "Smart." It knows where the block is located in your flow. -- **Available Variables**: You will only see variables in the Smart Value Selector that have actually been defined *before* the current block. +- **Available Variables**: In the `@` menu, you will only see variables that have actually been defined *before* the current block. - **Validation**: Required fields are marked, and the panel will alert you if your configuration is incomplete or contains errors. ## Saving Changes diff --git a/content/en/rule-builder/condition-builder.md b/content/en/rule-builder/condition-builder.md index 5fdf852..218f125 100644 --- a/content/en/rule-builder/condition-builder.md +++ b/content/en/rule-builder/condition-builder.md @@ -22,11 +22,12 @@ A single condition row consists of three main parts: 2. **Operator**: How you are checking it (e.g., `is`, `is not`, `is greater than`, `contains`). 3. **Comparison Value**: What you are checking against (e.g., `Open` or `1000`). -### Using the Smart Value Selector -For both the first and third parts of a condition, you use the **Smart Value Selector**. This tool allows you to: -- Pick fields directly from the document. -- Use variables calculated earlier in the rule. +### Powered by the Smart Value System +For both the first and third parts of a condition, you use the [Smart Value System]({{< relref "smart-value-system.md" >}}). This allows you to: +- Pick fields directly from the document using `@doc`. +- Use variables calculated earlier in the rule using `@rule`. - Enter static text or numbers. +- Use resolver functions with `/` for complex comparisons. ## Grouping Logic (AND / OR) diff --git a/content/en/rule-builder/smart-value-system.md b/content/en/rule-builder/smart-value-system.md new file mode 100644 index 0000000..2afb5f4 --- /dev/null +++ b/content/en/rule-builder/smart-value-system.md @@ -0,0 +1,85 @@ +--- +title: Smart Value System +description: Learn how FlexiRule handles inputs using static values, variables, and resolvers. +weight: 45 +--- + +# Smart Value System + +The **Smart Value System** is the unified way FlexiRule handles data across the entire platform. Whether you are setting a field value, defining a condition, or configuring a notification, you use the same consistent interface to provide data. + +> **The Core Principle**: Every input field in FlexiRule is a "Smart" field that can be a static value, a variable reference, or a dynamically calculated result. + +--- + +## The Three Input Modes + +Every input field in FlexiRule supports three distinct modes of operation. You can switch between these modes seamlessly within the same field. + +### 1. Static Value +This is the simplest mode. You directly type the value you want to use. +- **Text**: `Open`, `High Priority`, `Welcome to FlexiRule` +- **Numbers**: `100`, `0.05`, `-10` +- **Dates**: Picked from a calendar or typed in a standard format. + +### 2. Variable Reference (`@`) +Variables allow you to access live data from your system or values calculated earlier in your rule. You trigger this mode by typing the `@` symbol or clicking the **Variable (@)** icon. + +- **`@doc.*` (Document Variables)**: Access fields from the record that triggered the rule. + - *Example*: `@doc.customer_name`, `@doc.grand_total` +- **`@rule.*` (Rule Variables)**: Access values you have created using "Set Value" or "Query" blocks earlier in the flow. + - *Example*: `@rule.discounted_price`, `@rule.is_valid_customer` +- **`@system.*` (System Variables)**: Access global information. + - *Example*: `@system.current_date`, `@system.current_user` + +### 3. Resolver Functions (`/`) +Resolvers are dynamic functions that transform data or perform calculations on the fly. You trigger this mode by typing the `/` symbol or clicking the **Magic Wand (/)** icon. + +- **Calculations**: `/math.sum`, `/math.multiply` +- **Formatting**: `/date.format`, `/text.upper` +- **Logic**: `/logic.if_else` (Choose a value based on a condition) +- **Combinations**: `/text.concat` (Merge multiple pieces of text and variables) + +--- + +## UI Interactions + +FlexiRule provides visual cues in every input field to help you use the Smart Value System. + +- **Default State**: Just start typing to enter a **Static Value**. +- **The `@` Icon**: Clicking this opens a searchable list of all available variables in the current context. +- **The `/` Icon**: Clicking this opens a menu of available resolver functions. + +When you select a variable or a resolver, the system automatically inserts the correct syntax into the field for you. + +--- + +## Understanding Variables & Scope + +Variables in FlexiRule are designed to be safe and predictable. + +### Execution Lifecycle +Variables created during a rule execution (using `@rule.*`) exist only for that specific run. They are not saved to the database unless you explicitly use an **Update Record** block. + +### Branch Isolation +If your rule splits into a "True" and "False" path, variables created on the "True" path are not available if the logic follows the "False" path. This prevents errors caused by using data that was never actually calculated. + +### Loop Iteration Isolation +When using a **Repeat (Loop)** block, the variables representing the "Current Item" change with every iteration. FlexiRule ensures that the logic inside the loop always uses the correct data for the item being processed. + +--- + +## Where the Smart Value System is Used + +You will find the Smart Value System everywhere you provide input: + +- **Condition Builder**: Comparing fields to variables or calculated values. +- **Action Settings**: Setting email subjects, calculating totals, or mapping fields. +- **Query Records**: Defining filters to find specific data. +- **Notify / Messaging**: Inserting customer names or order IDs into messages. +- **Filters**: Fine-tuning which records a rule should apply to. + +--- + +## Summary +By combining **Static Values**, **@ Variables**, and **/ Resolvers**, you can build incredibly powerful logic without ever leaving the visual interface. It is the single language of data in FlexiRule.