Logikfunktionen

Definieren Sie serverseitige TypeScript-Funktionen mit HTTP-, cron- und Datenbankereignis-Triggern.

Logikfunktionen sind serverseitige TypeScript-Funktionen, die auf der Twenty-Plattform ausgeführt werden. Sie können durch HTTP-Anfragen, cron-Zeitpläne oder Datenbankereignisse ausgelöst werden — und außerdem als Tools für KI-Agenten bereitgestellt werden.

defineLogicFunction

Logikfunktionen und deren Trigger definieren

Jede Funktionsdatei verwendet defineLogicFunction(), um eine Konfiguration mit einem Handler und optionalen Triggern zu exportieren.

src/logic-functions/createPostCard.logic-function.ts

import { defineLogicFunction } from 'twenty-sdk/define';
import type { RoutePayload } from 'twenty-sdk/logic-function';
import { CoreApiClient } from 'twenty-client-sdk/core';

const handler = async (params: RoutePayload) => {
  const client = new CoreApiClient();
  const body = (params.body ?? {}) as { name?: string };
  const name = body.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world';

  const result = await client.mutation({
    createPostCard: {
      __args: { data: { name } },
      id: true,
      name: true,
    },
  });
  return result;
};

export default defineLogicFunction({
  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
  name: 'create-new-post-card',
  timeoutSeconds: 2,
  handler,
  httpRouteTriggerSettings: {
    path: '/post-card/create',
    httpMethod: 'POST',
    isAuthRequired: true,
  },
  /*databaseEventTriggerSettings: {
    eventName: 'people.created',
  },*/
  /*cronTriggerSettings: {
    pattern: '0 0 1 1 *',
  },*/
});

Verfügbare Trigger-Typen:

• httpRoute: Stellt Ihre Funktion über einen HTTP-Pfad und eine Methode bereit. Im Anwendungscode den Routenpfad bei Verwendung von RestApiClient mit dem Präfix /s/ versehen; die bereitgestellte URL verwendet als Basis die injizierte TWENTY_FUNCTIONS_URL (oder \<server-url>/s, wenn diese nicht gesetzt ist).

Um eine routenausgelöste Logikfunktion von einer (headless) Front-Komponente aus aufzurufen, siehe Aufrufen einer Logikfunktion.

• cron: Führt Ihre Funktion nach Zeitplan mithilfe eines CRON-Ausdrucks aus.
• databaseEvent: Wird bei Lebenszyklusereignissen von Workspace-Objekten ausgeführt. Wenn die Ereignisoperation updated ist, können bestimmte zu überwachende Felder im Array updatedFields angegeben werden. Wenn das Array undefiniert oder leer ist, löst jede Aktualisierung die Funktion aus.

z. B. person.updated, *.created, company.*

• serverRoute: Stellt eine einzelne, registrierungsbezogene HTTP-Route bereit. Eine Resolver-Funktion (deklariert mit serverRouteTriggerSettings) läuft im Owner-Workspace und gibt entweder eine synchrone Response zurück oder den Ziel-Workspace UND die Ziel-Logikfunktion, die in die Queue eingereiht werden soll; auf dem Enqueue-Pfad bestätigt die Plattform mit 202 und führt dieses Ziel in der Worker-Queue aus. Siehe Server-Route-Trigger.

Sie können eine Funktion auch manuell über die CLI ausführen:

yarn twenty dev:function:exec -n create-new-post-card -p '{"key": "value"}'

yarn twenty dev:function:exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf

Sie können Protokolle mit folgendem Befehl ansehen:

yarn twenty dev:function:logs

​

Routen-Trigger-Payload

Wenn ein Route-Trigger Ihre Logikfunktion aufruft, erhält sie ein RoutePayload-Objekt, das dem AWS-HTTP-API-v2-Format folgt. Importieren Sie den Typ RoutePayload aus twenty-sdk/logic-function:

import type { RoutePayload } from 'twenty-sdk/logic-function';

const handler = async (event: RoutePayload) => {
  const { headers, queryStringParameters, pathParameters, body } = event;
  const { method, path } = event.requestContext.http;

  return { message: 'Success' };
};

Der Typ RoutePayload hat die folgende Struktur:

