Execução de Workflows

A execução de workflows no Triglit é orquestrada pela engine, que gerencia o fluxo de dados, pausas, retomadas e tratamento de erros.

O que é uma Execução (Run)?

Uma run é uma instância de execução de um workflow para uma entidade específica (entityId). Cada run:

Tem um ID único
Está associada a um workflow version publicado
Processa uma entidade específica (pedido, usuário, etc.)
Mantém um contexto de execução compartilhado
Pode ser pausada e retomada

Estrutura de uma Run

{
  "id": "run_123",
  "tenantId": "tenant_abc",
  "subTenantId": "sub_xyz",
  "workflowVersionId": "version_456",
  "entityId": "order_789",
  "status": "running",
  "context": {
    "data": {
      "input": { "orderId": "order_789" },
      "node-1": { "result": "validated" }
    },
    "metadata": {
      "runId": "run_123",
      "entityId": "order_789",
      "executedNodes": ["node-1"]
    }
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:05:00Z"
}

Status de Execução

Estados Possíveis

pending: Aguardando início
running: Em execução
paused: Pausada (aguardando retomada)
completed: Concluída com sucesso
failed: Falhou (após retries)

Fluxo de Execução

Trigger → Run Criado → Nodes Executam → Conclusão
              ↓
         (Pausa opcional)
              ↓
         Retomada → Continua → Conclusão

1. Início da Execução

Um trigger inicia a execução:

{
  "triggerId": "trigger_123",
  "workflowVersionId": "version_456",
  "entityId": "order_789",
  "payload": {
    "orderId": "order_789",
    "amount": 100.00
  }
}

2. Criação da Run

O sistema cria uma run automaticamente:

{
  "id": "run_123",
  "status": "pending",
  "context": {
    "data": {
      "input": { "orderId": "order_789", "amount": 100.00 }
    }
  }
}

3. Execução de Nodes

Nodes são executados em ordem topológica:

node-1 (trigger) → node-2 (validate) → node-3 (process)

Paralelismo:

Nodes sem dependências executam em paralelo
Nodes dependentes aguardam conclusão dos anteriores

4. Contexto Compartilhado

Dados fluem entre nodes via contexto:

{
  "data": {
    "input": { "orderId": "order_789" },
    "node-validate": { "valid": true },
    "node-process": { "processed": true, "result": "success" }
  }
}

Pausas e Retomadas

Nodes Pausáveis

Alguns nodes podem pausar a execução:

input: Aguarda entrada do usuário
wait: Aguarda tempo determinado
waitForEvent: Aguarda evento externo

Quando uma Run Pausa

{
  "id": "run_123",
  "status": "paused",
  "pausedAtNode": "node-input-1",
  "resumeToken": "resume_abc123",
  "context": {
    "data": {
      "input": { "orderId": "order_789" }
    }
  }
}

Retomando uma Run

POST /v1/gateway/runs/{runId}/resume
{
  "resumeToken": "resume_abc123",
  "resumeData": {
    "input": "dados do usuário"
  }
}

Tratamento de Erros

Retry Automático

Nodes podem ter retry configurado:

{
  "type": "custom",
  "config": {
    "retry": {
      "maxAttempts": 3,
      "backoff": "exponential",
      "initialDelay": 1000
    }
  }
}

Dead Letter Queue (DLQ)

Falhas persistentes vão para DLQ:

{
  "runId": "run_123",
  "status": "failed",
  "error": {
    "message": "Node failed after 3 retries",
    "nodeId": "node-custom-1",
    "lastError": "Connection timeout"
  },
  "dlq": true
}

Ordem de Execução

Topologia

Nodes são executados baseado nas edges (conexões):

     node-1
    /      \
node-2    node-3
    \      /
     node-4

Ordem:

node-1 executa primeiro
node-2 e node-3 executam em paralelo (após node-1)
node-4 executa após node-2 e node-3

Trigger Nodes

Se um workflow foi iniciado por um trigger, a execução começa nos nodes conectados ao trigger:

{
  "nodes": [
    {
      "id": "trigger-webhook",
      "type": "trigger_webhook",
      "config": { "_triggerId": "trigger_123" }
    },
    {
      "id": "node-process",
      "type": "transform"
    }
  ],
  "edges": [
    { "source": "trigger-webhook", "target": "node-process" }
  ]
}

Timeout

Timeout por Run

Cada run tem um timeout máximo (padrão: 30 minutos):

{
  "runId": "run_123",
  "timeout": 1800000,  // 30 minutos em ms
  "startedAt": "2024-01-15T10:00:00Z"
}

Timeout por Node

Nodes individuais também podem ter timeout:

{
  "type": "custom",
  "config": {
    "timeout": 300000  // 5 minutos
  }
}

Observabilidade

Logs

Cada execução gera logs estruturados:

{
  "level": "info",
  "runId": "run_123",
  "nodeId": "node-1",
  "message": "Node executed successfully",
  "duration": 150,
  "timestamp": "2024-01-15T10:00:00Z"
}

Métricas

Métricas são coletadas automaticamente:

Tempo de execução
Taxa de sucesso/falha
Nodes executados
Pausas e retomadas

Boas Práticas

Idempotência

Torne workflows idempotentes para permitir retries seguros.

Timeouts Apropriados

Configure timeouts realistas baseados na complexidade do workflow.

Tratamento de Erros

Sempre inclua tratamento de erro e use retries quando apropriado.

Monitoramento

Monitore execuções e configure alertas para falhas.

Contexto Limpo

Mantenha o contexto organizado e evite dados desnecessários.

Limitações

Timeout máximo: 30 minutos por run (configurável)
Nodes por run: 100 nodes (configurável)
Tamanho do contexto: 1MB por run
Retries: Máximo de 3 por node (configurável)

Para workflows longos, considere dividir em múltiplos workflows menores e conectá-los via webhooks.

​O que é uma Execução (Run)?

​Estrutura de uma Run

​Status de Execução

​Estados Possíveis

​Fluxo de Execução

​1. Início da Execução

​2. Criação da Run

​3. Execução de Nodes

​4. Contexto Compartilhado

​Pausas e Retomadas

​Nodes Pausáveis

​Quando uma Run Pausa

​Retomando uma Run

​Tratamento de Erros

​Retry Automático

​Dead Letter Queue (DLQ)

​Ordem de Execução

​Topologia

​Trigger Nodes

​Timeout

​Timeout por Run

​Timeout por Node

​Observabilidade

​Logs

​Métricas

​Boas Práticas

​Limitações

O que é uma Execução (Run)?

Estrutura de uma Run

Status de Execução

Estados Possíveis

Fluxo de Execução

1. Início da Execução

2. Criação da Run

3. Execução de Nodes

4. Contexto Compartilhado

Pausas e Retomadas

Nodes Pausáveis

Quando uma Run Pausa

Retomando uma Run

Tratamento de Erros

Retry Automático

Dead Letter Queue (DLQ)

Ordem de Execução

Topologia

Trigger Nodes

Timeout

Timeout por Run

Timeout por Node

Observabilidade

Logs

Métricas

Boas Práticas

Limitações