Guia de Design de Workflows

Projete workflows no Flowker com clareza e controle. Este guia apresenta os tipos de nodes, edges, padrões do mundo real, transições de status, limites técnicos e boas práticas para ajudar você a construir orquestrações confiáveis e fáceis de manter.

Tipos de nodes

Todo workflow é construído a partir de nodes. Cada node possui um type que define como o Flowker o processa em tempo de execução.

trigger

Um node trigger é um ponto de entrada da execução. Workflows em draft podem estar incompletos, mas a ativação exige pelo menos um node trigger. Quando uma execução começa por um trigger, o motor entra por esse node e inicia o roteamento a partir dele. Os exemplos desta página mostram apenas a topologia dos nodes. Um node trigger real também carrega um triggerType e a configuração desse trigger em seu data — veja Configurando um trigger de webhook ou Executando um workflow em um agendamento.

{
  "id": "node-trigger",
  "type": "trigger",
  "name": "Payment Received"
}

executor

Chama um serviço externo por meio de uma configuração de provider. Este é o bloco fundamental para integração com motores de fraude, providers de pagamento, serviços de notificação e outros sistemas externos. Os exemplos desta página mostram apenas a topologia dos nodes. Um node executor real também carrega um providerConfigId e, se usar um executor do catálogo, um executorId em seu data. Um node que chama uma operação de um documento OpenAPI enviado omite executorId e carrega operation_path e operation_method — veja o Guia de integração.

{
  "id": "node-fraud-check",
  "type": "executor",
  "name": "Check Fraud Score"
}

conditional

Avalia uma condição contra o contexto de execução e roteia para diferentes ramificações com base no resultado. Use nodes condicionais para implementar lógica de ramificação, por exemplo, roteando para um caminho de aprovação quando o risco é alto, ou continuando diretamente quando é baixo. A condição fica em data.condition do node. Uma expressão de texto livre é avaliada como booleana e produz o handle de saída true ou false; cada edge de saída declara qual handle segue por meio de sourceHandle. Nodes condicionais criados no Console usam uma condição estruturada baseada em casos, em que cada caso roteia para seu próprio handle de saída — veja o Editor de canvas.

{
  "id": "node-risk-decision",
  "type": "conditional",
  "name": "Evaluate Risk Score",
  "data": { "condition": "node-fraud-check.riskScore < 70" }
}

action

Representa uma operação interna síncrona set_output. Ela pode gravar um valor de saída interpolado e, opcionalmente, substituir o status da resposta HTTP síncrona. Não fornece pausa integrada, emissão genérica de eventos nem uma operação genérica de mudança de estado.

{
  "id": "node-record-approval",
  "type": "action",
  "name": "Record Approval Decision"
}

Edges

Edges conectam nodes e definem caminhos de execução. Cada edge inclui os seguintes campos:

Campo	Descrição
`id`	Identificador único do edge.
`source`	ID do node de origem.
`target`	ID do node de destino.
`sourceHandle`	Handle de saída do node de origem que este edge segue. Obrigatório para rotear a partir de um node condicional: deve corresponder ao resultado da ramificação (`true` ou `false` para uma condição de texto livre).
`condition`	Campo legado de texto livre mantido por compatibilidade. Não é avaliado para roteamento — deixe vazio em workflows novos.
`label`	Rótulo legível usado para visualização e depuração.

Exemplo de edge

{
  "id": "edge-approved",
  "source": "node-risk-decision",
  "target": "node-process-payment",
  "sourceHandle": "true",
  "label": "Approved"
}

O roteamento depende do tipo do node de origem. Um node condicional avalia seu data.condition e segue o único edge de saída cujo sourceHandle corresponde ao resultado da ramificação; se nenhum edge corresponder, essa ramificação termina. Todos os outros tipos de node seguem todos os seus edges de saída quando concluem com sucesso.

Transições de status

