defineLogicFunction
Defina funções de lógica e seus gatilhos
defineLogicFunction
Defina funções de lógica e seus gatilhos
Cada arquivo de função usa Tipos de gatilho disponíveis:O tipo No seu manipulador, acesse os cabeçalhos encaminhados assim:Por motivos de segurança, os cabeçalhos de resposta são restringidos a uma lista de permissões. Qualquer cabeçalho que não esteja na lista (por exemplo, O endpoint fica acessível em:O identificador é o Contrato do resolver. O tipo O payload inclui:Exemplo de evento de criação:Exemplo de evento de atualização:Disparar somente em atualizações de email:Exemplo de evento de destruição:Pontos-chave:Para declarar seus parâmetros uma vez e atender a ambas as interfaces, defina um único JSON Schema (Depois que o app é instalado, Enrich Company aparece no seletor de ações do construtor de fluxos de trabalho. O construtor renderiza
defineLogicFunction() para exportar uma configuração com um manipulador e gatilhos opcionais.src/logic-functions/createPostCard.logic-function.ts
- httpRoute: Expõe sua função em um caminho e método HTTP. No código do app, prefixe o caminho da rota com
/s/ao usarRestApiClient; a URL implantada usa a base injetadaTWENTY_FUNCTIONS_URL(ou\<server-url>/squando ela não está definida).
Para invocar uma função de lógica acionada por rota a partir de um componente de front-end (headless), consulte Chamando uma função de lógica.
- cron: Executa sua função em um agendamento usando uma expressão CRON.
- databaseEvent: Executa em eventos do ciclo de vida de objetos do espaço de trabalho. Quando a operação do evento é
updated, campos específicos a serem observados podem ser especificados no arrayupdatedFields. Se deixar indefinido ou vazio, qualquer atualização acionará a função.
por exemplo,person.updated,*.created,company.*
- serverRoute: expõe uma única rota HTTP com escopo de registro. Uma função resolver (declarada com
serverRouteTriggerSettings) é executada no workspace proprietário e retorna umaResponsesíncrona ou o workspace de destino E a função de lógica de destino para enfileirar; no caminho de enfileiramento, a plataforma confirma com202e executa esse destino na fila de workers. Veja gatilho de rota de servidor.
Você também pode executar manualmente uma função usando a CLI:Você pode acompanhar os logs com:
Payload de gatilho de rota
Quando um gatilho de rota invoca sua função de lógica, ela recebe um objetoRoutePayload que segue o formato HTTP API v2 da AWS.
Importe o tipo RoutePayload de twenty-sdk/logic-function:RoutePayload tem a seguinte estrutura:forwardedRequestHeaders
Por padrão, os cabeçalhos HTTP das requisições recebidas não são repassados para sua função de lógica por motivos de segurança. Para acessar cabeçalhos específicos, liste-os explicitamente no arrayforwardedRequestHeaders:Os nomes dos cabeçalhos são normalizados para minúsculas. Acesse-os usando chaves em minúsculas (por exemplo,
event.headers['content-type']).Resposta HTTP personalizada
Por padrão, retornar um valor simples do seu handler o envia de volta como uma resposta200 (JSON para objetos, text/plain para strings). Para controlar o código de status e os cabeçalhos da resposta, retorne um Response de twenty-sdk/logic-function:Set-Cookie, cabeçalhos CORS como Access-Control-Allow-Origin ou cabeçalhos personalizados X-*) é silenciosamente descartado antes de a resposta ser enviada. Os cabeçalhos de resposta permitidos são:content-typecontent-languagecontent-dispositioncache-controlretry-after
O código de status deve ser um código de status HTTP válido (entre 100 e 599). Os nomes dos cabeçalhos de resposta são comparados sem distinção entre maiúsculas e minúsculas.
Gatilho de rota de servidor
httpRouteTriggerSettings expõe uma função em /s/ e resolve o workspace a partir do host da solicitação — o que funciona quando cada workspace tem seu próprio domínio. Provedores de terceiros, entretanto, entregam os eventos de todos os workspaces para uma URL. Para esse caso, use serverRouteTriggerSettings.Nesse caso, o gatilho tem duas partes:-
Uma função de lógica de resolver — declarada com
serverRouteTriggerSettings— é executada no seu workspace proprietário (o workspace que é proprietário do registro da aplicação). Ela inspeciona a requisição recebida e retorna um dos seguintes:{ workspaceId, targetLogicFunctionUniversalIdentifier, payload? }— a plataforma coloca esse destino em fila no workspace resolvido e confirma com202 { queued: true }, ou- uma
Responsedetwenty-sdk/logic-function— a plataforma repete essa resposta HTTP sincronamente e não coloca nenhum destino em fila (use isso para handshakes de desafio, como ourl_verificationdo Slack).
rawBodyoriginal e aos headers encaminhados e pode rejeitar sem nunca tocar no alvo. - Uma função de lógica de target — uma função de lógica regular por workspace — então é executada no workspace resolvido com o payload retornado pelo resolver (ou o payload original da requisição, se o resolver não o tiver transformado). Seu valor de retorno não é observado pelo chamador HTTP quando o resolver escolheu o caminho de enfileiramento.
src/logic-functions/resolve-server-route.logic-function.ts
src/logic-functions/handle-invoice-paid.logic-function.ts
universalIdentifier do resolver, vindo do seu manifest. Registre essa URL junto ao provedor.O aplicativo deve ser reivindicado e instalado em seu workspace proprietário. Como o resolvedor é executado no workspace proprietário (o workspace que é proprietário do registro do aplicativo), um acionador de rota de servidor só funciona depois que o aplicativo tiver sido reivindicado — ou seja, tiver um workspace proprietário — e esse aplicativo estiver instalado no workspace proprietário. Até que ambas as condições sejam verdadeiras, o resolvedor não tem onde ser executado, portanto a rota não pode ser despachada. Um aplicativo que expõe uma função lógica
serverRouteTriggerSettings, portanto, não pode ser listado no marketplace até que seja reivindicado e instalado em seu workspace proprietário.LogicFunctionConfig do SDK aplica isso em tempo de compilação: assim que você define serverRouteTriggerSettings, o seu handler fica limitado a retornar uma Response ou { workspaceId: string; targetLogicFunctionUniversalIdentifier: string; payload?: object } (ou uma Promise de qualquer um deles). No caminho de dispatch, o workspaceId deve ser um workspace onde a função de destino esteja instalada, caso contrário a requisição é rejeitada com 404. Um resultado que não corresponda a nenhum dos formatos — incluindo um cujos identificadores não sejam UUIDs — é rejeitado com 502.Para assinaturas de requisição, a maioria dos provedores assina com HMAC-SHA256; as partes que diferem são o nome do header, a codificação do digest e a string de payload assinada. Alguns exemplos:
O exemplo de resolver acima já mostra o fluxo de HMAC-SHA256 do GitHub — adapte o nome do header, a codificação do digest e a string de payload assinada de acordo com o provedor com o qual você está integrando.
Quando o resolver retorna um objeto de dispatch, a rota responde com
202 { queued: true } e o destino é executado na fila de workers — quem faz a chamada nunca observa a latência, o resultado ou as falhas do destino (essas são registradas nos logs de execução). Isso evita que reentregas do remetente amplifiquem a lentidão do processamento, que é o que você quer para a ingestão de webhooks.Quando o chamador precisa ler o corpo da resposta na mesma requisição (handshakes de desafio, acknowledgements interativos), retorne, em vez disso, uma Response a partir do resolver. A plataforma o replica de forma síncrona e ignora a fila; seus headers passam pela mesma allow-list que as respostas de rotas HTTP. Mantenha o resolver rápido — alguns provedores (por exemplo, Slack) atingem timeout em poucos segundos. Como o resolver fica acessível como um endpoint público, proteja-o com rate limiting na sua borda.Payload do gatilho de evento do banco de dados
Quando um gatilho de evento do banco de dados invoca sua função lógica, ela recebe umDatabaseEventPayload por registro alterado. O payload combina metadados sobre o workspace e o objeto de origem com o evento em nível de registro.Para exclusões lógicas,
.deleted segue o formato de atualização porque o campo deletedAt do registro é alterado.
Para exclusões permanentes, use .destroyed.databaseEventTriggerSettings.updatedFields filtra quais eventos de atualização disparam a função.
event.properties.updatedFields informa quais campos realmente foram alterados no evento atual.Expor uma função como ferramenta de IA ou como ação de fluxo de trabalho
As funções de lógica podem ser expostas em duas superfícies, cada uma com seu próprio gatilho:toolTriggerSettings— torna a função disponível para os recursos de IA do Twenty (chat, MCP, chamadas de função). Usa o JSON Schema padrão, o formato que os LLMs entendem nativamente.workflowActionTriggerSettings— torna a função visível como uma etapa no construtor visual de fluxos de trabalho. Usa oInputSchemaavançado do Twenty para que o construtor possa renderizar editores de campo adequados, seletores de variáveis e rótulos.
cronTriggerSettings, databaseEventTriggerSettings e httpRouteTriggerSettings — mesmo padrão, mesmo formato.Relação com a ação Code do fluxo de trabalho. A ação Code incorporada no construtor de fluxos de trabalho é, em si, uma função lógica — a Twenty cria uma para cada etapa Code e exibe seu editor em linha.
workflowActionTriggerSettings é como você transforma esse código em linha único em uma ação reutilizável: defina a função uma vez no seu app e ela se torna selecionável em qualquer fluxo de trabalho, em vez de ser copiada e colada em cada etapa Code. Veja a ação Code no guia do usuário para a visão do usuário final.src/logic-functions/enrich-company.logic-function.ts
- Uma função pode misturar superfícies — declare tanto
toolTriggerSettingsquantoworkflowActionTriggerSettingspara expô-la no chat E no construtor de fluxos de trabalho. toolTriggerSettings.inputSchemaeworkflowActionTriggerSettings.inputSchemasão opcionais. Quando omitidos, o construtor de manifestos os infere a partir do código-fonte do handler (JSON Schema para a ferramenta de IA,InputSchemado Twenty para a ação de fluxo de trabalho). Forneça um explicitamente quando quiser uma tipagem mais rica — por exemplo, com campos compatíveis comFieldMetadataType, comoCURRENCYouRELATIONpara o construtor de fluxos de trabalho, ou com camposdescriptionque o agente de IA pode ler:
InputJsonSchema) e converta-o para a ação de fluxo de trabalho com jsonSchemaToInputSchema de twenty-sdk/logic-function. toolTriggerSettings.inputSchema recebe o JSON Schema diretamente, enquanto workflowActionTriggerSettings.inputSchema espera o InputSchema da Twenty:Um exemplo completo de ação de fluxo de trabalho
workflowActionTriggerSettings aceita quatro campos:Juntando tudo — uma função exposta como uma ação de fluxo de trabalho, com uma saída declarada para que etapas posteriores possam referenciar
taskId:src/logic-functions/enrich-company.logic-function.ts
companyName e domain como campos de entrada (cada um podendo extrair valores de etapas anteriores), e as etapas subsequentes podem referenciar as saídas taskId e enriched da etapa.Escreva uma boa
description. Os agentes de IA dependem do campo description da função para decidir quando usar a ferramenta. Seja específico sobre o que a ferramenta faz e quando ela deve ser chamada.Auxiliares de tempo de execução.
twenty-sdk/utils reexporta pequenos auxiliares de tempo de execução para que os handlers nunca importem diretamente de twenty-shared. Por exemplo, isDefined(value) retorna false tanto para null quanto para undefined — use-o para restringir com segurança entradas opcionais de handlers, que podem chegar como null em tempo de execução mesmo quando tipadas como T | undefined:Hooks de instalação — manipuladores de pré-instalação, pós-instalação e desinstalação — compartilham esse ambiente de execução, mas são declarados com suas próprias funções de definição e não usam configurações de gatilho. Veja Hooks de instalação para
definePreInstallLogicFunction, definePostInstallLogicFunction e defineUninstallLogicFunction.Clientes de API tipados (twenty-client-sdk)
O pacotetwenty-client-sdk fornece dois clientes GraphQL tipados para interagir com a API do Twenty a partir das suas funções de lógica e componentes de front-end.
CoreApiClient
Consultar e modificar dados do espaço de trabalho (registros, objetos)
CoreApiClient
Consultar e modificar dados do espaço de trabalho (registros, objetos)
CoreApiClient é o cliente principal para consultar e mutar dados do espaço de trabalho. Ele é gerado a partir do schema do seu espaço de trabalho durante yarn twenty dev ou yarn twenty dev:build, então é totalmente tipado para corresponder aos seus objetos e campos.true para incluir um campo, use __args para argumentos e aninhe objetos para relações. Você tem preenchimento automático e verificação de tipos completos com base no schema do seu espaço de trabalho.CoreApiClient é gerado em tempo de dev/build. Se você usá-lo sem executar primeiro
yarn twenty dev ou yarn twenty dev:build, ele lançará um erro. A geração ocorre automaticamente — a CLI analisa o schema GraphQL do seu espaço de trabalho e gera um cliente tipado usando @genql/cli.Usando CoreSchema para anotações de tipo
CoreSchema fornece tipos TypeScript que correspondem aos objetos do seu espaço de trabalho — útil para tipar o estado de componentes ou parâmetros de função:MetadataApiClient
Configuração do espaço de trabalho, aplicativos e upload de arquivos
MetadataApiClient
Configuração do espaço de trabalho, aplicativos e upload de arquivos
MetadataApiClient é fornecido pré-compilado com o SDK (não é necessário gerar). Ele consulta o endpoint /metadata para configuração do espaço de trabalho, aplicativos e upload de arquivos.Carregamento de arquivos
MetadataApiClient inclui um método uploadFile para anexar arquivos a campos do tipo arquivo:Pontos-chave:
- Usa o
universalIdentifierdo campo (não o ID específico do espaço de trabalho), de modo que seu código de upload funcione em qualquer espaço de trabalho onde seu aplicativo esteja instalado. - A
urlretornada é uma URL assinada que você pode usar para acessar o arquivo enviado.
Quando seu código é executado no Twenty (funções de lógica ou componentes de front-end), a plataforma injeta credenciais como variáveis de ambiente:
TWENTY_API_URL— URL base da API do TwentyTWENTY_APP_ACCESS_TOKEN— Chave de curta duração com escopo para o papel de função padrão do seu aplicativo
process.env automaticamente. As permissões da chave de API são determinadas pelo papel declarado com defineApplicationRole() (ou referenciado via defaultRoleUniversalIdentifier em application-config.ts).