Eigenschaft	Typ	Beschreibung	Beispiel
headers	Record\<string, string | undefined>	HTTP-Header (nur die in forwardedRequestHeaders aufgelisteten)	siehe Abschnitt unten
queryStringParameters	Record\<string, string | undefined>	Query-String-Parameter (mehrere Werte mit Kommas verbunden)	/users?ids=1&ids=2&ids=3&name=Alice -> { ids: '1,2,3', name: 'Alice' }
pathParameters	Record\<string, string | undefined>	Aus dem Routenmuster extrahierte Pfadparameter	/users/:id, /users/123 -> { id: '123' }
body	object | null	Geparster Request-Body (JSON)	{ id: 1 } -> { id: 1 }
rawBody	string | undefined	Ursprünglicher UTF-8-Request-Body vor dem JSON-Parsing. Nützlich zur Verifizierung von Webhook-Signaturen im HMAC-Stil (z. B. GitHubs X-Hub-Signature-256, Stripe). undefined, wenn die Laufzeitumgebung es nicht beibehalten hat.
isBase64Encoded	boolean	Gibt an, ob der Body Base64-codiert ist
requestContext.http.method	Zeichenkette	HTTP-Methode (GET, POST, PUT, PATCH, DELETE)
requestContext.http.path	string	Rohpfad der Anfrage

​

forwardedRequestHeaders

Standardmäßig werden HTTP-Header von eingehenden Anfragen aus Sicherheitsgründen nicht an Ihre Logikfunktion weitergegeben. Um auf bestimmte Header zuzugreifen, listen Sie diese im Array forwardedRequestHeaders auf:

export default defineLogicFunction({
  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
  name: 'webhook-handler',
  handler,
  httpRouteTriggerSettings: {
    path: '/webhook',
    httpMethod: 'POST',
    isAuthRequired: false,
    forwardedRequestHeaders: ['x-webhook-signature', 'content-type'],
  },
});

Greifen Sie in Ihrem Handler wie folgt auf die weitergeleiteten Header zu:

const handler = async (event: RoutePayload) => {
  const signature = event.headers['x-webhook-signature'];
  const contentType = event.headers['content-type'];

  // Validate webhook signature...
  return { received: true };
};

Header-Namen werden in Kleinbuchstaben normalisiert. Greifen Sie mit Schlüsseln in Kleinbuchstaben darauf zu (z. B. event.headers['content-type']).

​

Benutzerdefinierte HTTP-Antwort

Standardmäßig sendet das Zurückgeben eines einfachen Werts aus Ihrem Handler diesen als 200-Antwort zurück (JSON für Objekte, text/plain für Zeichenketten). Um den Statuscode und die Antwort-Header zu steuern, geben Sie eine Response aus twenty-sdk/logic-function zurück:

import { Response } from 'twenty-sdk/logic-function';

const handler = async (event: RoutePayload) => {
  return new Response('<h1>Hello</h1>', {
    status: 201,
    headers: { 'content-type': 'text/html' },
  });
};

Aus Sicherheitsgründen sind Antwort-Header auf eine Allowlist beschränkt. Jeder Header, der nicht auf der Liste steht (z. B. Set-Cookie, CORS-Header wie Access-Control-Allow-Origin oder benutzerdefinierte X-*-Header), wird stillschweigend verworfen, bevor die Antwort gesendet wird. Die erlaubten Antwort-Header sind:

• content-type
• content-language
• content-disposition
• cache-control
• retry-after

Der Statuscode muss ein gültiger HTTP-Statuscode sein (zwischen 100 und 599). Antwort-Header-Namen werden ohne Beachtung der Groß-/Kleinschreibung verglichen.

​

Server-Route-Trigger

httpRouteTriggerSettings stellt eine Funktion unter /s/ bereit und ermittelt den Workspace aus dem Host der Anfrage — was funktioniert, wenn jeder Workspace seine eigene Domain hat. Drittanbieter hingegen liefern die Ereignisse jedes Mandanten an eine URL. Für diesen Fall verwende serverRouteTriggerSettings.

Der Trigger besteht aus zwei Teilen:

1. Eine Resolver-Logikfunktion – deklariert mit serverRouteTriggerSettings – läuft in deinem Owner-Workspace (dem Workspace, dem die Anwendungsregistrierung gehört). Sie inspiziert die eingehende Anfrage und gibt entweder Folgendes zurück:

   • { workspaceId, targetLogicFunctionUniversalIdentifier, payload? } — die Plattform reiht dieses Ziel im aufgelösten Workspace in die Queue ein und bestätigt mit 202 { queued: true }, oder
   • eine Response von twenty-sdk/logic-function — die Plattform gibt diese HTTP-Response synchron zurück und reiht kein Ziel in die Queue ein (verwende dies für Challenge-Handshakes wie Slack url_verification).

   Der Resolver ist die einzige Autorisierungsstelle – die URL enthält nur den Bezeichner des Resolvers. Dies ist der bevorzugte Ort, um Anfragesignaturen zu verifizieren: Der Resolver läuft vor jeglicher Nebenwirkung, hat Zugriff auf den ursprünglichen rawBody und weitergeleitete Header und kann ablehnen, ohne jemals das Ziel zu berühren.

