The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Document application workflows (#28199)
Thomas Trompette2834c2e85584
diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdxindex 2286caad09e..205df2cdb48 100644--- a/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdx@@ -45,6 +45,7 @@ your-app/| **Logic Function** | Server-side TypeScript with triggers | [Logic Functions](/developers/extend/apps/logic/logic-functions) || **Skill** | Reusable AI agent instructions | [Skills & Agents](/developers/extend/apps/logic/skills-and-agents) || **Agent** | AI assistants with custom prompts | [Skills & Agents](/developers/extend/apps/logic/skills-and-agents) |+| **Workflow** | Ready-made workflows with a trigger and steps | [Workflows](/developers/extend/apps/logic/workflows) || **Connection Provider** | OAuth credentials for third-party APIs | [Connections](/developers/extend/apps/logic/connections) || **View** | Pre-configured record list views | [Views](/developers/extend/apps/layout/views) || **Navigation Menu Item** | Custom sidebar entries | [Navigation Menu Items](/developers/extend/apps/layout/navigation-menu-items) |diff --git a/packages/twenty-docs/developers/extend/apps/logic/overview.mdx b/packages/twenty-docs/developers/extend/apps/logic/overview.mdxindex d5cdf59b5e7..3e06e5d5673 100644--- a/packages/twenty-docs/developers/extend/apps/logic/overview.mdx+++ b/packages/twenty-docs/developers/extend/apps/logic/overview.mdx@@ -31,6 +31,9 @@ A Twenty app's **logic layer** is the code that *runs* — server-side TypeScrip<Card title="Skills & Agents" icon="robot" href="/developers/extend/apps/logic/skills-and-agents">Reusable AI agent instructions and assistants with custom system prompts.</Card>+ <Card title="Workflows" icon="diagram-project" href="/developers/extend/apps/logic/workflows">+ Ready-made workflows installed with your app: triggers, steps, and how they run.+ </Card><Card title="Connections" icon="plug" href="/developers/extend/apps/logic/connections">OAuth credentials your app holds for third-party services — Linear, GitHub, Slack, and more.</Card>diff --git a/packages/twenty-docs/developers/extend/apps/logic/workflows.mdx b/packages/twenty-docs/developers/extend/apps/logic/workflows.mdxnew file mode 100644index 00000000000..e63782be3cf--- /dev/null+++ b/packages/twenty-docs/developers/extend/apps/logic/workflows.mdx@@ -0,0 +1,109 @@+---+title: Workflows+description: Ship ready-made workflows with your app.+icon: "diagram-project"+---++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.++## Define a workflow++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, its trigger and each step need their own `universalIdentifier`. 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.++## 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`.+- **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.++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` 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`.+- To run your own code, use a `LOGIC_FUNCTION` step. The builder's Code step is not available, and neither are the email and calendar steps.++## 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.diff --git a/packages/twenty-docs/docs.json b/packages/twenty-docs/docs.jsonindex 764eefc5049..0dd8479c4b6 100644--- a/packages/twenty-docs/docs.json+++ b/packages/twenty-docs/docs.json@@ -461,6 +461,7 @@"developers/extend/apps/logic/key-value-store","developers/extend/apps/logic/background-jobs","developers/extend/apps/logic/skills-and-agents",+ "developers/extend/apps/logic/workflows","developers/extend/apps/logic/connections","developers/extend/apps/logic/messaging-channels","developers/extend/apps/logic/credits"diff --git a/packages/twenty-docs/navigation/base-structure.json b/packages/twenty-docs/navigation/base-structure.jsonindex 636ffd2fdc5..7fa72156940 100644--- a/packages/twenty-docs/navigation/base-structure.json+++ b/packages/twenty-docs/navigation/base-structure.json@@ -464,6 +464,7 @@"developers/extend/apps/logic/key-value-store","developers/extend/apps/logic/background-jobs","developers/extend/apps/logic/skills-and-agents",+ "developers/extend/apps/logic/workflows","developers/extend/apps/logic/connections","developers/extend/apps/logic/messaging-channels","developers/extend/apps/logic/credits"diff --git a/packages/twenty-shared/src/constants/DocumentationPaths.ts b/packages/twenty-shared/src/constants/DocumentationPaths.tsindex aa5346df247..625ad282578 100644--- a/packages/twenty-shared/src/constants/DocumentationPaths.ts+++ b/packages/twenty-shared/src/constants/DocumentationPaths.ts@@ -76,6 +76,8 @@ export const DOCUMENTATION_PATHS = {'/developers/extend/apps/logic/overview',DEVELOPERS_EXTEND_APPS_LOGIC_SKILLS_AND_AGENTS:'/developers/extend/apps/logic/skills-and-agents',+ DEVELOPERS_EXTEND_APPS_LOGIC_WORKFLOWS:+ '/developers/extend/apps/logic/workflows',DEVELOPERS_EXTEND_APPS_OPERATIONS_CLI:'/developers/extend/apps/operations/cli',DEVELOPERS_EXTEND_APPS_OPERATIONS_OVERVIEW: