Automations & Automation Runs
Relevant source files
The following files were used as context for generating this wiki page:
The Automations module manages automated workflows that execute predefined steps based on specific triggers. It allows you to create, update, list, and control the lifecycle of automated processes, such as email sequences or contact management tasks.
The Automation Runs submodule tracks the execution history of these workflows. It provides visibility into the status, timing, and output of individual steps within a specific automation instance.
Automations Management
The Automations class provides methods to manage the configuration and lifecycle of workflows. It interacts with the /automations API endpoints to perform CRUD operations and control execution states.
Core Architecture
The system uses a graph-based structure where workflows consist of steps connected by connections.
The Automations class initializes a runs property as an instance of AutomationRuns to handle execution data.
Sources: src/automations/automations.ts:44-48, src/common/utils/parse-automation-to-api-options.ts:114-121
Lifecycle Operations
You can control the state of an automation using specific methods:
- Create: Submits a payload containing name, steps, and connections.
- Update: Modifies existing automation fields, including partial updates to steps or status.
- Stop: Halts a running automation and sets its status to
disabled. - Duplicate: Creates a new copy of an existing automation.
- Remove: Deletes an automation record.
Sources: src/automations/automations.ts:50-136, src/automations/automations.spec.ts:333-366
Automation Steps and Connections
Workflows are defined by discrete steps and the logic that links them.
Step Types
Each step requires a unique key, a type, and a specific config object.
| Step Type | Description | Configuration Fields |
|---|---|---|
trigger | Starts the automation | eventName |
delay | Pauses execution | duration |
send_email | Sends a template-based email | template, subject, from, replyTo |
wait_for_event | Pauses until an event occurs | eventName, timeout, filterRule |
condition | Evaluates logic | ConditionRule (field, operator, value) |
contact_update | Modifies contact data | firstName, lastName, unsubscribed, properties |
contact_delete | Removes a contact | (Empty object) |
add_to_segment | Adds contact to a segment | segmentId |
Sources: src/automations/interfaces/automation-step.interface.ts:83-91, src/common/utils/parse-automation-to-api-options.ts:50-101
Connection Logic
Connections define the path between steps using from and to keys. They support conditional routing via the type field.
Automation Runs
The AutomationRuns class retrieves data about the execution of automations. It accesses endpoints nested under specific automations: /automations/{automationId}/runs.
Execution Tracking
When an automation triggers, the system creates an automation_run object. This object tracks the progression through the defined steps.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the run |
status | string | Current state (e.g., completed, running, failed) |
started_at | string | ISO timestamp of start |
completed_at | string | ISO timestamp of completion |
steps | array | Detailed status of each executed step |
Sources: src/automation-runs/automation-runs.ts:16-24, src/automation-runs/automation-runs.spec.ts:25-34
Data Flow for Runs
Data Transformation
The module uses utility functions to transform camelCase SDK options into the snake_case format required by the API.
parseAutomationToApiOptions: Maps the top-level automation structure.parseStepConfig: Handles specific transformations for different step types, such as mappingeventNametoevent_nameorreplyTotoreply_to.parseConnection: Ensures connection metadata is formatted correctly.
Sources: src/common/utils/parse-automation-to-api-options.ts:49-121
Summary
The Automations system provides a programmable interface for constructing complex, event-driven workflows. By combining varied step types with conditional connections and execution tracking via Automation Runs, you can automate communication and data management tasks while maintaining full visibility into the lifecycle of every automated process. Sources: src/automations/automations.ts, src/automation-runs/automation-runs.ts