2. Eine Target-Logikfunktion – eine reguläre, Workspace-spezifische Logikfunktion – läuft dann im aufgelösten Workspace mit dem Payload, der vom Resolver zurückgegeben wurde (oder dem ursprünglichen Anfrage-Payload, falls der Resolver ihn nicht transformiert hat). Sein Rückgabewert wird vom HTTP-Aufrufer nicht beobachtet, wenn der Resolver den Enqueue-Pfad gewählt hat.

src/logic-functions/resolve-server-route.logic-function.ts

import { createHmac, timingSafeEqual } from 'crypto';
import { defineLogicFunction } from 'twenty-sdk/define';
import { Response, type RoutePayload } from 'twenty-sdk/logic-function';

// Runs in the owner workspace. Verifies the request signature, picks
// which target function should handle the event, and returns the
// workspace + target the platform should dispatch to.
const handler = async (event: RoutePayload) => {
  // Fail closed if the secret isn't configured — never fall back to an
  // empty key, which would let any caller forge a matching signature.
  const secret = process.env.GITHUB_WEBHOOK_SECRET;

  if (!secret) {
    throw new Error('GITHUB_WEBHOOK_SECRET is not configured');
  }

  const signature = event.headers['x-hub-signature-256'] ?? '';
  const expected =
    'sha256=' +
    createHmac('sha256', secret).update(event.rawBody ?? '').digest('hex');

  const a = Buffer.from(signature);
  const b = Buffer.from(expected);

  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    throw new Error('invalid signature');
  }

  const body = (event.body ?? {}) as {
    challenge?: string;
    metadata?: { twentyWorkspaceId?: string };
    type?: string;
  };

  // Handshakes must be answered on this same response, so reply from the
  // resolver instead of returning a dispatch target.
  if (body.type === 'url_verification') {
    return new Response({ challenge: body.challenge });
  }

  const workspaceId = body.metadata?.twentyWorkspaceId;

  if (!workspaceId) {
    throw new Error('event is not linked to a workspace');
  }

  return {
    workspaceId,
    // Route different event types to different target functions.
    targetLogicFunctionUniversalIdentifier:
      body.type === 'invoice.paid'
        ? 'c4e2a9b1-7d4e-4c9a-9f2b-2e1d6a4c8e10' // handle-invoice-paid
        : 'd5f3b0c2-8e5f-5d0b-a0c3-3f2e7b5d9f21', // handle-other-event
  };
};

export default defineLogicFunction({
  universalIdentifier: 'b3c2f0a1-7d4e-4c9a-9f2b-2e1d6a4c8e10',
  name: 'resolve-server-route',
  handler,
  serverRouteTriggerSettings: {
    forwardedRequestHeaders: ['x-hub-signature-256'],
  },
});

src/logic-functions/handle-invoice-paid.logic-function.ts

import { defineLogicFunction } from 'twenty-sdk/define';
import type { RoutePayload } from 'twenty-sdk/logic-function';

// Runs in the resolved workspace. The resolver has already authenticated
// the request, so this handler can focus on the actual work.
const handler = async (event: RoutePayload) => {
  // ...handle the verified event
  return { received: true };
};

export default defineLogicFunction({
  universalIdentifier: 'c4e2a9b1-7d4e-4c9a-9f2b-2e1d6a4c8e10',
  name: 'handle-invoice-paid',
  handler,
});

Der Endpoint ist erreichbar unter:

POST https://your-twenty-server.com/webhooks/server/:resolverLogicFunctionUniversalIdentifier

Der Bezeichner ist der universalIdentifier des Resolvers aus deinem Manifest. Registriere diese URL beim Provider.

Die Anwendung muss beansprucht und im Arbeitsbereich ihres Besitzers installiert werden. Da der Resolver im Owner-Arbeitsbereich ausgeführt wird (dem Arbeitsbereich, der die Anwendungsregistrierung besitzt), funktioniert ein Server-Route-Trigger nur, wenn die Anwendung beansprucht wurde – d. h. sie einen Owner-Arbeitsbereich hat – und diese Anwendung im Owner-Arbeitsbereich installiert ist. Solange beides nicht zutrifft, hat der Resolver keinen Ausführungsort, sodass die Route nicht ausgeführt werden kann. Eine Anwendung, die eine serverRouteTriggerSettings-Logikfunktion bereitstellt, kann daher nicht im Marketplace aufgeführt werden, bevor sie beansprucht und im Owner-Arbeitsbereich installiert wurde.

