Logic: Conditions & Waits

Relevant source files

The following files were used as context for generating this wiki page:

• backend/src/workflows/domain/condition_evaluators.py
• backend/src/workflows/application/wait_service.py
• backend/src/workflows/infrastructure/condition_repository.py
• IMPLEMENTATION_REPORT_SPEC_WFL_003.md
• DDD_IMPLEMENTATION_REPORT_SPEC_WFL_005.md
• FRONTEND_PHASES_4_7_IMPLEMENTATION_SUMMARY.md

The Logic: Conditions & Waits system provides the decision-making and timing capabilities of the workflow automation engine. It allows workflows to branch based on contact data or events (If/Else logic) and pause execution for specific durations or until certain criteria are met. This system ensures that automation is dynamic and responsive to real-time data rather than purely linear.

These components work in tandem with the Action System and the core Execution Engine. Conditions evaluate the path a contact should take, while Waits manage the lifecycle of an execution during idle periods. Sources: IMPLEMENTATION_REPORT_SPEC_WFL_003.md, DDD_IMPLEMENTATION_REPORT_SPEC_WFL_005.md

Logic Components Architecture

The logic system is divided into two primary categories: branching logic and timing logic. Branching logic (Conditions) uses an evaluator to determine the next step in a sequence, while timing logic (Waits) interacts with a scheduler to resume execution after a delay.

Logic Flow Diagram

The following diagram illustrates how the execution engine interacts with the logic system to determine the workflow path.

Conditions: Branching and Evaluation

Conditions enable if/else branching and split testing within a workflow. The evaluation process is managed by specific domain evaluators that compare contact attributes or event data against defined criteria.

If/Else Condition

The logic.ifElse step allows for multiple conditions joined by logical operators (AND/OR). It supports branching paths based on various data points.

Component	Description
Logic Operator	Supports AND/OR logic for multiple criteria.
Path Configuration	Defines the "True" and "False" branches for the workflow.
Data Points	Can evaluate contact fields, tags, or previous action results.

Sources: FRONTEND_PHASES_4_7_IMPLEMENTATION_SUMMARY.md:Phases 6

Condition Evaluators

The evaluation logic is encapsulated in domain-level evaluators. These components categorize errors into terminal (validation/auth) or retryable (network/timeout) failures.

# Simplified Logic Implementation
- logic.ifElse: Supports multiple conditions and branch paths.
- logic.splitTest: Handles A/B testing logic for path distribution.

Sources: FRONTEND_PHASES_4_7_IMPLEMENTATION_SUMMARY.md:Phase 5, DDD_IMPLEMENTATION_REPORT_SPEC_WFL_005.md:Error Handling Strategy

Waits: Timing and Scheduling

Timing actions pause the workflow execution. There are three primary types of wait operations implemented in the system.

Wait Types

The system supports both relative and absolute timing logic:

1. Wait Time (timing.wait): Pauses for a relative duration (e.g., 5 minutes, 2 days).
2. Wait Until (timing.waitUntil): Pauses until a specific absolute date and time is reached.
3. Wait for Event (timing.waitForEvent): Pauses until a specific event (like a tag being added) occurs.

Sources: FRONTEND_PHASES_4_7_IMPLEMENTATION_SUMMARY.md:Phase 5, IMPLEMENTATION_REPORT_SPEC_WFL_003.md:R4

Wait Execution Flow

When a WaitTimeExecutor is triggered, it calculates the resume_at timestamp and transitions the execution state to WAITING.

Data Models and State

Wait and Condition logic rely on the WorkflowExecutionModel to persist state across sessions.

State Transitions

Logic steps influence the following status transitions in the WorkflowExecution aggregate:

• ACTIVE → WAITING: Occurs when a wait_time or wait_until step is encountered.
• WAITING → ACTIVE: Occurs when the scheduler detects the resume time has passed.
• ACTIVE → ACTIVE: Condition evaluation immediately advances the current_step_index to the appropriate branch.

Sources: DDD_IMPLEMENTATION_REPORT_SPEC_WFL_005.md:Phase 3

Table: Logic Configuration Fields

Configuration fields for logic nodes are dynamically generated based on the step definition.

Field Type	Usage in Logic	Example
select	Operator selection	AND, OR, EQUALS
datetime	Absolute wait	Resume on 2026-01-01
number	Relative wait	Wait for 5 (minutes)
toggle	Boolean logic	Is active? (True/False)

Sources: FRONTEND_PHASES_4_7_IMPLEMENTATION_SUMMARY.md:Field Types Supported

Conclusion

The Logic: Conditions & Waits module provides the essential "intelligence" of the workflow engine. By implementing a robust state machine that supports WAITING statuses and a flexible condition evaluator for if/else branching, the system can handle complex, multi-path automation scenarios. The architecture ensures that these steps are auditable through the ExecutionLog and can safely resume without data loss.