Workflows seguem um ciclo de vida bem definido. Compreender essas transições é essencial para implantar e evoluir workflows com segurança.

Diagrama de transição de status de workflow mostrando três estados: draft, active e inactive. Uma seta rotulada 'activate' aponta de draft para active. Uma seta rotulada 'deactivate' aponta de active para inactive. Uma seta rotulada 'draft' aponta de inactive de volta para draft.

draft — O estado inicial. Todas as modificações (adicionar nodes, editar edges, alterar configurações) são permitidas apenas no status draft.
active — Um workflow que foi ativado. Pode ser executado. Nenhuma modificação é permitida enquanto estiver ativo.
inactive — Um workflow que foi desativado. Não pode mais ser executado, mas pode ser movido de volta para draft para edição.

Regras

Apenas um workflow em draft pode ser ativado (transição: draft → active).
Apenas um workflow active pode ser desativado (transição: active → inactive).
Apenas um workflow inactive pode ser movido de volta para draft (transição: inactive → draft).
Tentar uma transição inválida retorna o erro FLK-0102.
Tentar modificar um workflow que não está em draft retorna o erro FLK-0103.

Movendo um workflow inativo de volta para draft

Se você desativou um workflow e quer editá-lo novamente, mova-o de volta para draft chamando POST /v1/workflows/{id}/draft. Isso torna o workflow editável sem precisar cloná-lo. Isso é útil quando você desativou um workflow por engano ou quando quer iterar sobre um workflow existente em vez de criar uma cópia.

Apenas workflows inativos podem ser movidos para draft. Se você precisar modificar um workflow ativo sem tirá-lo do ar, use a abordagem de clone descrita abaixo.

Iterando com segurança usando clone

Para modificar um workflow ativo, clone-o primeiro. A clonagem cria um novo draft a partir de qualquer status, copiando todos os nodes e edges. Você pode então atualizar, testar e ativá-lo sem impactar a versão atual. Esta é a abordagem recomendada para versionamento em produção.

Limites técnicos

Limite	Valor	Código de erro
Máximo de nodes por workflow	100	`FLK-0113`
Máximo de edges por workflow	200	`FLK-0114`
Payload máximo de entrada para execução	1 MB	`FLK-0506`

Tenha esses limites em mente ao projetar fluxos complexos. Workflows com mais de ~50 nodes geralmente indicam que o fluxo deve ser dividido em workflows menores e compostos.

Padrões comuns

Sequencial

O padrão mais simples. Os nodes são executados em uma sequência linear. Use quando cada etapa depende da anterior e nenhuma ramificação é necessária.

Exemplo: Orquestração de pagamento

{
  "nodes": [
    { "id": "n1", "type": "trigger",  "name": "Payment Initiated" },
    { "id": "n2", "type": "executor", "name": "Validate Payment Data" },
    { "id": "n3", "type": "executor", "name": "Route to Provider" },
    { "id": "n4", "type": "executor", "name": "Send Confirmation Notification" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Valid" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Routed" }
  ]
}

Ramificação condicional

Um node conditional avalia sua condição e roteia a execução de acordo. O resultado da ramificação seleciona qual edge de saída é seguido, pela correspondência do sourceHandle.

Exemplo: Verificação antifraude

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Transaction Received" },
    { "id": "n2", "type": "executor",    "name": "Get Fraud Score" },
    {
      "id": "n3",
      "type": "conditional",
      "name": "Evaluate Score",
      "data": { "condition": "n2.fraudScore < 70" }
    },
    { "id": "n4", "type": "executor",    "name": "Approve Transaction" },
    { "id": "n5", "type": "executor",    "name": "Reject Transaction" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Score received" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "true",
      "label": "Approved"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "false",
      "label": "Rejected"
    }
  ]
}

Exemplos do mundo real

Verificação antifraude

