The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
---
title: Workflows
description: Ship ready-made workflows with your app.
---
import { PageBanner } from "/snippets/page-banner.mdx"
## Define a workflow
Apps can ship workflows. Each `defineWorkflow()` call describes one workflow: a trigger and the steps it runs. On install, Twenty creates it as an active workflow in the workspace, ready to run.
This workflow runs when a company is created. It calls one of the app's logic functions, then writes the result on the company:
```ts src/workflows/score-new-companies.ts
import {
defineWorkflow,
STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';
const COMPANY = STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier;
const SCORE_COMPANY_FUNCTION = '0f6c0b3e-8a4f-4f0e-9d0a-3c1e5b7a2d41';
const SCORE_NEW_COMPANIES = {
workflow: 'c2a4e6f8-1b3d-4f5a-8c7e-9d0b2a4c6e81',
trigger: 'c2a4e6f8-1b3d-4f5a-8c7e-9d0b2a4c6e82',
score: 'c2a4e6f8-1b3d-4f5a-8c7e-9d0b2a4c6e83',
save: 'c2a4e6f8-1b3d-4f5a-8c7e-9d0b2a4c6e84',
};
export default defineWorkflow({
universalIdentifier: SCORE_NEW_COMPANIES.workflow,
name: 'Score new companies',
version: {
trigger: {
universalIdentifier: SCORE_NEW_COMPANIES.trigger,
type: 'DATABASE_EVENT',
settings: {
objectUniversalIdentifier: COMPANY,
action: 'created',
},
nextStepIds: [SCORE_NEW_COMPANIES.score],
},
steps: [
{
universalIdentifier: SCORE_NEW_COMPANIES.score,
name: 'Score the company',
type: 'LOGIC_FUNCTION',
logicFunctionUniversalIdentifier: SCORE_COMPANY_FUNCTION,
input: { companyName: '{{trigger.properties.after.name}}' },
nextStepIds: [SCORE_NEW_COMPANIES.save],
},
{
universalIdentifier: SCORE_NEW_COMPANIES.save,
name: 'Save the score',
type: 'UPDATE_RECORD',
input: {
objectUniversalIdentifier: COMPANY,
objectRecordId: '{{trigger.recordId}}',
objectRecord: { leadScore: `{{${SCORE_NEW_COMPANIES.score}.score}}` },
fieldsToUpdate: ['leadScore'],
},
nextStepIds: [],
},
],
},
});
```
Key points:
- The workflow and each step need their own `universalIdentifier`, and the trigger can have one. Keep them stable across releases: they are how Twenty matches the installed workflow on the next install.
- `nextStepIds` wires the graph. The trigger points to the first steps, and each step points to the steps that run after it.
- A step reads earlier output with `{{trigger.<path>}}` or `{{<step universalIdentifier>.<path>}}`.
- The build validates the whole definition: unsupported trigger or step types, broken step links and references to unknown steps fail it.
- `isSystem` (optional, defaults to `false`) hides the workflow from the lists that leave out system workflows. It only changes what is displayed.
## Referencing other entities
Steps and triggers point at metadata by universal identifier, never by name or id:
- **Objects and fields**: your app's own, or standard ones through `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`. The example above assumes the app also defines a `leadScore` number field on Company with [`defineField()`](/developers/extend/apps/data/extending-objects): a record step that writes a field missing from the workspace fails the install.
- **Logic functions**: your app's own, exposed as a [workflow action](/developers/extend/apps/logic/logic-functions#exposing-a-function-as-an-ai-tool-or-workflow-action) with `workflowActionTriggerSettings`. The workspace Custom application can also reference the workflow actions of the other apps installed in the workspace, as workflows built in the app can.
- **Agents**: your app's own, from [`defineAgent()`](/developers/extend/apps/logic/skills-and-agents).
A reference Twenty can't resolve fails the install.
## Triggers
| Type | Runs when | Settings |
|------|-----------|----------|
| `MANUAL` | A user launches it | `availability` (optional): `GLOBAL`, or `SINGLE_RECORD` / `BULK_RECORDS` with an `objectUniversalIdentifier`. Adds a command menu entry, with an optional `icon` and `isPinned`. |
| `CRON` | On a schedule | `type`: `DAYS`, `HOURS` or `MINUTES` with a `schedule`, or `CUSTOM` with a cron `pattern`. |
| `DATABASE_EVENT` | A record changes | `objectUniversalIdentifier`, `action` (`created`, `updated`, `deleted`, `upserted`), optional `fieldUniversalIdentifiers` to watch (updates and upserts only) and `filter`. |
| `WEBHOOK` | An HTTP request reaches the workflow URL | `httpMethod` (`GET` or `POST`), and `expectedBody` for `POST`. |
A manual workflow without `availability` gets no command menu entry.
Every trigger also takes optional `name`, `position` and `outputSchema`, which only shape how the workflow looks in the builder. Without them, Twenty uses a name such as `Manual trigger`, places the trigger at the top of the canvas and computes the output schema from the settings.
A webhook workflow listens on `https://<your-twenty-domain>/webhooks/workflows/<workspaceId>/<workflowId>`, where `workflowId` is the id of the installed workflow. The request body is available as `{{trigger.<path>}}`.
## Steps
Application workflows support these step types: `LOGIC_FUNCTION`, `AI_AGENT`, `HTTP_REQUEST`, `CLASSIFY`, `CREATE_RECORD`, `UPDATE_RECORD`, `UPSERT_RECORD`, `DELETE_RECORD`, `FIND_RECORDS`, `PICK_RECORD`, `FILTER`, `IF_ELSE`, `ITERATOR`, `FORM`, `DELAY`, `WAIT_FOR_EVENT`, `SEND_EMAIL`, `DRAFT_EMAIL`, `CREATE_CALENDAR_EVENT`, `SEND_CHAT_MESSAGE` and `EMPTY`.
Their inputs match the steps of the [workflow builder](/user-guide/workflows/capabilities/workflow-actions), with universal identifiers in place of names:
- Record steps take `objectUniversalIdentifier` instead of an object name.
- Filters and sorts point at fields with `fieldMetadataUniversalIdentifier`.
- Filter operands take `ViewFilterOperand` values, exported by `twenty-sdk/define`. Filter group operators take string values such as `'AND'` or `'OR'`.
- Form fields of type `RECORD` name their object with `settings.objectUniversalIdentifier`. Fields of type `SELECT` and `MULTI_SELECT` offer the options of an existing field of the same type, named with `settings.selectedFieldUniversalIdentifier`.
- To run your own code, use a `LOGIC_FUNCTION` step. The builder's Code step is not available.
- `AI_AGENT` steps come in two kinds, which you can't mix:
- A Generate step has no agent. It carries its own `instructions`, `modelId`, `modelConfiguration` and `scope`, and runs once: no conversation, no human input, no waiting.
- An Agent step runs one of your app's agents, named with `agentUniversalIdentifier`, which brings its own instructions, model and permissions. Only an Agent step takes `humanInputInstructions` and `conversation`.
Both kinds take the builder's `prompt` and `responseFormat`, and `workspaceMemberId` for the member the agent's conversation is with.
- An `AI_AGENT` step's `scope` takes a role's permissions without its identity or row-level predicates: `canReadAllObjectRecords`, `objectPermissions` and `fieldPermissions` by universal identifier, `permissionFlagUniversalIdentifiers`, and so on. It only restricts: the step's AI never reaches more than whoever runs the workflow. It resolves like a role whose all-records flags default to off: object actions and permission flags it doesn't grant are denied, system objects stay readable unless it grants more, and a field it doesn't list follows its object. A Generate step without a `scope` gets no data tools; an Agent step runs with its agent's role.
- Email and calendar steps run only if your app's role has the matching permission flag: `SystemPermissionFlag.SEND_EMAIL_TOOL` for `SEND_EMAIL` and `DRAFT_EMAIL`, `SystemPermissionFlag.CREATE_CALENDAR_EVENT_TOOL` for `CREATE_CALENDAR_EVENT`. The workspace grants it by installing the app, and the step can then use any connected account in the workspace, like a workflow built in the app.
- Connected account ids are local to each workspace, so don't hardcode one. Name the account in one of two ways:
- `connectedAccountHandle`: the account's email address, such as `'[email protected]'`. When the app is synced, the handle resolves to an account with that address that is shared with the workspace (`WORKSPACE` scope) and can run the step. A member's private account can't be named by handle: pull keeps it as its `connectedAccountId`. If several accounts share the address, for example one mailbox connected by two members or through two providers, the oldest one wins. If none matches, the sync fails and names the handle. This is not `fromHandle`, which picks an alias to send from.
- `connectedAccountId`: a variable, such as `{{trigger.properties.after.connectedAccountId}}`. Email steps also take a workspace member id, such as `{{trigger.properties.after.assigneeId}}`, which resolves to that member's first account able to send.
Set exactly one of the two.
- `SEND_CHAT_MESSAGE` posts to a workspace member's inbox, set with `workspaceMemberId`. Member ids are local to each workspace too, so an app passes a variable, such as `{{trigger.properties.after.assigneeId}}`.
## After install
- The workflow is active as soon as the app is installed, and its runs appear with the workspace's other workflow runs.
- Installing a new version of the app updates the workflow in place.
- Users can't edit an installed workflow. To customize one, they duplicate it: the copy is theirs to edit.
## Workflows of the workspace Custom application
The workspace Custom application owns the workflows built in the workflow builder, and code is as authoritative for them as the builder:
- `twenty app pull` writes each one from its active version, the one the builder last published. A workflow whose active version uses settings a `defineWorkflow()` file can't express, such as a Code step, is reported and left in place.
- A pulled workflow keeps what the builder stored: a trigger without a `universalIdentifier`, the trigger's builder name, a `position` of `null` for a node the builder never placed, and an `outputSchema` that differs from the computed one. These fields need twenty-sdk 2.53.0 or later, applied to a server on 2.53.0 or later: older versions reject them as unknown keys.
- `twenty app apply` publishes like the builder. A workflow whose definition matches its active version is left alone. Otherwise the active version is archived and the definition becomes a new active version, so past runs keep the version they ran.
- Users keep editing these workflows in the builder, and the next pull brings their changes back.
<PageBanner illustration="card-page-workflows" />