Workflows & Automation
Relevant source files
The following files were used as context for generating this wiki page:
- packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts
- packages/twenty- front/src/locales/generated/en.ts
- packages/twenty-e2e-testing/lib/fixtures/blank-workflow.ts
- packages/twenty-shared/src/constants/DocumentationPaths.ts
- packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md
Workflows and automation in Twenty provide a powerful framework for streamlining business processes by connecting events within the CRM to automated actions. This system allows users to define logic that executes automatically based on triggers such as database changes, manual invocations, or scheduled time intervals.
The architecture is built around a sequence of steps, where the output of one step can be referenced by subsequent steps using a specific templating syntax. This enables complex data flows, such as creating related records, sending emails, or executing custom serverless code functions in response to CRM activity.
Sources: packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts:25-30, packages/twenty-e2e-testing/lib/fixtures/blank-workflow.ts:25-50
Core Components
The automation engine is comprised of three primary entities: Triggers, Steps, and Runs. Together, they define the lifecycle of an automation from definition to execution.
Triggers
Triggers are the starting point of any workflow. They define the conditions under which a workflow begins its execution.
- DATABASE_EVENT: Fires when a record is created, updated, or deleted.
- MANUAL: Launched directly by a user from the interface.
- CRON: Executed on a recurring schedule (e.g., daily, hourly).
- WEBHOOK: Triggered by an incoming HTTP request from an external system.
Sources: packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts:32-35, packages/twenty-e2e-testing/lib/fixtures/blank-workflow.ts:52-57
Steps and Actions
Steps represent individual units of logic within a workflow version. Each step performs a specific action and produces an output schema that can be consumed by later steps.
| Step Type | Description |
|---|---|
| CREATE_RECORD | Creates a new record in a specified CRM object. |
| UPDATE_RECORD | Modifies existing record fields based on inputs. |
| DELETE_RECORD | Removes a record from the database. |
| SEND_EMAIL | Sends an email using configured SMTP/Gmail/Outlook integrations. |
| CODE | Executes a custom TypeScript serverless function. |
| LOGIC_FUNCTION | Executes a function provided by an installed Twenty App. |
Sources: packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts:33-80, packages/twenty-e2e-testing/lib/fixtures/blank-workflow.ts:40-50
Workflow Lifecycle
Workflows transition through several states, primarily moving from a Draft phase to an Active phase. A "Workflow Version" system allows for iterative development without breaking live automations.
The diagram above illustrates the typical path from workflow creation to execution and status tracking.
Sources: packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts:80-85, packages/twenty-e2e-testing/lib/fixtures/blank-workflow.ts:85-110
Data Flow and Templating
Workflows use a double-curly-brace syntax to pass data between steps. A step can access the results of a previous step using the format {{stepId.fieldName}}. For relationships, nested objects are used to link records (e.g., {"company": {"id": "{{reference}}"}}).
Recurring Schedules (CRON)
The CRON trigger supports sophisticated scheduling configurations. The system requires an exact schema for different interval types:
- DAYS: Daily schedule requiring a specific day, hour (0-23), and minute (0-59).
- HOURS: Hourly schedule (e.g., every 2 hours) at a specific minute past the hour.
- MINUTES: Minute-based intervals (e.g., every 15 minutes).
- CUSTOM: Standard cron expression pattern (e.g.,
0 * * * *).
Logic Functions and External Integration
Logic functions allow workflows to extend beyond native CRM actions. They are categorized into two types:
- Native Code Steps: Users write TypeScript directly in the workflow builder. These are handled as serverless functions with a specific
logicFunctionId. - App Logic Functions: Functions registered by external apps installed in the workspace. Users can discover these using
list_logic_function_toolsbefore adding them to a workflow.
The sequence diagram shows how logic functions act as a bridge between the workflow engine and external services or custom code.
Sources: packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts:57-75
Workflow Visualization and Management
In the Twenty front-end, workflows are managed through a "Workflow Visualizer." This interface provides specialized controls for adding triggers, manipulating the node graph, and viewing execution logs.
Key Management Actions
- Activate/Deactivate: Toggles whether a workflow will fire on its triggers.
- See Runs: Navigates to a list of historical executions (Workflow Runs) to inspect successes or failures.
- Discard/Override Draft: Manages the local workspace changes compared to the active version.
Sources: packages/twenty-e2e-testing/lib/fixtures/blank-workflow.ts:15-38, packages/twenty-front/src/locales/generated/en.ts:1
Summary
Workflows & Automation serve as the logical nervous system of the Twenty CRM. By utilizing a robust trigger-action model, flexible data templating, and the ability to execute custom logic functions, it enables automated data enrichment, complex notification systems, and seamless integrations with third-party tools. The system ensures reliability through built-in validation and a versioning lifecycle that supports safe iteration from draft to production.