Uma transação chega, uma pontuação de fraude é obtida, e a execução é roteada para aprovação ou rejeição.

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Transaction Received" },
    { "id": "n2", "type": "executor",    "name": "Get Fraud Score" },
    {
      "id": "n3",
      "type": "conditional",
      "name": "Evaluate Fraud Score",
      "data": { "condition": "n2.fraudScore < 70" }
    },
    { "id": "n4", "type": "executor",    "name": "Approve Transaction" },
    { "id": "n5", "type": "executor",    "name": "Reject and Notify" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Score received" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "true",
      "label": "Low risk"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "false",
      "label": "High risk"
    }
  ]
}

Orquestração de pagamento

Um fluxo linear que valida os dados de pagamento recebidos, roteia para o provider apropriado e envia uma confirmação.

{
  "nodes": [
    { "id": "n1", "type": "trigger",  "name": "Payment Initiated" },
    { "id": "n2", "type": "executor", "name": "Validate Payment Data" },
    { "id": "n3", "type": "executor", "name": "Route to Payment Provider" },
    { "id": "n4", "type": "executor", "name": "Send Confirmation" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Valid" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Payment routed" }
  ]
}

Onboarding KYC

Use um workflow para enviar uma checagem de documentos a um sistema de aprovação externo. O Flowker não tem uma pausa embutida: para uma revisão humana assíncrona, inicie uma execução de workflow posterior e separada quando o seu sistema de aprovação publicar a decisão.

Fluxo de aprovação manual

Uma solicitação é enviada para revisão. Um executor consulta a decisão da revisão no sistema externo. Um node condicional então roteia para o caminho de aprovação ou rejeição. Execuções do Flowker rodam de ponta a ponta — não há etapa de pausa embutida, então uma decisão humana precisa vir de um sistema externo consultado pelo workflow.

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Request Submitted" },
    { "id": "n2", "type": "executor",    "name": "Submit for Review" },
    { "id": "n3", "type": "executor",    "name": "Get Approval Decision" },
    {
      "id": "n4",
      "type": "conditional",
      "name": "Decision Received",
      "data": { "condition": "n3.decision == 'approved'" }
    },
    { "id": "n5", "type": "executor",    "name": "Process Approved Request" },
    { "id": "n6", "type": "executor",    "name": "Notify Rejection" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Submitted" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Decision received" },
    {
      "id": "e4",
      "source": "n4",
      "target": "n5",
      "sourceHandle": "true",
      "label": "Approved"
    },
    {
      "id": "e5",
      "source": "n4",
      "target": "n6",
      "sourceHandle": "false",
      "label": "Rejected"
    }
  ]
}

Boas práticas

Convenções de nomenclatura de nodes

Use nomes descritivos e orientados a ações que comuniquem o que o node faz, e não qual é o seu tipo.

correto: Validate Payment Data, Get Fraud Score, Notify Customer, Get Approval Decision
errado: executor1, conditional node, node3

Bons nomes tornam os workflows legíveis sem precisar abrir a configuração do node. Eles também aparecem nos registros de execução e nos seus rastreamentos, tornando a depuração significativamente mais rápida.

Expressões de condição

As condições de texto livre nos nodes condicionais são avaliadas contra o contexto de execução em tempo de execução. Mantenha-as simples e explícitas:

Use comparações diretas de campos: <nodeId>.status == 'approved'
Use comparações numéricas: <nodeId>.riskScore < 70
Use campos booleanos: <nodeId>.reviewRequired == true
Combine com AND / OR quando necessário: <nodeId>.score < 70 AND <nodeId>.verified == true

Evite expressões complexas que são difíceis de ler ou depurar. Se a lógica não for trivial, dê ao node conditional um nome claro que encapsule a decisão. Uma condição ausente ou que falha ao ser avaliada em tempo de execução faz a execução falhar (FLK-0105 identifica uma expressão condicional inválida). Sempre teste as condições antes de ativar um workflow.

Estratégias de tratamento de erros

Projete workflows para lidar com falhas de forma explícita:

