> ## Documentation Index
> Fetch the complete documentation index at: https://docs.triglit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Execução de Workflows

> Entenda como workflows são executados no Triglit

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

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

### Retomando uma Run

```bash theme={null}
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:

```json theme={null}
{
  "type": "custom",
  "config": {
    "retry": {
      "maxAttempts": 3,
      "backoff": "exponential",
      "initialDelay": 1000
    }
  }
}
```

### Dead Letter Queue (DLQ)

Falhas persistentes vão para DLQ:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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):

```json theme={null}
{
  "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:

```json theme={null}
{
  "type": "custom",
  "config": {
    "timeout": 300000  // 5 minutos
  }
}
```

## Observabilidade

### Logs

Cada execução gera logs estruturados:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Idempotência">
    Torne workflows idempotentes para permitir retries seguros.
  </Accordion>

  <Accordion title="Timeouts Apropriados">
    Configure timeouts realistas baseados na complexidade do workflow.
  </Accordion>

  <Accordion title="Tratamento de Erros">
    Sempre inclua tratamento de erro e use retries quando apropriado.
  </Accordion>

  <Accordion title="Monitoramento">
    Monitore execuções e configure alertas para falhas.
  </Accordion>

  <Accordion title="Contexto Limpo">
    Mantenha o contexto organizado e evite dados desnecessários.
  </Accordion>
</AccordionGroup>

## 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)

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