Workflows

Visão geral

Um workflow é uma automação que começa num trigger e transporta dados através de uma cadeia de passos até produzir um efeito — escrever registos, enviar um email, chamar um sistema externo. Cada passo lê os dados que o workflow já reuniu até esse ponto, faz um trabalho, e passa o resultado ao passo seguinte, para que o que um passo produz o seguinte possa consumir.

Os workflows substituem trabalho manual repetitivo e scripts ad-hoc: importar um lote de documentos, reagir a uma mudança de estado, sincronizar dados com um sistema externo, ou pausar para que alguém verifique algo antes de ser aplicado.

Os workflows são geridos na secção Workflows do Painel de administração. A barra lateral lista os teus workflows — pesquisáveis, com ações de duplicar/renomear/arquivar (arquivar mantém o histórico de execuções, não o elimina) — mais uma entrada Connections para os serviços externos que os passos podem usar.

Triggers

Um workflow tem exatamente um trigger. Triggers disponíveis:

Trigger	Dispara quando	Configuração
Manual (a pedido)	Alguém o dispara manualmente, a partir de um de quatro âmbitos: Genérico (sem contexto — por exemplo, um botão de dashboard), Linha (um único registo), Feature (vários/todos os registos de uma feature), Vista (os registos atualmente visíveis numa vista)	O âmbito, mais uma feature de origem (Linha/Feature) ou uma vista (Vista)
Upload de ficheiro	Documentos são carregados através da própria caixa de diálogo de upload do workflow — uma execução por ficheiro	Extensões de ficheiro aceites
Webhook	Um sistema externo envia um pedido POST para o URL próprio do workflow	O URL/token é gerado automaticamente para ti (copia-o, ou regenera para invalidar o antigo), mais uma descrição opcional
Agendado (cron)	Numa agenda	Um intervalo simples (a cada N minutos/horas/dias) ou uma agenda de calendário (diária/semanal/mensal/anual/uma vez, ou uma expressão cron em bruto), com fuso horário
Registo criado / Registo atualizado / Registo apagado	Um registo numa feature escolhida é criado, atualizado, ou eliminado	Feature a observar, um filtro sobre os dados do registo; "Registo atualizado" também aceita um filtro sobre o estado anterior (para modelar uma transição, por exemplo pending → paid) e uma lista de colunas que têm de ter mudado

Passos

Os passos estão agrupados em cinco categorias. A paleta de passos (aberta a partir do + no canvas) está organizada da mesma forma, e o canvas colore o conector de cada passo consoante a categoria.

Sources — trazer dados

Passo	Lê
CSV — ler ficheiro	Um CSV carregado (delimitador, linha de cabeçalho)
Excel — ler folha	Uma folha Excel carregada
JSON — ler lista	Um array/objeto JSON de um ficheiro ou de uma variável
OCR — extrair documento	Campos estruturados de um documento (PDF/imagem) via AI, de acordo com um schema que definires
HTTP fetch	A resposta JSON de uma API externa, convertida em registos — opcionalmente através de uma ligação HTTP
Ler registos	As linhas de uma tabela de origem à escolha, com filtros tipados (os mesmos editores por tipo dos filtros de tabela - e cada regra aceita variáveis via um toggle {{}}) e um limite de linhas (500 por predefinição, máximo 2000) - a base para workflows de reconciliação. A opção "O que fazer aos registos" decide se as linhas lidas substituem as que já estão no fluxo ou se se lhes juntam, para conciliar duas tabelas

Transforms — reformular os dados

Passo	Faz
Mapear → colunas	Mapeia campos de origem para colunas da feature de destino, mais valores fixos
Deduplicar	Compara cada registo com registos existentes por um ou mais campos-chave e marca-o como insert / update / skip
Conciliar (match)	Concilia dois conjuntos de registos entre si (regras exatas/numéricas/de data/fuzzy) e atribui uma pontuação a cada correspondência — por exemplo, movimentos bancários vs faturas
Agente (emit-only)	Envia os dados atuais para um agente de AI com um prompt e um schema; o resultado junta-se às variáveis do workflow (por exemplo, para classificar um tipo de documento). O agente só propõe — nunca escreve nada por si só

Control — decidir o caminho

Passo	Faz
Condição (if/else)	Ramifica com base numa variável, na contagem de registos, ou na forma dos dados
Agente escolhe a rota	Um agente de AI escolhe exatamente uma de várias rotas nomeadas que definires (pelo menos duas); cada rota torna-se numa faixa própria no canvas
Sub-workflow	Corre outro workflow como um único passo. Por predefinição dispara uma vez com os dados atuais (fire-and-forget); em alternativa, pode gerar uma execução filha por registo e esperar que todas terminem antes de continuar