Adicione caminhos de rejeição a partir de nodes conditional para cada ponto de decisão que pode falhar.
Use nodes executor separados para lógica de retry ou providers de fallback.
Nomeie os caminhos de erro de forma clara (por exemplo, Reject and Notify, Fallback to Manual Review) para que os registros de execução sejam autoexplicativos.

Evitando ciclos

O Flowker usa um mecanismo de detecção de ciclos baseado em DFS em tempo de execução. Se um ciclo for detectado durante a execução, o workflow falha com FLK-0508. Ciclos não são detectados em tempo de design, portanto valide a estrutura dos seus edges antes de ativar. Regras para prevenir ciclos:

Os edges devem sempre apontar para frente no fluxo, nunca de volta para um node executado anteriormente.
Revise o grafo visualmente antes de ativar qualquer workflow com ramificações ou caminhos de junção.
Se um retry ou loop for necessário, modele-o como uma invocação de workflow separada, não como um edge de retorno no grafo atual.

Versionamento via clone

Nunca edite um workflow ativo diretamente. Em vez disso:

Clone o workflow (cria um novo draft com todos os nodes e edges copiados).

Faça suas alterações no rascunho.

Valide ou faça a pré-visualização do rascunho. Ative-o antes de executar testes de execução.

Ative a nova versão.

Desative a versão antiga se ela não for mais necessária.

Isso preserva o histórico de execução da versão ativa e oferece um caminho de rollback caso a nova versão apresente problemas.

Referência de erros

Os seguintes códigos de erro são relevantes para o design e a execução de workflows:

Código	Descrição
`FLK-0102`	Transição de status inválida
`FLK-0103`	Workflow não pode ser modificado — não está no status draft
`FLK-0105`	Expressão condicional inválida
`FLK-0113`	Nodes em excesso — o máximo é 100
`FLK-0114`	Edges em excesso — o máximo é 200
`FLK-0506`	Payload de entrada da execução muito grande — o máximo é 1 MB
`FLK-0508`	Ciclo detectado durante a execução do workflow

Visão geral

Guias

Console

Operações

Guia de Design de Workflows

Tipos de nodes

trigger

executor

conditional

action

Edges

Exemplo de edge

Transições de status

Regras

Movendo um workflow inativo de volta para draft

Iterando com segurança usando clone

Limites técnicos

Padrões comuns

Sequencial

Ramificação condicional

Exemplos do mundo real

Verificação antifraude

Orquestração de pagamento

Onboarding KYC

Fluxo de aprovação manual

Boas práticas

Convenções de nomenclatura de nodes

Expressões de condição

Estratégias de tratamento de erros

Evitando ciclos

Versionamento via clone

Referência de erros

​Tipos de nodes

​trigger

​executor

​conditional

​action

​Edges

​Exemplo de edge

​Transições de status

​Regras

​Movendo um workflow inativo de volta para draft

​Iterando com segurança usando clone

​Limites técnicos

​Padrões comuns

​Sequencial

​Ramificação condicional

​Exemplos do mundo real

​Verificação antifraude

​Orquestração de pagamento

​Onboarding KYC

​Fluxo de aprovação manual

​Boas práticas

​Convenções de nomenclatura de nodes

​Expressões de condição

​Estratégias de tratamento de erros

​Evitando ciclos

​Versionamento via clone

​Referência de erros

Tipos de nodes

trigger

executor

conditional

action

Edges

Exemplo de edge

Transições de status

Regras

Movendo um workflow inativo de volta para draft

Iterando com segurança usando clone

Limites técnicos

Padrões comuns

Sequencial

Ramificação condicional

Exemplos do mundo real

Verificação antifraude

Orquestração de pagamento

Onboarding KYC

Fluxo de aprovação manual

Boas práticas

Convenções de nomenclatura de nodes

Expressões de condição

Estratégias de tratamento de erros

Evitando ciclos

Versionamento via clone

Referência de erros