Přejít na hlavní obsah
Logické funkce jsou serverové funkce v TypeScriptu, které běží na platformě Twenty. Mohou být spouštěny požadavky HTTP, plány cronu nebo databázovými událostmi — a lze je také zpřístupnit jako nástroje pro agenty AI.
Každý soubor funkce používá defineLogicFunction() k exportu konfigurace s obslužnou funkcí (handlerem) a volitelnými spouštěči.
src/logic-functions/createPostCard.logic-function.ts
Dostupné typy spouštěčů:
  • httpRoute: Zpřístupní vaši funkci na HTTP cestě a metodě. V kódu aplikace přidejte prefix /s/ k cestě routy při použití RestApiClient; nasazená URL používá injektovanou základní adresu TWENTY_FUNCTIONS_URL (nebo \<server-url>/s, pokud není nastavena).
Chcete-li vyvolat logickou funkci spuštěnou trasou z (bezhlavé) front-endové komponenty, podívejte se na Volání logické funkce.
  • cron: Spouští vaši funkci podle plánu pomocí výrazu CRON.
  • databaseEvent: Spouští se při událostech životního cyklu objektů v pracovním prostoru. Když je operace události updated, lze konkrétní sledovaná pole určit v poli updatedFields. Pokud zůstane nedefinované nebo prázdné, spustí funkci jakákoli aktualizace.
např. person.updated, *.created, company.*
  • serverRoute: Zpřístupňuje jednu registrací omezenou trasu HTTP. Funkce resolver (deklarovaná pomocí serverRouteTriggerSettings) běží ve vlastnickém workspace a vrací cílový workspace i cílovou logickou funkci, na kterou se má směrovat; platforma poté spustí tuto cílovou funkci a vrátí její odpověď. Viz spouštěč serverové trasy.
Funkci můžete také spustit ručně pomocí CLI:
Logy můžete sledovat pomocí:

Payload spouštěče trasy

Když spouštěč typu route vyvolá vaši logickou funkci, ta obdrží objekt RoutePayload, který odpovídá AWS HTTP API v2 formátu. Importujte typ RoutePayload z twenty-sdk/logic-function:
Typ RoutePayload má následující strukturu:

forwardedRequestHeaders

Ve výchozím nastavení se záhlaví HTTP z příchozích požadavků z bezpečnostních důvodů do vaší logické funkce ne předávají. Chcete-li zpřístupnit konkrétní záhlaví, výslovně je uveďte v poli forwardedRequestHeaders:
Ve vašem handleru k přeposlaným záhlavím přistupujte takto:
Názvy záhlaví jsou normalizovány na malá písmena. Přistupujte k nim pomocí klíčů s malými písmeny (například event.headers['content-type']).

Vlastní odpověď HTTP

Ve výchozím nastavení vrácení prosté hodnoty z vašeho handleru odešle tuto hodnotu zpět jako odpověď 200 (JSON pro objekty, text/plain pro řetězce). Pro kontrolu stavového kódu a hlaviček odpovědi vraťte Response z twenty-sdk/logic-function:
Z bezpečnostních důvodů jsou hlavičky odpovědi omezeny na seznam povolených položek. Jakákoli hlavička, která není na seznamu (např. Set-Cookie, CORS hlavičky jako Access-Control-Allow-Origin nebo vlastní hlavičky X-*), je tiše zahozena před odesláním odpovědi. Povolené hlavičky odpovědi jsou:
  • content-type
  • content-language
  • content-disposition
  • cache-control
  • retry-after
Stavový kód musí být platný stavový kód HTTP (mezi 100 a 599). Názvy hlaviček odpovědi se porovnávají bez rozlišení velikosti písmen.

Spouštěč serverové trasy

