defineLogicFunction
Definujte logické funkce a jejich spouštěče
defineLogicFunction
Definujte logické funkce a jejich spouštěče
Každý soubor funkce používá Dostupné typy spouštěčů:Typ Ve vašem handleru k přeposlaným záhlavím přistupujte takto: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ř. Endpoint je dostupný na:Identifikátor je Smlouva resolveru. Typ Tělo zprávy obsahuje: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í:Hlavní body:Abyste deklarovali své parametry jen jednou a obsloužili obě rozhraní, definujte jedno JSON Schema (Jakmile je aplikace nainstalovaná, Enrich Company se zobrazí ve výběru akcí tvůrce workflow. Tvůrce zobrazí
defineLogicFunction() k exportu konfigurace s obslužnou funkcí (handlerem) a volitelnými spouštěči.src/logic-functions/createPostCard.logic-function.ts
- 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í adresuTWENTY_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 poliupdatedFields. 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ží objektRoutePayload, který odpovídá
AWS HTTP API v2 formátu.
Importujte typ RoutePayload z twenty-sdk/logic-function: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 poliforwardedRequestHeaders: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: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-typecontent-languagecontent-dispositioncache-controlretry-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:- 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ímurawBodya předaným hlavičkám a může request odmítnout, aniž by se vůbec dotkl cíle. - 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
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.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.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ží jedenDatabaseEventPayload 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.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.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éInputSchemaod Twenty, aby builder mohl vykreslit správné editory polí, voliče proměnných a štítky.
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
- Funkce může míchat rozhraní — deklarujte jak
toolTriggerSettings, takworkflowActionTriggerSettings, abyste ji zpřístupnili v chatu i ve workflow builderu. toolTriggerSettings.inputSchemaaworkflowActionTriggerSettings.inputSchemajsou obě volitelné. Pokud jsou vynechány, sestavovač manifestu je odvodí ze zdrojového kódu handleru (JSON Schema pro nástroj AI,InputSchemaod Twenty pro akci workflow). Uveďte jej explicitně, když chcete bohatší typování — například u polí s podporouFieldMetadataType, jakoCURRENCYneboRELATIONpro workflow builder, nebo s polidescription, která si AI agent může přečíst:
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
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íčektwenty-client-sdk poskytuje dva typované klienty GraphQL pro práci s Twenty API z vašich logických funkcí a frontendových komponent.
CoreApiClient
Dotazování a změny dat pracovního prostoru (záznamy, objekty)
CoreApiClient
Dotazování a změny dat pracovního prostoru (záznamy, objekty)
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.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
Konfigurace pracovního prostoru, aplikace a nahrávání souborů
MetadataApiClient
Konfigurace pracovního prostoru, aplikace a nahrávání souborů
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á
universalIdentifierpole (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
urlje 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 APITWENTY_APP_ACCESS_TOKEN— krátkodobý klíč s rozsahem omezeným na výchozí roli funkce vaší aplikace
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).