Resolver-Vertrag. Der LogicFunctionConfig-Typ des SDK erzwingt dies zur Compile-Zeit: Sobald du serverRouteTriggerSettings setzt, ist dein Handler darauf beschränkt, entweder eine Response oder { workspaceId: string; targetLogicFunctionUniversalIdentifier: string; payload?: object } zurückzugeben (oder ein Promise von einem der beiden). Auf dem Dispatch-Pfad muss die workspaceId auf einen Workspace verweisen, in dem die Zielfunktion installiert ist, andernfalls wird die Anfrage mit 404 abgelehnt. Ein Ergebnis, das keiner der beiden Formen entspricht – einschließlich eines Ergebnisses, dessen Bezeichner keine UUIDs sind – wird mit 502 abgelehnt.

Feld	Typ	Notizen
workspaceId	string	UUID des Workspaces, in dem das Ziel ausgeführt wird.
targetLogicFunctionUniversalIdentifier	string	universalIdentifier der Logikfunktion, die in diesem Workspace aufgerufen werden soll.
payload	object (optional)	Falls gesetzt, ersetzt er den Request-Body, der an das Target gesendet wird.

Die Signaturverifizierung liegt in deiner Verantwortung – verifiziere im Resolver. Die Plattform verifiziert Anfragesignaturen nicht. Der Resolver ist der empfohlene Ort dafür: Er läuft zuerst, mit Zugriff auf event.rawBody und die Header, die du in forwardedRequestHeaders aufgeführt hast, und ein geworfener Fehler (oder eine nicht passende workspaceId) stoppt das Dispatching, bevor das Target aufgerufen wird. Wenn du die Verifizierung stattdessen in das Target verschiebst, muss das Target darauf achten, rawBody und Header nicht zu verlieren – d. h. der Resolver darf keinen payload zurückgeben. Überprüfe immer vor jeglicher Nebenwirkung und verwende einen Vergleich in konstanter Zeit.

Für Anfragesignaturen signieren die meisten Provider mit HMAC-SHA256; die Teile, die sich unterscheiden, sind der Header-Name, die Digest-Codierung und der signierte Payload-String. Einige Beispiele:

Anbieter	Weiterzuleitende Header	Signierte Zeichenkette	Digest
Svix (Recall, Resend, Clerk)	webhook-id, webhook-timestamp, webhook-signature	{id}.{timestamp}.{rawBody}	base64 (Geheimnis ist base64 nach Entfernen von whsec_)
Stripe	stripe-signature	{timestamp}.{rawBody}	hex
GitHub	x-hub-signature-256	{rawBody}	hex (mit Präfix sha256=)
Shopify	x-shopify-hmac-sha256	{rawBody}	base64
Slack	x-slack-signature, x-slack-request-timestamp	v0:{timestamp}:{rawBody}	hex (mit Präfix v0=)

Das obige Resolver-Beispiel zeigt bereits den GitHub-HMAC-SHA256-Flow – passe den Header-Namen, die Digest-Codierung und den signierten Payload-String entsprechend dem Provider an, den du integrierst.

Wenn der Resolver ein Dispatch-Objekt zurückgibt, antwortet die Route mit 202 { queued: true } und das Ziel wird in der Worker-Queue ausgeführt – der Aufrufer bekommt weder die Latenz, noch das Ergebnis oder Fehler des Ziels mit (diese werden in den Ausführungsprotokollen aufgezeichnet). Dadurch wird verhindert, dass erneute Zustellungen des Senders Verarbeitungsverzögerungen verstärken – genau das ist bei der Erfassung von Webhooks erwünscht.

Wenn der Aufrufer den Response-Body in derselben Anfrage lesen muss (Challenge-Handshakes, interaktive Bestätigungen), gib stattdessen eine Response aus dem Resolver zurück. Die Plattform gibt sie synchron zurück und überspringt die Queue; ihre Header durchlaufen dieselbe Allow-Liste wie HTTP-Routen-Antworten. Halten Sie den Resolver schnell – einige Provider (z. B. Slack) laufen nach wenigen Sekunden in ein Timeout. Da der Resolver als öffentlicher Endpoint erreichbar ist, schütze ihn mit Rate-Limiting an deinem Edge.

​

Datenbank-Event-Trigger-Payload