httpRouteTriggerSettings zpřístupňuje funkci pod /s/ a workspace určuje z hostitele požadavku — což funguje, když má každý workspace svou vlastní doménu. Poskytovatelé třetích stran však doručují události každého tenanta na jednu adresu URL. Pro tento případ použijte serverRouteTriggerSettings.Spouštěč má dvě části:
  1. Logická funkce resolveru — deklarovaná pomocí serverRouteTriggerSettings — běží ve vašem vlastnickém workspace (workspace, který je vlastníkem registrace aplikace). Prohlédne si příchozí request a vrátí { workspaceId, targetLogicFunctionUniversalIdentifier, payload? }, čímž zvolí obě — cílový workspace i cílovou funkci. Resolver je jediným místem autorizace — URL nese pouze identifikátor resolveru. Toto je preferované místo pro ověřování podpisů requestů: resolver běží před jakýmikoli vedlejšími efekty, má přístup k původnímu rawBody a předaným hlavičkám a může request odmítnout, aniž by se vůbec dotkl cíle.
  2. Cílová (target) logická funkce — běžná per-workspace logická funkce — pak běží v určeném workspace s payloadem vráceným resolverem (nebo s původním payloadem requestu, pokud jej resolver neupravil). Její návratová hodnota se stává HTTP odpovědí.
src/logic-functions/resolve-server-route.logic-function.ts
src/logic-functions/handle-invoice-paid.logic-function.ts
Endpoint je dostupný na:
Identifikátor je universalIdentifier resolveru z vašeho manifestu. Zaregistrujte tuto adresu URL u poskytovatele.
Aplikace musí být převzata do vlastnictví a nainstalována v pracovním prostoru vlastníka. Protože resolver běží v pracovním prostoru vlastníka (pracovní prostor, který vlastní registraci aplikace), spouštěč serverové trasy funguje pouze tehdy, když byla aplikace převzata do vlastnictví — tj. má pracovní prostor vlastníka — a tato aplikace je nainstalována v pracovním prostoru vlastníka. Dokud nejsou obě podmínky splněny, resolver nemá kde běžet, takže trasu nelze zpracovat. Aplikace, která zpřístupňuje logickou funkci serverRouteTriggerSettings, proto nemůže být uvedena na Marketplace, dokud není převzata do vlastnictví a nainstalována v pracovním prostoru vlastníka.
Smlouva resolveru. Typ LogicFunctionConfig v SDK toto vynucuje v době kompilace: jakmile nastavíte serverRouteTriggerSettings, váš handler je omezen tak, aby vracel { workspaceId: string; targetLogicFunctionUniversalIdentifier: string; payload?: object } (nebo Promise této hodnoty). workspaceId musí být workspace, ve kterém je cílová funkce nainstalována, jinak je request odmítnut s chybou 404.
Ověření podpisu je vaší odpovědností — proveďte ho v resolveru. Platforma nepřezkušuje (neověřuje) podpisy requestů. Resolver je k tomu doporučené místo: běží jako první, má přístup k event.rawBody a hlavičkám, které jste uvedli v forwardedRequestHeaders, a vyhozená chyba (nebo jakékoli neodpovídající workspaceId) zastaví předání dříve, než je cíl zavolán. Pokud místo toho posunete ověřování až do cíle, cíl musí dávat pozor, aby neztratil rawBody a hlavičky — tj. resolver nesmí vracet payload. Vždy ověřujte před jakýmikoliv vedlejšími efekty a použijte porovnání v konstantním čase.
U podpisů requestů většina poskytovatelů podepisuje pomocí HMAC-SHA256; části, které se liší, jsou název hlavičky, kódování digestu a podepsaný řetězec payloadu. Několik příkladů:Příklad resolveru výše už ukazuje GitHub HMAC-SHA256 flow — přizpůsobte název hlavičky, kódování digestu a podepsaný řetězec payloadu podle poskytovatele, se kterým se integrujete.
Cíl běží synchronně a jeho návratová hodnota se stává HTTP odpovědí, takže volající vidí váš stavový kód a mohou opakovat požadavek při jiném než 2xx kódu. Udržujte oba handlery rychlé — některým poskytovatelům (např. Slack) vyprší časový limit během několika sekund. Protože je resolver dostupný jako veřejný endpoint, chraňte ho omezením rychlosti (rate limiting) na své edge vrstvě.