Gates — pausar para uma pessoa

Passo	Faz
Revisão humana	Pausa a execução e mostra os dados propostos para alguém editar, aprovar, ou rejeitar. A apresentação adapta-se aos dados: campos simples (predefinição), uma tabela quando os registos correspondem a uma feature, um visualizador de documentos, campos de email, ou um único bloco de texto — definido via "Formato de revisão". Um limiar de confiança opcional pode aprovar automaticamente registos acima desse valor
Aprovação	Um ponto de controlo simples de aprovar/rejeitar com um título e mensagem personalizados — sem registos mostrados

Em Revisão humana, cada registo recebe uma decisão insert / update / skip mais um toggle de rejeição; aprovar escreve o lote e retoma a execução. Se todos os registos acabarem rejeitados, a caixa de diálogo oferece antes Rejeitar e repetir (começar uma nova execução a partir dos mesmos dados de origem) ou Rejeitar e retomar (terminar esta execução sem escrever nada).

Sinks — o efeito

Passo	Faz
Escrever registo	Escreve ou atualiza registos numa tabela à escolha, com cada coluna-alvo ligada a um valor (literal ou variável). Produz {{vars.write.*}} — o id e os dados do registo escrito — para os passos seguintes
Guardar registos preparados	Escreve os registos aprovados na feature de destino: insere novos, atualiza correspondências (pela mesma chave que o Deduplicar), ou ignora. Seguro de retomar depois de uma pausa — nunca escreve o mesmo registo duas vezes
Enviar email	Envia um email (destinatários/assunto/corpo), opcionalmente com os ficheiros do workflow anexados — através do transporte de email global ou de uma ligação SMTP específica
Chamar tool MCP	Chama uma tool num servidor MCP externo (por exemplo, um sistema de faturação) através de uma ligação MCP

Referenciar dados de outros passos

Os valores dos campos na configuração de um passo podem referenciar os dados que o workflow já reuniu até esse ponto:

Referência	Aponta para
{{record.campo}}	O registo atual do conjunto de trabalho
{{records.2.campo}}	Um registo específico, por índice
{{vars.nome}}	Uma variável do workflow
{{vars.trigger.coluna}}	A linha que disparou o workflow
{{vars.write.rowId}}, {{vars.write.record.coluna}}	O resultado do último Escrever registo - também inserted, updated, rowIds. É sempre o do passo de escrita mais recente: numa cadeia com vários, usa antes {{vars.steps.<id>.write...}} para apontar a um passo concreto
{{vars.steps.<id>.<saída>...}}	A saída de um passo específico, pelo seu id - sem ambiguidade quando há dois passos iguais na cadeia
{{sys.now}}, {{sys.today}}	Data e hora atuais / data de hoje

Cada campo de configuração que aceita {{...}} tem, no próprio campo, um botão {} que abre um menu com pesquisa e agrupado - Gatilho, Variáveis, Saídas por passo, Registos, Ficheiros, Sistema - listando o rótulo de cada coluna (não o nome técnico) e o respetivo tipo; escolher uma entrada insere o token na posição do cursor desse campo. As saídas compostas, como o registo escrito por Escrever registo, aparecem já expandidas coluna a coluna, com o rótulo e o tipo de cada uma: já não é preciso escrever os caminhos profundos à mão.

Nos filtros do passo Ler registos, cada regra tem um toggle {{}} que troca o valor tipado (o mesmo editor por tipo dos filtros de uma vista em tabela) por um campo de texto livre - com o mesmo botão {} - para comparar a coluna com uma variável em vez de um valor fixo.

A maior parte dos passos mostra dois painéis no rail de configuração: Recebe, no início, com o que chega do passo anterior (ou do gatilho); e Produz, no fim, com o que esse passo acrescenta aos passos seguintes.

Ligações

As Connections (Workflows → Connections) são acessos reutilizáveis e pré-configurados a um serviço externo, referenciados por nome a partir dos passos. Os secrets são encriptados no vault e não podem ser lidos de volta depois de guardados — só substituídos.

Tipo	Guarda	Usado por
HTTP	URL base, headers, autenticação, endpoints com nome	HTTP fetch
MCP	URL do servidor, autenticação (nenhuma / bearer token / header personalizado)	Chamar tool MCP
SMTP	Host, porta, utilizador, endereço de remetente, TLS	Enviar email
AI Provider	Fornecedor, modelo, URL base (traz a tua própria chave)	Passos de OCR e de agente

