Actions & Steps

Relevant source files

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

• backend/src/workflows/domain/action_entities.py
• frontend/src/lib/constants/step-types.ts
• IMPLEMENTATION_REPORT_SPEC_WFL_003.md
• DDD_IMPLEMENTATION_SUMMARY.md
• ACTION_SYSTEM_GUIDE.md
• FRONTEND_PHASES_4_7_IMPLEMENTATION_SUMMARY.md
• frontend/VISUAL_BUILDER_QUICK_REFERENCE.md

Introduction

Actions and Steps constitute the core operational building blocks of the workflow automation engine. While Triggers initiate a workflow, Actions define the specific tasks performed by the system, ranging from communication (email/SMS) and CRM updates to logic branching and external integrations. The system supports 25+ distinct action types organized into logical categories to facilitate complex automation sequences.

The architecture follows a Clean Domain-Driven Design (DDD) approach where actions are part of the Workflow aggregate. Each action is defined by an immutable configuration and tracked through an execution lifecycle that records status, timing, and outcomes for every contact processed.

Sources: DDD_IMPLEMENTATION_SUMMARY.md, IMPLEMENTATION_REPORT_SPEC_WFL_003.md, FRONTEND_PHASES_4_7_IMPLEMENTATION_SUMMARY.md

Domain Architecture & Entities

The backend logic for actions is centered around three primary domain constructs: the Action entity, the ActionConfig value object, and the ActionExecution entity.

Action Entity

The Action entity represents a specific step within a workflow definition. It manages its position in the sequence and its configuration data. Actions are linked in a sequence via previous_action_id and next_action_id, effectively forming a linked list within the database.

Action Execution

The ActionExecution entity tracks the lifecycle of a single action being performed for a specific contact. It records state transitions from pending to completed or failed, capturing duration and error data.

Domain Model Relationship

The following diagram illustrates the relationship between Workflows, Actions, and their Executions:

Action Categories & Types

The system categorizes actions to simplify the user experience in the Visual Builder. There are over 25 action types implemented across 5-6 major categories.

Category	Description	Key Action Types
Communication	Direct outreach to contacts	send_email, send_sms, make_call, send_messenger
CRM	Modifying contact or pipeline data	add_tag, remove_tag, update_contact, move_pipeline_stage
Timing	Controlling workflow flow over time	wait_time, wait_until_date, wait_for_event
Logic	Branching and goal tracking	if_else, split_test, goal
Internal	System-level notifications and tasks	send_notification, create_task, custom_code
Integration	Connecting with external systems	webhook_call

Sources: frontend/src/lib/constants/step-types.ts, ACTION_SYSTEM_GUIDE.md, DDD_IMPLEMENTATION_SUMMARY.md

Action Execution Lifecycle

The execution of an action follows a strictly defined state machine to ensure reliability and trackability.

The state machine allows for handling asynchronous tasks (like waits) and retries. If an action fails, the system supports exponential backoff and execution logging for debugging.

Sources: backend/src/workflows/domain/action_entities.py:10-25, IMPLEMENTATION_REPORT_SPEC_WFL_003.md

Visual Builder Integration

In the frontend, Actions are represented as "Steps" within the Visual Workflow Builder. Each step is a custom node on a React Flow canvas.

Dynamic Form Generation

The system uses a metadata-driven approach to render configuration forms. Each action type defined in step-types.ts includes a configFields array that specifies the UI components needed (e.g., text inputs, selects, toggles).

Example Action Definition Structure:

{
  type: 'communication.sendEmail',
  category: 'action',
  label: 'Send Email',
  configFields: [
    { name: 'subject', label: 'Subject', type: 'text', required: true },
    { name: 'body', label: 'Email Body', type: 'textarea', required: true }
  ]
}

Drag-and-Drop Workflow

1. Palette: Users select actions from the collapsible Sidebar.
2. Canvas: Actions are added to the React Flow canvas as StepNode components.
3. Configuration: Clicking a node opens the ConfigurationPanel on the right, which generates a form using React Hook Form and Zod validation based on the configFields.

Sources: frontend/src/lib/constants/step-types.ts, FRONTEND_PHASES_4_7_IMPLEMENTATION_SUMMARY.md, frontend/VISUAL_BUILDER_QUICK_REFERENCE.md

Configuration & Validation Rules

To maintain system integrity, several business rules are enforced during the creation and modification of actions:

• Workflow Status: Actions can only be modified (added, updated, deleted) if the parent workflow is in draft or paused status. active workflows are locked to prevent execution inconsistencies.
• Action Limits: A single workflow is capped at a maximum of 50 actions.
• Merge Fields: Many configuration fields support dynamic placeholders using the {{contact.field_name}} syntax, which are resolved at runtime by the execution engine.
• Sequence Integrity: When an action is deleted, the system automatically updates the previous_action_id and next_action_id of the surrounding nodes to maintain the linked list.

Sources: ACTION_SYSTEM_GUIDE.md, IMPLEMENTATION_REPORT_SPEC_WFL_003.md, DDD_IMPLEMENTATION_SUMMARY.md

API Reference for Action Management

The system provides a RESTful interface for managing actions within a workflow.

Method	Endpoint	Description
POST	/api/v1/workflows/{id}/actions	Adds a new action to the workflow.
GET	/api/v1/workflows/{id}/actions	Lists all actions in the specified workflow.
PUT	/api/v1/workflows/{id}/actions/{action_id}	Updates the configuration or status of an action.
POST	/api/v1/workflows/{id}/actions/reorder	Bulk updates positions and links for actions.

Sources: ACTION_SYSTEM_GUIDE.md, IMPLEMENTATION_REPORT_SPEC_WFL_003.md

Summary

The Actions & Steps system provides a robust framework for defining and executing automated tasks. By combining a flexible domain model in the backend with a dynamic, metadata-driven UI in the frontend, the platform allows users to build complex, multi-stage automations while ensuring data integrity through strict validation and execution tracking.