Wenn ein Datenbank-Event-Trigger Ihre Logic Function aufruft, erhält sie eine DatabaseEventPayload pro geändertem Datensatz. Die Payload kombiniert Metadaten über den Quell-Workspace und das Objekt mit dem Ereignis auf Datensatzebene.

import type {
  DatabaseEventPayload,
  ObjectRecordCreateEvent,
  ObjectRecordDestroyEvent,
  ObjectRecordUpdateEvent,
} from 'twenty-sdk/logic-function';

type Person = {
  id: string;
  emails?: { primaryEmail?: string };
};

Die Nutzlast umfasst:

Eigenschaft	Beschreibung
name	Ereignisname, z. B. person.updated.
workspaceId	Arbeitsbereich, in dem das Ereignis stattgefunden hat.
objectMetadata	Metadaten für das Objekt, das geändert wurde.
recordId	ID des geänderten Datensatzes.
userId, userWorkspaceId, workspaceMemberId	Akteurfelder, wenn das Ereignis von einem Benutzer des Arbeitsbereichs ausgelöst wurde.
properties	Datensatzdaten für das Ereignis mit before, after, diff und updatedFields, abhängig von der Operation.

Ereignis	Datensatzdaten
person.created	event.properties.after
person.updated	event.properties.before, event.properties.after, event.properties.diff, event.properties.updatedFields
person.destroyed	event.properties.before

Bei Soft Deletes folgt .deleted der Aktualisierungsstruktur, da sich das Feld deletedAt des Datensatzes ändert. Für dauerhafte Löschvorgänge verwende .destroyed.

databaseEventTriggerSettings.updatedFields filtert, welche Aktualisierungsereignisse die Funktion auslösen. event.properties.updatedFields gibt an, welche Felder beim aktuellen Ereignis tatsächlich geändert wurden.

Beispiel für ein Created-Ereignis:

type PersonCreatedEvent = DatabaseEventPayload<
  ObjectRecordCreateEvent<Person>
>;

const handler = async (event: PersonCreatedEvent) => {
  const person = event.properties.after;

  return {
    personId: event.recordId,
    email: person.emails?.primaryEmail,
  };
};

Beispiel für ein Updated-Ereignis:

type PersonUpdatedEvent = DatabaseEventPayload<
  ObjectRecordUpdateEvent<Person>
>;

const handler = async (event: PersonUpdatedEvent) => {
  const { before, after, diff, updatedFields } = event.properties;

  return {
    personId: event.recordId,
    updatedFields,
    previousEmail: before.emails?.primaryEmail,
    currentEmail: after.emails?.primaryEmail,
    emailDiff: diff.emails,
  };
};

Nur bei E-Mail-Aktualisierungen auslösen:

export default defineLogicFunction({
  ...,
  databaseEventTriggerSettings: {
    eventName: 'person.updated',
    updatedFields: ['emails'],
  },
});

Beispiel für ein Destroyed-Ereignis:

type PersonDestroyedEvent = DatabaseEventPayload<
  ObjectRecordDestroyEvent<Person>
>;

const handler = async (event: PersonDestroyedEvent) => {
  const personBeforeDestroy = event.properties.before;

  return {
    personId: event.recordId,
    email: personBeforeDestroy.emails?.primaryEmail,
  };
};

​

Eine Funktion als KI-Tool oder Workflow-Aktion verfügbar machen

Logikfunktionen können auf zwei Oberflächen verfügbar gemacht werden, jeweils mit eigenem Trigger:

• toolTriggerSettings — macht die Funktion über die KI-Funktionen von Twenty (Chat, MCP, Funktionsaufrufe) auffindbar. Verwendet das standardmäßige JSON Schema, das Format, das LLMs nativ verstehen.
• workflowActionTriggerSettings — lässt die Funktion als Schritt im visuellen Workflow-Builder erscheinen. Verwendet das umfangreiche InputSchema von Twenty, sodass der Builder geeignete Feldeditoren, Variablenauswahlen und Beschriftungen rendern kann.

Eine Funktion kann sich für eine, die andere oder beide entscheiden. Sie stehen neben cronTriggerSettings, databaseEventTriggerSettings und httpRouteTriggerSettings — gleiches Muster, gleiche Struktur.

Beziehung zur Code-Aktion im Workflow. Die integrierte Code-Aktion im Workflow-Builder ist selbst eine Logikfunktion – Twenty erstellt für jeden Code-Schritt eine Logikfunktion und stellt deren Editor inline bereit. workflowActionTriggerSettings ist die Art und Weise, wie Sie diesen einmaligen Inline-Code in eine wiederverwendbare Aktion verwandeln: Definieren Sie die Funktion einmal in Ihrer App, und sie wird in jedem Workflow auswählbar, anstatt in jeden Code-Schritt kopiert zu werden. Siehe die Code-Aktion im Benutzerhandbuch für die Endbenutzeransicht.

