Skip to content
Merged
Show file tree
Hide file tree
Changes from 8 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
22 changes: 11 additions & 11 deletions packages/twenty-docs/developers/extend/capabilities/apps.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,11 @@ Apps are currently in alpha testing. The feature is functional but still evolvin

## What Are Apps?

Apps let you build and manage Twenty customizations **as code**. Instead of configuring everything through the UI, you define your data model and serverless functions in code — making it faster to build, maintain, and roll out to multiple workspaces.
Apps let you build and manage Twenty customizations **as code**. Instead of configuring everything through the UI, you define your data model and logic functions in code — making it faster to build, maintain, and roll out to multiple workspaces.

**What you can do today:**
- Define custom objects and fields as code (managed data model)
- Build serverless functions with custom triggers
- Build logic functions with custom triggers
- Deploy the same app across multiple workspaces

**Coming soon:**
Expand Down Expand Up @@ -159,9 +159,9 @@ At a high level:
- **README.md**: A short README in the app root with basic instructions.
- **src/**: The main place where you define your application-as-code:
- `application.config.ts`: Global configuration for your app (metadata and runtime wiring). See "Application config" below.
- `*.role.ts`: Role definitions used by your serverless functions. See "Default function role" below.
- `*.role.ts`: Role definitions used by your logic functions. See "Default function role" below.
- `*.object.ts`: Custom object definitions.
- `*.function.ts`: Serverless function definitions.
- `*.function.ts`: Logic function definitions.
- `*.front-component.tsx`: Front component definitions.

Later commands will add more files and folders:
Expand Down Expand Up @@ -214,7 +214,7 @@ The SDK provides four helper functions with built-in validation for defining you
|----------|---------|
| `defineApp()` | Configure application metadata |
| `defineObject()` | Define custom objects with fields |
| `defineFunction()` | Define serverless functions with handlers |
| `defineFunction()` | Define logic functions with handlers |
| `defineRole()` | Configure role permissions and object access |

These functions validate your configuration at runtime and provide better IDE autocompletion and type safety.
Expand Down Expand Up @@ -344,7 +344,7 @@ Notes:

#### Roles and permissions

Applications can define roles that encapsulate permissions on your workspace's objects and actions. The field `functionRoleUniversalIdentifier` in `application.config.ts` designates the default role used by your app's serverless functions.
Applications can define roles that encapsulate permissions on your workspace's objects and actions. The field `functionRoleUniversalIdentifier` in `application.config.ts` designates the default role used by your app's logic functions.

- The runtime API key injected as `TWENTY_API_KEY` is derived from this default function role.
- The typed client will be restricted to the permissions granted to that role.
Expand Down Expand Up @@ -405,7 +405,7 @@ Notes:
- `permissionFlags` control access to platform-level capabilities. Keep them minimal; add only what you need.
- See a working example in the Hello World app: [`packages/twenty-apps/hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).

### Serverless function config and entrypoint
### Logic function config and entrypoint

Each function file uses `defineFunction()` to export a configuration with a handler and optional triggers. Use the `*.function.ts` file suffix for automatic detection.

Expand Down Expand Up @@ -497,7 +497,7 @@ const handler = async (event: RoutePayload) => {
**To migrate existing functions:** Update your handler to destructure from `event.body`, `event.queryStringParameters`, or `event.pathParameters` instead of directly from the params object.
</Warning>

When a route trigger invokes your function, it receives a `RoutePayload` object that follows the AWS HTTP API v2 format. Import the type from `twenty-sdk`:
When a route trigger invokes your logic function, it receives a `RoutePayload` object that follows the AWS HTTP API v2 format. Import the type from `twenty-sdk`:

```typescript
import { defineFunction, type RoutePayload } from 'twenty-sdk';
Expand Down Expand Up @@ -527,7 +527,7 @@ The `RoutePayload` type has the following structure:

### Forwarding HTTP headers

By default, HTTP headers from incoming requests are **not** passed to your serverless function for security reasons. To access specific headers, explicitly list them in the `forwardedRequestHeaders` array:
By default, HTTP headers from incoming requests are **not** passed to your logic function for security reasons. To access specific headers, explicitly list them in the `forwardedRequestHeaders` array:

```typescript
export default defineFunction({
Expand Down Expand Up @@ -581,7 +581,7 @@ const { me } = await client.query({ me: { id: true, displayName: true } });

The client is re-generated by `yarn app:generate`. Re-run after changing your objects or when onboarding to a new workspace.

#### Runtime credentials in serverless functions
#### Runtime credentials in logic functions

When your function runs on Twenty, the platform injects credentials as environment variables before your code executes:

Expand All @@ -590,7 +590,7 @@ When your function runs on Twenty, the platform injects credentials as environme

Notes:
- You do not need to pass URL or API key to the generated client. It reads `TWENTY_API_URL` and `TWENTY_API_KEY` from process.env at runtime.
- The API key's permissions are determined by the role referenced in your `application.config.ts` via `functionRoleUniversalIdentifier`. This is the default role used by serverless functions of your application.
- The API key's permissions are determined by the role referenced in your `application.config.ts` via `functionRoleUniversalIdentifier`. This is the default role used by logic functions of your application.
- Applications can define roles to follow least‑privilege. Grant only the permissions your functions need, then point `functionRoleUniversalIdentifier` to that role's universal identifier.


Expand Down
12 changes: 6 additions & 6 deletions packages/twenty-docs/developers/self-host/capabilities/setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -289,19 +289,19 @@ yarn command:prod cron:workflow:automated-cron-trigger
**Environment-only mode:** If you set `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, add these variables to your `.env` file instead.
</Warning>

## Serverless Functions
## Logic Functions

Twenty supports serverless functions for workflows and custom logic. The execution environment is configured via the `SERVERLESS_TYPE` environment variable.
Twenty supports logic functions for workflows and custom logic. The execution environment is configured via the `SERVERLESS_TYPE` environment variable.

<Warning>
**Security Notice:** The local serverless driver (`SERVERLESS_TYPE=LOCAL`) runs code directly on the host in a Node.js process with no sandboxing. It should only be used for trusted code in development. For production deployments handling untrusted code, we highly recommend using `SERVERLESS_TYPE=LAMBDA` or `SERVERLESS_TYPE=DISABLED`.
**Security Notice:** The local driver (`SERVERLESS_TYPE=LOCAL`) runs code directly on the host in a Node.js process with no sandboxing. It should only be used for trusted code in development. For production deployments handling untrusted code, we highly recommend using `SERVERLESS_TYPE=LAMBDA` or `SERVERLESS_TYPE=DISABLED`.
</Warning>

### Available Drivers

| Driver | Environment Variable | Use Case | Security Level |
|--------|---------------------|----------|----------------|
| Disabled | `SERVERLESS_TYPE=DISABLED` | Disable serverless functions entirely | N/A |
| Disabled | `SERVERLESS_TYPE=DISABLED` | Disable logic functions entirely | N/A |
| Local | `SERVERLESS_TYPE=LOCAL` | Development and trusted environments | Low (no sandboxing) |
| Lambda | `SERVERLESS_TYPE=LAMBDA` | Production with untrusted code | High (hardware-level isolation) |

Expand All @@ -321,11 +321,11 @@ SERVERLESS_LAMBDA_ACCESS_KEY_ID=your-access-key
SERVERLESS_LAMBDA_SECRET_ACCESS_KEY=your-secret-key
```

**To disable serverless functions:**
**To disable logic functions:**
```bash
SERVERLESS_TYPE=DISABLED
```

<Note>
When using `SERVERLESS_TYPE=DISABLED`, any attempt to execute a serverless function will return an error. This is useful if you want to run Twenty without serverless function capabilities.
When using `SERVERLESS_TYPE=DISABLED`, any attempt to execute a logic function will return an error. This is useful if you want to run Twenty without logic function capabilities.
</Note>
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: Get familiar with essential terminology used in Twenty.
API (Application Programming Interface) allows you to connect Twenty with other software systems and build custom integrations.

## Apps
Apps are custom extensions built as code that can define data models and serverless functions. They enable developers to create reusable customizations that can be deployed across multiple workspaces.
Apps are custom extensions built as code that can define data models and logic functions. They enable developers to create reusable customizations that can be deployed across multiple workspaces.

## Code Actions
Code Actions are workflow steps that let you write custom JavaScript to transform data, make calculations, or perform complex logic that isn't possible with built-in actions.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ You can attach files to emails sent from workflows. The attachment is a static f
| **Event confirmations** | Event details or agenda |

<Note>
Attachments are static—the same file is sent to all recipients. For dynamic documents (like personalized quotes), generate and attach files using a [Serverless Function](/user-guide/workflows/how-tos/connect-to-other-tools/generate-pdf-from-twenty).
Attachments are static—the same file is sent to all recipients. For dynamic documents (like personalized quotes), generate and attach files using a [Logic Function](/user-guide/workflows/how-tos/connect-to-other-tools/generate-pdf-from-twenty).
</Note>

## Best Practices
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,7 @@ Runs custom JavaScript within your workflow.
- Test code directly in the step

<Note>
If you need to use external API keys in your code, you must input them directly in the function body. You cannot configure API keys elsewhere and reference them in the serverless function.
If you need to use external API keys in your code, you must input them directly in the function body. You cannot configure API keys elsewhere and reference them in the logic function.
</Note>

<Tip>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Automatically generate or fetch a PDF and attach it to a record in Twenty. This

## Overview

This workflow uses a **Manual Trigger** so users can generate a PDF on demand for any selected record. A **Serverless Function** handles:
This workflow uses a **Manual Trigger** so users can generate a PDF on demand for any selected record. A **Logic Function** handles:
1. Downloading the PDF from a URL (from a PDF generation service)
2. Uploading the file to Twenty
3. Creating an Attachment linked to the record
Expand All @@ -16,7 +16,7 @@ This workflow uses a **Manual Trigger** so users can generate a PDF on demand fo

Before setting up the workflow:

1. **Create an API Key**: Go to **Settings → APIs** and create a new API key. You'll need this token for the serverless function.
1. **Create an API Key**: Go to **Settings → APIs** and create a new API key. You'll need this token for the logic function.
2. **Set up a PDF generation service** (optional): If you want to dynamically generate PDFs (e.g., quotes), use a service like Carbone, PDFMonkey, or DocuSeal to create the PDF and get a download URL.

## Step-by-Step Setup
Expand All @@ -31,9 +31,9 @@ Before setting up the workflow:
With a Manual Trigger, users can run this workflow using a button that appears on the top right once a record is selected, to generate and attach a PDF.
</Tip>

### Step 2: Add a Serverless Function
### Step 2: Add a Logic Function

1. Add a **Serverless Function** action
1. Add a **Code** action (logic function)
2. Create a new function with the code below
3. Configure the input parameters

Expand All @@ -44,10 +44,10 @@ With a Manual Trigger, users can run this workflow using a button that appears o
| `companyId` | `{{trigger.object.id}}` |

<Note>
If attaching to a different object (Person, Opportunity, etc.), rename the parameter accordingly (e.g., `personId`, `opportunityId`) and update the serverless function.
If attaching to a different object (Person, Opportunity, etc.), rename the parameter accordingly (e.g., `personId`, `opportunityId`) and update the logic function.
</Note>

#### Serverless Function Code
#### Logic Function Code

```typescript
export const main = async (
Expand Down Expand Up @@ -170,7 +170,7 @@ Update both the function parameter and the `variables.data` object in the attach

If using a PDF generation service, you can:
1. First make an HTTP Request action to generate the PDF
2. Pass the returned PDF URL to the serverless function as a parameter
2. Pass the returned PDF URL to the logic function as a parameter

```typescript
export const main = async (
Expand Down Expand Up @@ -209,7 +209,7 @@ For creating dynamic quotes or invoices:
- **DocuSeal** - Document automation platform
- **Documint** - API-first document generation

Each service provides an API that returns a PDF URL, which you can then pass to the serverless function.
Each service provides an API that returns a PDF URL, which you can then pass to the logic function.

## Troubleshooting

Expand All @@ -222,6 +222,6 @@ Each service provides an API that returns a PDF URL, which you can then pass to
## Related

- [Workflow Triggers](/user-guide/workflows/capabilities/workflow-triggers)
- [Serverless Functions](/user-guide/workflows/capabilities/workflow-actions#serverless-function)
- [Logic Functions](/user-guide/workflows/capabilities/workflow-actions#code)
- [Generate a Quote or Invoice from Twenty](/user-guide/workflows/how-tos/connect-to-other-tools/generate-quote-or-invoice-from-twenty)

Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ description: Frequently asked questions about workflows in Twenty.
</Accordion>

<Accordion title="What's the maximum execution time for Code actions?">
Code actions (serverless functions) have a **default timeout of 5 minutes** (300 seconds).
Code actions (logic functions) have a **default timeout of 5 minutes** (300 seconds).

The maximum configurable timeout is **15 minutes** (900 seconds).

Expand Down
Loading
Loading