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

# Workflows

> Entenda o conceito de workflows no Triglit e como criar automações complexas

Um **workflow** no Triglit é um grafo direcionado acíclico (DAG) composto por **nodes** (nós) e **edges** (arestas) que define uma automação executável.

## O que é um Workflow?

Um workflow representa um processo automatizado que pode ser executado múltiplas vezes. Cada execução é chamada de **run** e é isolada por **entityId** (identificador da entidade sendo processada).

### Características Principais

* **Versionamento**: Workflows têm versões imutáveis que podem ser publicadas
* **Isolamento por Tenant**: Cada workflow pertence a um tenant específico (identificado pela chave de API)
* **Sub-Tenants**: Workflows podem ser associados a sub-tenants para segmentação adicional
* **Execução Assíncrona**: Workflows são executados de forma assíncrona via fila
* **Pausas e Retomadas**: Suporta pausas controladas e retomadas com dados externos

## Estrutura de um Workflow

```json theme={null}
{
  "id": "workflow_123",
  "tenantId": "tenant_abc",
  "name": "Processar Pedido",
  "description": "Workflow para processar pedidos de clientes",
  "isActive": true,
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z"
}
```

## Versões de Workflow

Cada workflow pode ter múltiplas **versões**. Uma versão define a estrutura executável do workflow:

* **Nodes**: Unidades de ação dentro do workflow
* **Edges**: Conexões entre nodes que definem o fluxo
* **Imutável**: Uma vez criada, uma versão não pode ser modificada
* **Publicação**: Apenas versões publicadas podem ser executadas

### Exemplo de Versão

```json theme={null}
{
  "id": "version_456",
  "workflowId": "workflow_123",
  "nodes": [
    {
      "id": "node-1",
      "type": "trigger_webhook",
      "config": {
        "path": "/pedido"
      }
    },
    {
      "id": "node-2",
      "type": "transform",
      "config": {
        "transformType": "expression",
        "expression": "input.total * 1.1"
      }
    }
  ],
  "edges": [
    {
      "source": "node-1",
      "target": "node-2"
    }
  ],
  "isPublished": false
}
```

## Ciclo de Vida de um Workflow

<Steps>
  <Step title="Criação">
    Um workflow é criado via API com nome e descrição básicos.
  </Step>

  <Step title="Desenvolvimento">
    Versões são criadas e testadas com diferentes configurações de nodes e edges.
  </Step>

  <Step title="Publicação">
    Uma versão é publicada, tornando-a disponível para execução.
  </Step>

  <Step title="Execução">
    Triggers iniciam execuções (runs) do workflow publicado.
  </Step>

  <Step title="Manutenção">
    Novas versões podem ser criadas para melhorias ou correções.
  </Step>
</Steps>

## Execução de Workflows

### Runs

Cada execução de um workflow é chamada de **run** e possui:

* **ID único**: Identificador da execução
* **Entity ID**: Identificador da entidade sendo processada
* **Contexto**: Dados compartilhados entre nodes
* **Status**: `pending`, `running`, `paused`, `completed`, `failed`
* **Resume Token**: Token para retomar execuções pausadas

### Fluxo de Execução

```
Trigger → Workflow Version → Run → Nodes Execution → Completion
```

1. **Trigger ativa**: Um trigger (webhook, schedule) inicia o workflow
2. **Run criado**: Uma nova execução é criada para o `entityId`
3. **Nodes executam**: Nodes são executados em ordem topológica
4. **Contexto compartilhado**: Dados fluem entre nodes via contexto
5. **Pausas**: Nodes pausáveis (input, wait) param a execução
6. **Retomada**: Execução pode ser retomada com dados externos
7. **Conclusão**: Workflow completa ou falha

## Tipos de Nodes

### Built-in Nodes

O Triglit oferece vários nodes built-in:

* **`input`**: Aguarda entrada do usuário ou sistema
* **`wait`**: Pausa por tempo determinado
* **`condition`**: Avalia condições e roteia o fluxo
* **`transform`**: Transforma dados usando expressões
* **`trigger_*`**: Nodes de trigger (webhook, schedule, etc.)

### Custom Nodes

Você pode criar nodes personalizados que são executados em seus próprios servidores via webhooks.

## Isolamento por Tenant

Cada workflow pertence a um **tenant** específico (seu cliente no Triglit):

* ✅ O tenant é identificado automaticamente pela chave de API utilizada
* ✅ Isolamento completo de dados e configurações
* ✅ Nodes customizados privados por tenant
* ✅ Triggers namespaced por tenant

## Sub-Tenants

Workflows podem ser associados a **sub-tenants** para oferecer multi-tenancy aos seus próprios clientes:

* **Segmentação por cliente final**: Cada cliente do seu cliente pode ser um sub-tenant
* **Organização por departamento**: Separe workflows por departamento dentro do mesmo tenant
* **Isolamento completo**: Dados, execuções e métricas isoladas por sub-tenant
* **Métricas e auditoria separadas**: Acompanhe métricas e logs por cliente final

<Card title="Saiba Mais sobre Sub-Tenants" icon="book" href="/concepts/sub-tenants">
  Entenda como usar sub-tenants para oferecer multi-tenancy aos seus clientes
</Card>

## Exemplo Prático

Vamos criar um workflow que processa pedidos:

<CodeGroup>
  ```bash Criar Workflow theme={null}
  curl -X POST "https://api.triglit.com/v1/gateway/workflows" \
    -H "X-API-Key: sk_sua_chave" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Processar Pedido",
      "description": "Valida e processa pedidos de clientes"
    }'
  ```

  ```bash Criar Versão theme={null}
  curl -X POST "https://api.triglit.com/v1/gateway/workflow-versions" \
    -H "X-API-Key: sk_sua_chave" \
    -H "Content-Type: application/json" \
    -d '{
      "workflowId": "workflow_123",
      "nodes": [
        {
          "id": "validate",
          "type": "condition",
          "config": {
            "condition": "input.amount > 0",
            "trueBranch": "process",
            "falseBranch": "reject"
          }
        },
        {
          "id": "process",
          "type": "transform",
          "config": {
            "transformType": "expression",
            "expression": "{ ...input, status: \"processed\" }"
          }
        }
      ],
      "edges": [
        { "source": "validate", "target": "process" }
      ]
    }'
  ```
</CodeGroup>

## Boas Práticas

<AccordionGroup>
  <Accordion title="Nomenclatura Clara">
    Use nomes descritivos para workflows e nodes. Ex: "Processar Pagamento" em vez de "Workflow 1".
  </Accordion>

  <Accordion title="Versionamento">
    Crie novas versões para mudanças significativas. Mantenha versões antigas para rollback.
  </Accordion>

  <Accordion title="Testes">
    Teste workflows em ambiente de desenvolvimento antes de publicar.
  </Accordion>

  <Accordion title="Documentação">
    Use descrições claras para explicar o propósito de cada workflow e node.
  </Accordion>

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

## Limitações

* **Tamanho máximo**: 100 nodes por workflow
* **Profundidade máxima**: 20 níveis de aninhamento
* **Timeout**: 30 minutos por execução (configurável)
* **Rate limit**: Baseado no seu plano

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