src/logic-functions/enrich-company.logic-function.ts

import { defineLogicFunction } from 'twenty-sdk/define';
import { CoreApiClient } from 'twenty-client-sdk/core';

const handler = async (params: { companyName: string; domain?: string }) => {
  const client = new CoreApiClient();

  const result = await client.mutation({
    createTask: {
      __args: {
        data: {
          title: `Enrich data for ${params.companyName}`,
          body: `Domain: ${params.domain ?? 'unknown'}`,
        },
      },
      id: true,
    },
  });

  return { taskId: result.createTask.id };
};

export default defineLogicFunction({
  universalIdentifier: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
  name: 'enrich-company',
  description: 'Enrich a company record with external data',
  timeoutSeconds: 10,
  handler,
  toolTriggerSettings: {},
});

Hauptpunkte:

• Eine Funktion kann Oberflächen mischen — deklarieren Sie sowohl toolTriggerSettings als auch workflowActionTriggerSettings, um sie im Chat UND im Workflow-Builder bereitzustellen.
• toolTriggerSettings.inputSchema und workflowActionTriggerSettings.inputSchema sind beide optional. Wenn sie weggelassen werden, leitet der Manifest-Builder sie aus dem Handler-Quellcode ab (JSON Schema für das KI-Tool, das InputSchema von Twenty für die Workflow-Aktion). Geben Sie eines explizit an, wenn Sie eine reichere Typisierung wünschen — zum Beispiel mit FieldMetadataType-fähigen Feldern wie CURRENCY oder RELATION für den Workflow-Builder oder mit description-Feldern, die der KI-Agent lesen kann:

export default defineLogicFunction({
  ...,
  toolTriggerSettings: {
    inputSchema: {
      type: 'object',
      properties: {
        companyName: {
          type: 'string',
          description: 'The name of the company to enrich',
        },
        domain: {
          type: 'string',
          description: 'The company website domain (optional)',
        },
      },
      required: ['companyName'],
    },
  },
});

Um Ihre Parameter einmal zu deklarieren und beide Oberflächen zu bedienen, definieren Sie ein einziges JSON Schema (InputJsonSchema) und konvertieren Sie es für die Workflow-Aktion mit jsonSchemaToInputSchema aus twenty-sdk/logic-function. toolTriggerSettings.inputSchema nimmt das JSON Schema direkt, während workflowActionTriggerSettings.inputSchema das InputSchema von Twenty erwartet:

import { defineLogicFunction } from 'twenty-sdk/define';
import { jsonSchemaToInputSchema, type InputJsonSchema } from 'twenty-sdk/logic-function';

const inputSchema: InputJsonSchema = {
  type: 'object',
  properties: {
    companyName: { type: 'string', label: 'Company name' },
    domain: { type: 'string', label: 'Domain' },
  },
  required: ['companyName'],
};

export default defineLogicFunction({
  ...,
  toolTriggerSettings: { inputSchema },
  workflowActionTriggerSettings: {
    label: 'Enrich Company',
    icon: 'IconBuilding',
    inputSchema: jsonSchemaToInputSchema(inputSchema),
  },
});

Ein vollständiges Beispiel für eine Workflow-Aktion

workflowActionTriggerSettings akzeptiert vier Felder:

Feld	Zweck
label	Name, der für die Aktion in der Schritt-Auswahl des Workflow-Builders angezeigt wird. Standardmäßig der Funktions-name.
icon	Symbol, das neben der Aktion angezeigt wird (ein tabler-icons-Name, z. B. IconBuilding).
inputSchema	Twentys umfangreiches InputSchema – das, was der Builder als konfigurierbare Felder (mit Variablen-Auswählern) rendert. Optional; wird aus dem Handler abgeleitet, wenn es weggelassen wird.
outputSchema	Deklariert die Struktur, die der Handler zurückgibt, sodass nachfolgende Schritte auf seine Ausgabefelder abbilden können. Optional; ohne dieses Schema wird die Ausgabe als einzelner undurchsichtiger Wert bereitgestellt.

Alles zusammen – eine Funktion, die als Workflow-Aktion bereitgestellt wird, mit einer deklarierten Ausgabe, damit spätere Schritte auf taskId verweisen können:

