Skip to main content
Version: Current

Deep Dive: Automation with Sentences

Introduction​

Sentences are Zudello's primary tool for automating business processes and enforcing custom rules without requiring traditional coding. They allow administrators and power users to define workflows using a natural language-like structure, specifying triggers, conditions, and actions. Sentences drive key functionalities like approval routing, status updates, notifications, data validation, and integration triggers.

Understanding how Sentences work is fundamental to customizing Zudello to meet specific business needs and achieving significant automation benefits. This guide explores the core concepts, configuration, execution logic, and best practices for using Sentences effectively.

See also: Zudello v3 Architecture Overview

Core Concepts​

A Sentence is composed of three main parts:

  1. Trigger: The event that initiates the Sentence evaluation.
  2. Conditions: The criteria that must be met for the Sentence's actions to execute.
  3. Actions: The tasks the Sentence performs if the conditions are met.

1. Triggers​

Triggers define when a Sentence should run. Zudello offers several trigger types:

  • Resource Event: Fires when a specific event occurs on the primary resource (e.g., the document being viewed or processed).
    • When a resource is created: Runs immediately after a new record (e.g., Invoice, PO, Supplier) is created.
    • When a resource is extracted: Runs after the Enrichment process completes for an extracted document (uploaded/emailed). This is a common trigger for initial validation and routing. Note: Does not fire for manually created documents.
    • When a resource is submitted: Runs when a user clicks the "Save and Submit" button (if enabled on the form). The document status is typically set to PROCESSING just before this trigger fires.
    • When a resource status has changed: Runs whenever the status field of the resource changes. This is frequently used to progress documents through workflows (e.g., trigger approval when status changes to APPROVAL, trigger integration when status changes to COMPLETE).
    • When an approval outcome is received: Runs after an approval milestone associated with the resource is completed (either APPROVED or REJECTED). Used to handle the next steps after an approval decision.
  • Related Resource Updated: Fires when a related resource linked to the primary resource is updated.
    • Example: Trigger an update on a Purchase Order when a related Invoice linked via Allocations is marked as COMPLETE.
    • Requires careful configuration of the relationship (e.g., Invoice related to Order via Allocations).
  • User Event: Fires when a user manually clicks a specific button or action configured as a "Quick Action".
    • Example: A button labelled "Request Urgent Review" triggers a Sentence to assign a specific user and send a notification.
  • Scheduled: Fires at a predefined time or interval (e.g., daily, weekly, specific time).
    • Example: Run a Sentence every Monday morning to find overdue approvals and send reminder notifications.

2. Conditions​

Conditions define if the Sentence's actions should execute after being triggered. All conditions within a single Sentence must evaluate to TRUE (AND logic) for the actions to run.

Common condition types include checking:

  • Field Values: Compare a field on the resource (or a related resource) to a specific value.
    • Operators: Equals, Does not equal, Greater than, Less than, Is set, Is not set, Contains, Does not contain, Starts with, Ends with.
    • Examples: Total Amount Local | Greater than | 1000; Supplier Name | Contains | Urgent; Department | Is not set.
  • Status: Check the current status or status_type of the resource.
    • Example: Status | Equals | READY; Status Type | Equals | APPROVAL.
  • Allocation Status: Check the matching status against related documents (e.g., Invoice vs. PO).
    • Fields: Allocation Status (Order), Allocation Status (Receipt).
    • Values: FULL, PARTIAL, INVALID.
    • Example: Allocation Status (Order) | Equals | FULL. See Understanding Allocation Statuses.
  • Variance: Check the calculated variance between allocated documents (primarily for quantity-based matching).
    • Fields: Variance Amount Local (Order), Variance Percentage (Order).
    • Operators: Greater than, Less than, Equals, etc.
    • Example: Variance Percentage (Order) | Greater than | 5. See Understanding and Resolving Variances.
  • Budget Exceptions: Check if the transaction triggers a budget exception.
    • Fields: Budget Exception.
    • Operators: Equals, Does not equal, Is set, Is not set.
    • Values: Over Budget, Out of Budget, Off Budget.
    • Example: Budget Exception | Is set. See Budgets Module - Budget Evaluation Process.
  • Validation Level: Check the highest severity level of any active validation issues on the resource.
  • Check Validation: Check if a specific validation rule (usually from an Extension) has failed.
    • Example: Check Validation | Equals | Validate document notes.

3. Actions​

Actions define what the Sentence does if the trigger occurs and all conditions are met. Multiple actions can be configured per Sentence and run sequentially.

