Testar, acompanhar e tratar erros: como manter um fluxo confiável
Um fluxo só é útil se você confia nele. Veja como testar um passo isolado, ler o histórico de execuções e definir o que acontece quando um nó falha, no módulo Fluxos do CollaborAI Enterprise.
Montar um fluxo leva uma tarde. Confiar nele leva um pouco mais. A API que fica fora do ar, o e-mail sem assunto, a lista que um dia veio vazia: é nesses casos que uma automação mostra se foi bem feita. O módulo Fluxos do CollaborAI Enterprise tem três recursos para isso: o teste de passo, o histórico de execuções e as configurações de erro de cada nó.
Este artigo faz parte da série sobre o módulo, que começa na visão geral.
Testar um passo de cada vez
Você não precisa rodar o fluxo inteiro para saber se um nó está certo. Abra o nó e clique em Testar passo. Só aquele nó roda, com os dados de entrada, e o resultado aparece na coluna Saída.
A tela do nó tem tudo o que você precisa para depurar:
- Entrada: os dados que chegam, em tabela, JSON ou esquema. Um seletor escolhe de qual nó anterior você quer ver os dados.
- Parâmetros: os campos do nó. Enquanto você edita uma expressão, a prévia mostra o valor calculado com os dados reais.
- Saída: o resultado da última execução ou do último teste, com o tempo e a contagem de itens.
Se o nó ainda não recebeu dados, execute o fluxo uma vez, ou teste o passo anterior. A partir daí, dá para ajustar um nó e testar só ele, quantas vezes for preciso.
O teste é de verdade
Esse é o aviso mais importante do módulo: o teste executa a ação. Um nó de e-mail envia, um nó do WhatsApp manda a mensagem, e uma requisição POST grava no outro sistema.
| Situação | O que acontece |
|---|---|
| Testar passo em um nó de envio | Envia de verdade |
| Executar fluxo | Roda tudo de verdade |
| Executar fluxo com Execução de teste ligada | Os e-mails do nó Enviar e-mail vão para o endereço de teste. Conectores e chamadas HTTP continuam reais |
Enquanto constrói, use destinatários seus e dados de exemplo. Outra saída é desativar um nó: no menu do nó, a opção Desativar faz os itens passarem por ele sem executar. Serve para desligar o envio enquanto você ajusta o resto.
Rascunho, ativo e pausado
O interruptor da barra superior define o estado do fluxo:
- Rascunho: só roda quando você executa. Pode ser salvo incompleto. O editor mostra as pendências e marca os nós que faltam configurar.
- Ativo: o agendamento dispara e o webhook aceita chamadas. Só é possível ativar um fluxo completo e válido.
- Pausado: o agendamento para e o webhook passa a responder erro, sem apagar nada.
Editar um fluxo ativo não afeta uma execução em andamento. Cada execução usa a versão do fluxo que existia quando ela começou.
O histórico de execuções
O botão Execuções, na barra superior, abre a lista de tudo o que o fluxo rodou: quando, por qual gatilho, quanto tempo levou e como terminou.
Clicar em uma execução sobrepõe o resultado ao desenho:
- Os nós concluídos mostram o número de itens que produziram.
- As setas mostram quantos itens passaram por elas.
- O nó que falhou fica marcado com erro.
- Abrindo qualquer nó, você vê a entrada e a saída daquela execução.
É a contagem nas setas que responde à pergunta mais comum: “por que não chegou nada no final?”. Siga os números até o ponto em que eles viram zero. Uma execução em andamento também pode ser cancelada pelo painel.
Quando um nó falha
Cada nó tem, na aba Configurações, duas decisões sobre erro.
Tentar novamente
A opção Tentar novamente em caso de falha repete o nó antes de desistir. Você define de 1 a 10 tentativas e o intervalo entre elas, de até 60 segundos. É o remédio para falhas passageiras: a API que oscilou, o serviço que demorou.
Em caso de erro
Se as tentativas acabarem, o campo Em caso de erro decide o que vem depois:
| Opção | O que acontece | Quando usar |
|---|---|---|
| Parar o fluxo (padrão) | A execução falha naquele nó, e o dono do fluxo é avisado | O passo é essencial: sem ele, o resto não faz sentido |
| Continuar | O item segue adiante com um campo error | Um item com problema não deve travar os outros |
| Continuar pela saída de erro | O nó ganha uma saída erro, e os itens com falha seguem por ela | Você quer um tratamento próprio: avisar, registrar, tentar outro caminho |
A terceira opção é a mais útil em fluxos com muitos itens. Em um envio para 200 clientes, os 197 que deram certo seguem pelo caminho normal, e os 3 com problema vão para uma planilha de pendências.
Parar de propósito
O nó Parar execução encerra o fluxo quando o dado não serve para continuar. Com o resultado Falhar com erro, a execução aparece como falha e você é avisado, com a mensagem que escreveu. Com Concluir com sucesso, o fluxo só termina mais cedo. É diferente de um erro inesperado: aqui foi você quem decidiu parar.
As travas que já vêm ligadas
Algumas proteções não dependem de configuração:
- Tempo máximo de execução: 30 minutos por padrão, ajustável de 1 a 120 nas configurações do fluxo. Uma execução que passa do limite é encerrada.
- Domínios permitidos: o nó Requisição HTTP só chama os domínios que você listou.
- Credenciais cifradas: senhas e chaves ficam guardadas no fluxo e não aparecem no desenho nem no histórico.
- Código isolado: os nós de Python e JavaScript rodam sem internet e sem acesso às credenciais.
- Webhook com token: a URL carrega um token secreto e deixa de funcionar quando o fluxo é pausado.
Checklist antes de ativar
- Rodei o fluxo com um caso normal e conferi a saída do último nó.
- Rodei com o caso vazio: lista sem itens, caixa sem e-mail novo.
- Rodei com um dado ruim: campo faltando, valor fora do esperado.
- Os nós que chamam sistemas externos têm Tentar novamente ligado.
- Decidi o Em caso de erro dos nós críticos.
- Conferi a contagem de itens antes de cada nó de envio.
- Os destinatários de teste foram trocados pelos reais.
- O fuso horário do agendamento está certo.
- Os nós têm nomes claros, e os mais delicados têm uma nota explicando o porquê.
Depois de ativar
Na primeira semana, abra o histórico todos os dias. Depois, basta olhar quando chegar um aviso de falha. Quando o processo mudar, edite o fluxo em vez de criar outro parecido: dois fluxos quase iguais são a origem mais comum de mensagem duplicada.
Um fluxo confiável é aquele em que você sabe o que acontece quando dá errado. O último artigo da série reúne casos de uso por área da empresa.