src/logic-functions/enrich-company.logic-function.ts

import { defineLogicFunction } from 'twenty-sdk/define';
import { jsonSchemaToInputSchema, type InputJsonSchema } from 'twenty-sdk/logic-function';
import { CoreApiClient } from 'twenty-client-sdk/core';

const inputSchema: InputJsonSchema = {
  type: 'object',
  properties: {
    companyName: { type: 'string', label: 'Company name' },
    domain: { type: 'string', label: 'Domain' },
  },
  required: ['companyName'],
};

const handler = async (params: { companyName: string; domain?: string }) => {
  const client = new CoreApiClient();

  const result = await client.mutation({
    createTask: {
      __args: {
        data: {
          title: `Enrich data for ${params.companyName}`,
          body: `Domain: ${params.domain ?? 'unknown'}`,
        },
      },
      id: true,
    },
  });

  // The keys returned here should match the `outputSchema` properties below.
  return { taskId: result.createTask.id, enriched: true };
};

export default defineLogicFunction({
  universalIdentifier: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
  name: 'enrich-company',
  description: 'Enrich a company record with external data',
  timeoutSeconds: 10,
  handler,
  workflowActionTriggerSettings: {
    label: 'Enrich Company',
    icon: 'IconBuilding',
    inputSchema: jsonSchemaToInputSchema(inputSchema),
    outputSchema: [
      {
        type: 'object',
        properties: {
          taskId: { type: 'string' },
          enriched: { type: 'boolean' },
        },
      },
    ],
  },
});

Sobald die App installiert ist, erscheint Enrich Company im Aktionswähler des Workflow-Builders. Der Builder rendert companyName und domain als Eingabefelder (die jeweils Werte aus vorherigen Schritten beziehen können), und nachgelagerte Schritte können auf die taskId- und enriched-Ausgaben des Schritts verweisen.

Schreiben Sie eine gute description. KI-Agenten verlassen sich auf das description-Feld der Funktion, um zu entscheiden, wann das Tool verwendet werden soll. Seien Sie konkret darin, was das Tool tut und wann es aufgerufen werden soll.

Runtime-Hilfsfunktionen. twenty-sdk/utils exportiert kleine Runtime-Hilfsfunktionen erneut, sodass Handler niemals direkt aus twenty-shared importieren. Zum Beispiel gibt isDefined(value) sowohl für null als auch für undefined den Wert false zurück – verwenden Sie es, um optionale Handler-Eingaben sicher einzugrenzen, die zur Laufzeit als null ankommen können, selbst wenn sie als T | undefined typisiert sind:

import { isDefined } from 'twenty-sdk/utils';

const handler = async (params: { parentMessageId?: string }) => {
  if (isDefined(params.parentMessageId)) {
    // params.parentMessageId is narrowed to string here
  }
};

Installations-Hooks – Vorinstallations-, Nachinstallations- und Deinstallations-Handler – teilen sich diese Laufzeit, werden aber mit ihren eigenen define-Funktionen deklariert und verwenden keine Trigger-Einstellungen. Siehe Installations-Hooks für definePreInstallLogicFunction, definePostInstallLogicFunction und defineUninstallLogicFunction.

​

Typisierte API-Clients (twenty-client-sdk)

Das Paket twenty-client-sdk stellt zwei typisierte GraphQL-Clients bereit, um aus Ihren Logikfunktionen und Frontend-Komponenten mit der Twenty-API zu interagieren.

Client	Importieren	Endpunkt	Generiert?
CoreApiClient	twenty-client-sdk/core	/graphql — Arbeitsbereichsdaten (Datensätze, Objekte)	Ja, zur Entwicklungs-/Build-Zeit
MetadataApiClient	twenty-client-sdk/metadata	/metadata — Arbeitsbereichskonfiguration, Datei-Uploads	Nein, wird vorgefertigt ausgeliefert

CoreApiClient

Arbeitsbereichsdaten (Datensätze, Objekte) abfragen und ändern

Der CoreApiClient ist der Haupt-Client zum Abfragen und Ändern von Arbeitsbereichsdaten. Er wird während yarn twenty dev oder yarn twenty dev:build aus Ihrem Arbeitsbereichsschema generiert und ist daher vollständig typisiert, passend zu Ihren Objekten und Feldern.

import { CoreApiClient } from 'twenty-client-sdk/core';

const client = new CoreApiClient();

// Query records
const { companies } = await client.query({
  companies: {
    edges: {
      node: {
        id: true,
        name: true,
        domainName: {
          primaryLinkLabel: true,
          primaryLinkUrl: true,
        },
      },
    },
  },
});