Payload spouštěče databázové události

Když spouštěč databázové události vyvolá vaši logickou funkci, obdrží jeden DatabaseEventPayload pro každý změněný záznam. Payload kombinuje metadata o zdrojovém pracovním prostoru a objektu s událostí na úrovni záznamu.
Tělo zprávy obsahuje:U logických smazání má .deleted podobu jako u aktualizace, protože se změní pole deletedAt záznamu. Pro trvalá smazání použijte .destroyed.
databaseEventTriggerSettings.updatedFields filtruje, které události aktualizace spustí funkci. event.properties.updatedFields říká, která pole se v aktuální události skutečně změnila.
Příklad události vytvoření:
Příklad události aktualizace:
Spouštění pouze při aktualizacích e‑mailu:
Příklad události smazání:

Zpřístupnění funkce jako nástroje AI nebo akce pracovního postupu

Logické funkce lze zpřístupnit na dvou rozhraních, z nichž každé má vlastní spouštěč:
  • toolTriggerSettings — zpřístupní funkci AI funkcím Twenty (chat, MCP, volání funkcí). Používá standardní JSON Schema, formát, kterému modely LLM nativně rozumějí.
  • workflowActionTriggerSettings — zobrazí funkci jako krok ve vizuálním builderu workflow. Používá bohaté InputSchema od Twenty, aby builder mohl vykreslit správné editory polí, voliče proměnných a štítky.
Funkce se může rozhodnout pro jedno, druhé nebo obě. Stojí po boku cronTriggerSettings, databaseEventTriggerSettings a httpRouteTriggerSettings — stejný vzor, stejná struktura.
Vztah k akci Code ve workflow. Vestavěná akce Code v tvůrci workflow je sama o sobě logická funkce — Twenty pro každý krok Code vytvoří jednu a její editor zpřístupní inline. workflowActionTriggerSettings je způsob, jak z jednorázového inline kódu udělat znovupoužitelnou akci: funkci v aplikaci nadefinujete jednou a potom je možné ji vybrat v libovolném workflow, místo aby se kopírovala do každého kroku Code. Pro pohled koncového uživatele se podívejte na akci Code v uživatelské příručce.
src/logic-functions/enrich-company.logic-function.ts
Hlavní body:
  • Funkce může míchat rozhraní — deklarujte jak toolTriggerSettings, tak workflowActionTriggerSettings, abyste ji zpřístupnili v chatu i ve workflow builderu.
  • toolTriggerSettings.inputSchema a workflowActionTriggerSettings.inputSchema jsou obě volitelné. Pokud jsou vynechány, sestavovač manifestu je odvodí ze zdrojového kódu handleru (JSON Schema pro nástroj AI, InputSchema od Twenty pro akci workflow). Uveďte jej explicitně, když chcete bohatší typování — například u polí s podporou FieldMetadataType, jako CURRENCY nebo RELATION pro workflow builder, nebo s poli description, která si AI agent může přečíst:
Abyste deklarovali své parametry jen jednou a obsloužili obě rozhraní, definujte jedno JSON Schema (InputJsonSchema) a převeďte jej pro akci pracovního postupu pomocí jsonSchemaToInputSchema z twenty-sdk/logic-function. toolTriggerSettings.inputSchema přebírá JSON Schema přímo, zatímco workflowActionTriggerSettings.inputSchema očekává InputSchema od Twenty:
Kompletní příklad akce workflow
workflowActionTriggerSettings přijímá čtyři pole:Dohromady — funkce zpřístupněná jako akce workflow s deklarovaným výstupem, aby se na taskId mohly odkazovat pozdější kroky:
src/logic-functions/enrich-company.logic-function.ts
Jakmile je aplikace nainstalovaná, Enrich Company se zobrazí ve výběru akcí tvůrce workflow. Tvůrce zobrazí companyName a domain jako vstupní pole (každé z nich může získávat hodnoty z předchozích kroků) a následující kroky se mohou odkazovat na výstupy kroku taskId a enriched.
Napište kvalitní description. Agenti AI se spoléhají na pole funkce description při rozhodování, kdy nástroj použít. Buďte konkrétní ohledně toho, co nástroj dělá a kdy se má volat.
Pomocné nástroje za běhu. twenty-sdk/utils znovu exportuje malé pomocné nástroje pro běh, takže handlery nikdy neimportují přímo z twenty-shared. Například isDefined(value) vrací false jak pro null, tak pro undefined — použijte jej k bezpečnému zúžení volitelných vstupů handleru, které mohou za běhu dorazit jako null, i když jsou typované jako T | undefined:
Instalační hooky — předinstalační a poinstalační handlery — sdílejí toto běhové prostředí, ale deklarují se vlastními funkcemi define a nepřebírají nastavení spouštěče (triggeru). Viz Instalační hooky pro definePreInstallLogicFunction a definePostInstallLogicFunction.

Typovaní klienti API (twenty-client-sdk)

Balíček twenty-client-sdk poskytuje dva typované klienty GraphQL pro práci s Twenty API z vašich logických funkcí a frontendových komponent.
CoreApiClient je hlavní klient pro dotazování a mutace dat pracovního prostoru. Generuje se z vašeho schématu pracovního prostoru během yarn twenty dev nebo yarn twenty dev:build, takže je plně typovaný tak, aby odpovídal vašim objektům a polím.
Klient používá syntaxi výběrové sady (selection-set): předáním true zahrnete pole, pro argumenty použijte __args a pro relace vnořujte objekty. Získáte plné automatické doplňování a kontrolu typů založené na schématu vašeho pracovního prostoru.
CoreApiClient je generován při vývoji/sestavení. Pokud jej použijete bez předchozího spuštění yarn twenty dev nebo yarn twenty dev:build, vyvolá chybu. Generování probíhá automaticky — CLI prozkoumá GraphQL schéma vašeho pracovního prostoru a vygeneruje typovaného klienta pomocí @genql/cli.

Použití CoreSchema pro anotace typů

CoreSchema poskytuje typy TypeScriptu odpovídající objektům vašeho pracovního prostoru — hodí se pro typování stavu komponent nebo parametrů funkcí:
MetadataApiClient je dodáván předem sestavený v rámci SDK (není vyžadováno žádné generování). Odesílá dotazy na endpoint /metadata pro konfiguraci pracovního prostoru, aplikace a nahrávání souborů.

Nahrávání souborů

MetadataApiClient obsahuje metodu uploadFile pro připojování souborů k polím typu souboru:
Hlavní body:
  • Používá universalIdentifier pole (nikoli jeho ID specifické pro pracovní prostor), takže váš kód pro nahrávání funguje v jakémkoli pracovním prostoru, kde je vaše aplikace nainstalována.
  • Vrácená hodnota url je podepsaná adresa URL, kterou můžete použít k přístupu k nahranému souboru.
Když váš kód běží na Twenty (logické funkce nebo frontendové komponenty), platforma vloží přihlašovací údaje jako proměnné prostředí:
  • TWENTY_API_URL — Základní URL Twenty API
  • TWENTY_APP_ACCESS_TOKEN — krátkodobý klíč s rozsahem omezeným na výchozí roli funkce vaší aplikace
Není nutné je předávat klientům — čtou je automaticky z process.env. Oprávnění API klíče jsou určena rolí deklarovanou pomocí defineApplicationRole() (nebo odkazovanou prostřednictvím defaultRoleUniversalIdentifier v application-config.ts).