Workflows
Um workflow é a definição de um processo de negócio — a sequência de passos que o Flowker segue para concluir uma operação. Todo workflow possui um ciclo de vida com três estados possíveis:
| Status | Descrição |
|---|---|
draft | Criado e editável. Ainda não pode ser executado. |
active | Pronto para execução. A estrutura está bloqueada. |
inactive | Desativado. Novas execuções não são aceitas. |
Nodes e edges
Os nodes são os passos individuais de um workflow — o que em termos de negócio você chamaria de tarefas. Cada node é uma unidade de trabalho: receber um evento, chamar um serviço, avaliar uma condição ou executar uma ação. O Flowker suporta quatro tipos de node:
| Tipo | Propósito | Quando usar |
|---|---|---|
trigger | Ponto de entrada do workflow | Sempre o primeiro node. Inicia a execução quando um evento ocorre. |
executor | Chama um serviço externo via um executor configurado | Quando você precisa chamar uma API ou integração externa. |
conditional | Bifurca a execução com base em condições | Quando o próximo passo depende do resultado do anterior. |
action | Executa uma ação integrada (log, transform, etc.) | Para operações nativas que não requerem chamadas externas. |
Catálogo
O catálogo é o registro somente leitura de todos os providers, executors e triggers integrados disponíveis no Flowker. Você não pode criar ou modificar entradas do catálogo — apenas descobri-las. Antes de configurar qualquer integração, explore o catálogo para ver o que está disponível:
- Os executors são as capacidades específicas que você pode invocar em um node (ex: requisições HTTP, transformações de dados).
- Os triggers definem os tipos de eventos que podem iniciar um workflow (ex: webhooks).
- Listar executors do catálogo e Listar triggers do catálogo para descobrir tipos de executor e trigger.
- Listar providers do catálogo (
GET /v1/catalog/providers) para listar todos os providers disponíveis. - Consultar provider do catálogo (
GET /v1/catalog/providers/{id}) para obter detalhes de um provider específico. - Listar executors por provider (
GET /v1/catalog/providers/{id}/executors) para listar os executors disponíveis para um provider específico.
Configurações
Antes de usar um executor em um workflow, você precisa configurá-lo. Uma configuração de executor define como o Flowker se conecta a um serviço externo — incluindo a URL base, as credenciais de autenticação e os endpoints HTTP específicos a chamar. As configurações de executor passam por um ciclo de vida:
| Status | Descrição |
|---|---|
unconfigured | Criada mas ainda não configurada com detalhes de conexão. |
configured | Detalhes de conexão fornecidos, pronta para testar. |
tested | Teste de conectividade bem-sucedido. |
active | Pronta para ser usada em execuções de workflows. |
disabled | Temporariamente fora de serviço. |
Configurações de provider
O Flowker usa um modelo de três camadas para integrações externas:
| Camada | O que é | Natureza |
|---|---|---|
| Provider | Um tipo de serviço externo (ex: Midaz, Tracer). | Estático — definido no catálogo. |
| Configuração de Provider | Uma instância configurada de um provider com credenciais e URL base. | Dinâmica — você cria e gerencia. |
| Configuração de Executor | Uma operação específica em um provider, com endpoints e mapeamentos de campos. | Dinâmica — referencia uma configuração de provider. |
active (em uso) e disabled (temporariamente offline). Você pode testar a conectividade a qualquer momento para verificar se a conexão está funcionando.
Use os endpoints de Configurações de provider para criar, gerenciar e testar suas conexões com providers.
Templates
Templates de workflow são padrões pré-construídos disponíveis no catálogo. Em vez de definir um workflow do zero, você pode selecionar um template, preencher seus parâmetros e criar um workflow pronto para uso em segundos. Cada template possui um schema de parâmetros que define quais entradas ele espera (ex: qual configuração de provider usar, valores de limiar). Quando você consulta um template, o schema é dinamicamente enriquecido — campos que referenciam configurações de provider são populados com suas configurações ativas, para que você possa escolher de uma lista em vez de inserir UUIDs manualmente. Para usar um template:
- Navegue pelos templates disponíveis no catálogo.
- Consulte o detalhe do template para ver seu schema de parâmetros.
- Opcionalmente valide seus parâmetros antes de criar.
- Crie um workflow a partir do template.
draft, para que você possa revisá-lo e ajustá-lo antes de ativar.
Execuções
Uma execução é uma instância em tempo de execução de um workflow. Cada vez que você dispara um workflow, o Flowker cria uma nova execução e processa seus nodes em ordem. Cada execução registra:
executionId— Identificador único desta execução.status— Estado atual:pending,running,completedoufailed.stepResults— A saída de cada node executado, em ordem.finalOutput— O resultado agregado de toda a execução.
O endpoint principal de status (
GET /v1/executions/{id}) retorna executionId, workflowId, status, currentStepNumber, totalSteps, startedAt, completedAt e errorMessage. Os campos stepResults e finalOutput só estão disponíveis pelo endpoint dedicado de resultados (GET /v1/executions/{id}/results).Idempotência
Toda requisição de execução requer o header
Idempotency-Key. É um UUID que você gera e envia com cada requisição para identificá-la de forma única.
Se o Flowker receber uma segunda requisição com o mesmo Idempotency-Key, ele retorna a resposta original em vez de criar uma nova execução. Isso torna as retentativas seguras — falhas de rede e timeouts não resultarão em execuções duplicadas.
Dashboard
A API de Dashboard fornece resumos agregados dos seus workflows e execuções — útil para construir dashboards operacionais e ferramentas de monitoramento. Use-a sempre que precisar de uma visão de alto nível da saúde do sistema sem consultar execuções individuais.
- Resumo de workflows retorna totais e detalhamentos por status (draft, active, inactive).
- Resumo de execuções retorna totais e detalhamentos por status, com filtros opcionais de intervalo de tempo e status.
GET /v1/dashboards/executions:
- Monitorar a saúde das execuções — acompanhe as taxas de conclusão e falha ao longo do tempo para identificar degradações precocemente.
- Construir páginas de status — exiba métricas de throughput e sucesso dos workflows em dashboards internos ou voltados ao cliente.
- Alertar sobre picos de taxa de falha — compare
failed / totalcom um limiar para disparar alertas antes que problemas se propaguem.
Auditoria e conformidade
O Flowker registra automaticamente uma trilha de auditoria imutável para cada ação significativa — criação de workflows, mudanças de status, inícios e conclusões de execuções, chamadas a executors e alterações de configuração. Você não precisa habilitar ou configurar nada; o registro de auditoria acontece internamente. Propriedades-chave do sistema de auditoria:
- Imutável — os registros de auditoria são somente-adição e não podem ser modificados ou excluídos.
- Integridade por cadeia de hash — cada entrada inclui um hash criptográfico que a vincula à entrada anterior, tornando adulterações detectáveis.
- Busca flexível — use Buscar eventos de auditoria para consultar eventos por tipo, ação, resultado, recurso ou intervalo de datas.
- Verificação da cadeia — use Verificar cadeia de hash para confirmar que a trilha de auditoria não sofreu adulteração.
Como tudo se encaixa
Os conceitos do Flowker se constroem uns sobre os outros em uma sequência clara:
- Explore o catálogo para descobrir providers, executors, triggers e templates disponíveis.
- Configure providers para conectar o Flowker a instâncias ativas de serviços externos.
- Configure executors para definir as operações e endpoints específicos que seu workflow precisa.
- Defina workflows — do zero ou a partir de um template — referenciando suas configurações de executor.
- Execute workflows para rodar seu processo de negócio e obter resultados.
- Monitore e audite — use o dashboard para resumos operacionais e a API de auditoria para conformidade.