// Create a record
const { createCompany } = await client.mutation({
  createCompany: {
    __args: {
      data: {
        name: 'Acme Corp',
      },
    },
    id: true,
    name: true,
  },
});

Der Client verwendet eine Selection-Set-Syntax: Übergeben Sie true, um ein Feld einzuschließen, verwenden Sie __args für Argumente, und verschachteln Sie Objekte für Relationen. Sie erhalten vollständige Autovervollständigung und Typprüfung basierend auf Ihrem Arbeitsbereichsschema.

Der CoreApiClient wird zur Entwicklungs-/Build-Zeit generiert. Wenn Sie ihn verwenden, ohne zuvor yarn twenty dev oder yarn twenty dev:build ausgeführt zu haben, wird ein Fehler ausgelöst. Die Generierung erfolgt automatisch — die CLI inspiziert das GraphQL-Schema Ihres Arbeitsbereichs und erzeugt mit @genql/cli einen typisierten Client.

​

Verwendung von CoreSchema für Typannotationen

CoreSchema stellt TypeScript-Typen bereit, die Ihren Arbeitsbereichsobjekten entsprechen — nützlich zum Typisieren von Komponentenzustand oder Funktionsparametern:

import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
import { useState } from 'react';

const [company, setCompany] = useState<
  Pick<CoreSchema.Company, 'id' | 'name'> | undefined
>(undefined);

const client = new CoreApiClient();
const result = await client.query({
  company: {
    __args: { filter: { position: { eq: 1 } } },
    id: true,
    name: true,
  },
});
setCompany(result.company);

MetadataApiClient

Konfiguration des Arbeitsbereichs, Anwendungen und Dateiuploads

MetadataApiClient ist im SDK bereits vorgefertigt enthalten (keine Generierung erforderlich). Er fragt den Endpunkt /metadata nach Arbeitsbereichskonfiguration, Anwendungen und Datei-Uploads ab.

import { MetadataApiClient } from 'twenty-client-sdk/metadata';

const metadataClient = new MetadataApiClient();

// List first 10 objects in the workspace
const { objects } = await metadataClient.query({
  objects: {
    edges: {
      node: {
        id: true,
        nameSingular: true,
        namePlural: true,
        labelSingular: true,
        isCustom: true,
      },
    },
    __args: {
      filter: {},
      paging: { first: 10 },
    },
  },
});

​

Dateien hochladen

Der MetadataApiClient enthält eine Methode uploadFile, um Dateien an Felder des Typs Datei anzuhängen:

import { MetadataApiClient } from 'twenty-client-sdk/metadata';
import * as fs from 'fs';

const metadataClient = new MetadataApiClient();

const fileBuffer = fs.readFileSync('./invoice.pdf');

const uploadedFile = await metadataClient.uploadFile(
  fileBuffer,                                         // file contents as a Buffer
  'invoice.pdf',                                      // filename
  'application/pdf',                                  // MIME type
  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
);

console.log(uploadedFile);
// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }

Parameter	Typ	Beschreibung
fileBuffer	Buffer	Der Rohinhalt der Datei
filename	string	Der Name der Datei (wird für Speicherung und Anzeige verwendet)
contentType	Zeichenkette	MIME-Typ (standardmäßig application/octet-stream, wenn weggelassen)
fieldMetadataUniversalIdentifier	string	Der universalIdentifier des Dateityp-Felds in Ihrem Objekt

Hauptpunkte:

• Sie verwendet den universalIdentifier des Feldes (nicht dessen arbeitsbereichsspezifische ID), sodass Ihr Upload-Code in jedem Arbeitsbereich funktioniert, in dem Ihre App installiert ist.
• Die zurückgegebene url ist eine signierte URL, mit der Sie auf die hochgeladene Datei zugreifen können.

Wenn Ihr Code auf Twenty ausgeführt wird (Logikfunktionen oder Frontend-Komponenten), injiziert die Plattform Anmeldedaten als Umgebungsvariablen:

• TWENTY_API_URL — Basis-URL der Twenty-API
• TWENTY_APP_ACCESS_TOKEN — Kurzlebiger Schlüssel, der auf die Standard-Funktionsrolle Ihrer Anwendung begrenzt ist

Sie müssen diese nicht an die Clients übergeben — sie lesen automatisch aus process.env. Die Berechtigungen des API-Schlüssels werden durch die Rolle bestimmt, die mit defineApplicationRole() deklariert wird (oder über defaultRoleUniversalIdentifier in application-config.ts referenziert wird).