Common actions include:

  • Set Field: Update the value of one or more fields on the resource.
    • Example: Set Status to APPROVAL; Set Assignee to a specific user; Set Department based on Supplier.
  • Get Approval: Initiate an approval process by creating approval milestones and steps. This is a complex action with many sub-options:
    • Approval Type: User, User Group, DOA, Management Tree, Submitter/Creator of Related Resource, Assignee.
    • Milestone/Step Naming: Define how steps appear in the UI.
    • Notify: Send notifications to approvers?
    • Apply Previous: Auto-action step based on user's previous response in the same flow? See Remember Response Not Applying.
    • Include Submitter: Allow/prevent the document submitter from approving this step? See Self-Approval Prevention.
    • Reminders/Escalations: Configure automatic reminders or escalations for overdue approvals. See Managing Notification Settings, Escalation Not Working Correctly.
  • Run Trigger: Trigger another Sentence or a backend Workflow (used for integrations).
  • Send Email: Send a customized email notification.
  • Generate PDF: Create a PDF document based on a configured template.
  • Consolidate: Merge multiple lines into a single summary line based on specified dimensions.
  • Assign: Add or remove users from the assignees field.
  • Duplicate: Create a copy of the current resource.
  • Save & Refresh: Save changes made by previous actions in the same Sentence and re-run backend validations. Useful for checking if automated field updates resolved validation errors before proceeding.
  • And cancel processing: Stop any further Sentences with the same trigger from running for this event instance. Crucial for preventing conflicting workflows.

Sentence Builder Interface​

Sentences are managed via Settings > Automations. The interface allows you to:

  • Create/Edit: Define the Name, Description, Trigger, Conditions, and Actions.
  • Order: Set the execution order for Sentences sharing the same trigger. Lower numbers run first.
  • Activate/Deactivate: Enable or disable Sentences.

Execution Logic​

  • Triggering: When an event occurs (e.g., status change), the Automation service finds all active Sentences configured for that specific trigger.
  • Ordering: Sentences are evaluated based on their configured Order number (lowest first).
  • Condition Evaluation: For the first Sentence in order, all its conditions are checked.
    • If all conditions are TRUE, the Sentence's actions are executed sequentially.
    • If any condition is FALSE, the Sentence's actions are skipped, and the engine moves to the next Sentence in the order.
  • "And cancel processing": If a Sentence's actions execute and it includes the "And cancel processing" action, no further Sentences for that trigger event instance will be evaluated or run. This prevents multiple conflicting workflows from executing simultaneously. If this action is not included, the engine continues evaluating the next Sentence in order, potentially leading to multiple Sentences running for the same event.
  • Timing: Sentences generally run after the Enrichment process completes for extracted documents or after a user saves/submits a document. Be mindful of potential race conditions if multiple events happen in rapid succession.

Common Use Cases​

  • Approval Workflows:
    • Route invoices over $1000 to the Finance Manager group.
    • Route POs based on Department and Amount using DOA.
    • Require variance approval if Invoice differs from PO by > 5%.
    • Send approved claims to the "Ready for Payment" status.
  • Status Updates:
    • Set PO status to COMPLETE when related Invoice and Receipt statuses are COMPLETE.
    • Set Invoice status to REVIEW if Enrichment fails to link a Supplier.
    • Set Expense status to POLICY_REVIEW if amount exceeds policy limits.
  • Notifications:
    • Email the submitter when their claim is rejected, including the rejection reason.
    • Notify the Procurement team via Slack when a high-value PO is approved.
  • Data Manipulation:
    • Set default Location based on the selected Subsidiary.
    • Assign the relevant Project Manager based on the Project Code entered.
    • Duplicate an approved Requisition to create a draft Purchase Order.
  • Integration Triggers:
    • When Invoice status changes to COMPLETE, run the "Sync to ERP" Workflow.

Debugging and Best Practices​

  • Automation Logs: Administrators (and Staff) can view Automation Logs (often via the document's History tab or Staff menu) to see which Sentences were triggered, which conditions passed/failed, and which actions were executed for a specific document. This is crucial for troubleshooting.
  • Test Thoroughly: Create test documents covering various scenarios (different amounts, suppliers, coding, statuses) to ensure Sentences trigger and route as expected. Use test users for approval steps.
  • Clear Naming Conventions: Use descriptive names for Sentences (e.g., "Route Invoice > $1k to Finance Mgr").
  • Keep Sentences Focused: Avoid creating single Sentences with overly complex conditions and actions. Break down complex workflows into multiple, smaller Sentences triggered by specific status changes or events.
  • Use "And cancel processing": Carefully consider when to use this action to prevent unintended consequences from multiple Sentences firing for the same event. If multiple outcomes are possible based on conditions (e.g., route to Manager A if < $5k, route to Manager B if >= $5k), ensure each path ends with "And cancel processing".
  • Understand Trigger Timing: Be aware of when triggers fire (e.g., Extracted vs. Submitted vs. Status Changed) and how this interacts with data availability (e.g., Enrichment data is available for Extracted, user-entered data is available for Submitted).

Sentences provide a powerful, flexible way to tailor Zudello's behaviour. By understanding their components and execution logic, you can automate complex processes, enforce compliance, and significantly improve operational efficiency.