Os passos de AI (OCR, agente) funcionam prontos a usar com as definições de AI configuradas na organização — uma ligação AI Provider só é necessária para usar um fornecedor ou chave diferente num passo específico. Uma ligação guardada pode ser verificada com Testar ligação na respetiva caixa de diálogo de edição.

Criar um workflow

A partir da barra lateral de Workflows, + inicia um novo workflow — do zero ou a partir de um template:

• Começar do zero — uma cadeia vazia, construída passo a passo.
• Importar CSV — CSV → mapear → deduplicar → rever → importar.
• Importar documentos (OCR) — OCR → mapear → deduplicar → rever → importar.
• Importar CSV (condicional) — a mesma importação de CSV, mas a revisão só entra em ação acima de um limiar de número de registos.
• Agente revisor (confiança) — um agente elabora uma resposta, um segundo atribui uma pontuação de confiança, e só os resultados de baixa confiança vão para revisão humana antes de serem enviados.

O editor mostra o trigger como uma pill no topo do canvas, seguida da cadeia de passos: clica no + no fio de ligação para inserir ali um passo, clica num cartão de passo para editar a sua configuração. Passos de ramificação (if/else, encaminhados por AI) bifurcam o canvas em faixas lado a lado que voltam a juntar-se.

As alterações são um rascunho até Guardar nova versão — guardar cria uma nova versão; as versões anteriores e o respetivo histórico de execuções mantêm-se intactos. Uma faixa de avisos acima do canvas assinala configuração incompleta (por exemplo, uma feature de destino em falta); Executar fica desativado enquanto houver alterações não guardadas ou erros por resolver.

Executar um workflow

Manualmente, onde o botão aparece depende do âmbito do trigger:

• Genérico, Linha, Feature — o componente Workflow, colocado num formulário ou numa coluna de tabela; também disponível no menu de ações do painel de detalhe do registo. Linha precisa do botão numa linha ou num formulário aberto; Genérico e Feature funcionam a partir de qualquer vista.
• Feature / Vista — também (ou, no caso de Vista, só) o botão "Ações Globais" na barra de ferramentas de uma vista em tabela, em "AÇÕES DA TABELA" / "AÇÕES DA VISTA". O componente Workflow recusa-se a disparar um workflow com âmbito Vista por si só — em vez disso, encaminha-te para esta ação da barra de ferramentas.

Automaticamente, um workflow dispara por si só assim que a condição do trigger é satisfeita: uma alteração de registo correspondente, um horário agendado, ou uma chamada de webhook recebida — sem necessidade de ação do utilizador.

Para testar um workflow antes de ligar o seu trigger real, usa o próprio botão Executar do editor: para file.upload abre a caixa de diálogo de upload real; para qualquer outro trigger abre uma caixa de diálogo de simulação onde escolhes um registo real ou escreves JSON à mão. Continua a criar uma execução real — só a origem dos dados de entrada é simulada.

Execuções

O editor de cada workflow mostra as suas execuções num painel lateral, que se atualiza automaticamente enquanto alguma estiver em curso.

Estado	Significado
Pendente	Em fila, ainda não foi apanhado
A correr	Em curso
A rever / A aprovar	Pausado num Gate, à espera de uma pessoa
A aguardar	Pausado à espera de um webhook, de uma agenda, ou de execuções filhas
Sucesso	Concluído
Falhou	Falhou — passa o rato sobre o ícone de erro para veres o motivo
Cancelado / Rejeitado	Interrompido, ou rejeitado num Gate

Selecionar uma execução destaca onde ela está no canvas, e acrescenta um botão Rever/Aprovar diretamente no passo pausado. O ícone de histórico de cada execução abre uma linha do tempo passo a passo — estado, tempos, e (através do botão </>) os dados exatos de entrada/saída de cada passo, para depuração.

Uma falha transitória (por exemplo, uma chamada externa instável) não aparece como Falhou — a execução volta a Pendente e retoma automaticamente a partir de onde parou, até um limite de tentativas; o ícone de erro mostra o número de tentativas e o motivo da última falha.

Dicas

• Um workflow precisa de um trigger e de pelo menos um passo — uma cadeia vazia não pode correr.
• file.upload precisa de uma feature de destino configurada num passo map antes de permitir o upload.
• A aprovação automática em Revisão humana é fail-closed: um valor de confiança em falta, ou abaixo do limiar, continua a ir para uma pessoa.
• Aprovação não tem atribuição por aprovador — quem quer que abra a execução pode aprová-la ou rejeitá-la.
• As chamadas Sub-workflow aninhadas têm um limite de 5 níveis, para evitar recursão descontrolada.
• Arquivar um workflow impede-o de disparar mas mantém o seu histórico de execuções — nada é eliminado.