Skip to main content
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:
  1. node-1 executa primeiro
  2. node-2 e node-3 executam em paralelo (após node-1)
  3. 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

Torne workflows idempotentes para permitir retries seguros.
Configure timeouts realistas baseados na complexidade do workflow.
Sempre inclua tratamento de erro e use retries quando apropriado.
Monitore execuções e configure alertas para falhas.
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.