Entendendo a Hierarquia de Dados no N8N
No desenvolvimento de workflows no n8n, um dos desafios mais comuns para iniciantes e até para usuários experientes é gerenciar o fluxo de dados entre nós (nodes). A confusão frequente ocorre ao tentar acessar variáveis ou objetos que foram criados em etapas anteriores do fluxo, mas que parecem "desaparecer" quando se tenta referenciá-los em uma etapa posterior. Para resolver isso, é fundamental compreender a distinção clara entre variáveis globais e o escopo local de execução.
Este tutorial técnico explica como essas duas camadas de contexto funcionam, quando utilizar cada uma e como evitar erros comuns de referência. Vamos analisar a estrutura de dados JSON que permeia o n8n, demonstrar comandos práticos para manipulação de variáveis e fornecer exemplos concretos de implementação em um workflow automatizado.
O Conceito de Escopo Local: O Fluxo do Workflow
O escopo local no n8n refere-se aos dados que fluem diretamente de um nó para o seguinte através da conexão principal. Cada execução de um nó recebe uma lista de entradas (input items) e produz uma lista de saídas (output items). Esses dados existem apenas durante a execução daquele nó específico e são passados adiante na forma de objetos JSON.
A principal característica do escopo local é a persistência sequencial. Se você tem um workflow com três nós — Node A, Node B e Node C — os dados processados no Node A estão disponíveis no Node B. No entanto, se o Node B modificar esses dados, o Node C receberá apenas as modificações feitas pelo Node B, não o estado original do Node A (a menos que o Node B tenha preservado explicitamente essas informações).
Para visualizar isso na prática, considere um cenário onde você busca dados de uma API. O nó HTTP Request retorna um JSON. Esse JSON é a "entrada" para o próximo nó. Se esse próximo nó for um código JavaScript (Code Node), ele recebe esse JSON como argumento. Tudo o que acontece dentro desse Code Node afeta apenas o item atual sendo processado.
// Exemplo de estrutura de dados recebida em um Code Node
// O parâmetro 'items' contém todos os itens de entrada do nó anterior
const items = $input.all();
items.forEach((item, index) => {
// Aqui, item.json contém os dados vindos do nó anterior
const email = item.json.email;
// Modificamos o escopo local deste item
item.json.status = 'processado';
// Retornamos o item modificado para o próximo nó
});
return items;É crucial entender que, no escopo local, a variável $json é apenas um atalho para acessar os dados do item atual. Ela não contém informações sobre outros itens processados em paralelo ou em loops anteriores, a menos que você tenha utilizado nós de agregação ou merge específicos.
Variáveis Globais: O Contexto da Execução
Diferentemente do escopo local, as variáveis globais no n8n são armazenadas em um contexto que transcende os dados individuais dos itens. Existem dois tipos principais de contextos globais no n8n: o Workflow Context e o Execution Context.
O Workflow Context persiste entre diferentes execuções do workflow. Isso significa que se você salvar uma variável neste contexto hoje, ela estará disponível na próxima execução do mesmo workflow, horas ou dias depois. É ideal para armazenar configurações persistentes, chaves de API rotativas ou estados de processos longos.
O Execution Context, por outro lado, é específico para uma única execução do workflow. Se você disparar o workflow manualmente duas vezes, cada execução terá seu próprio espaço de memória isolado. Variáveis salvas aqui não sobrevivem ao fim da execução e não são compartilhadas entre execuções simultâneas.
Para manipular variáveis globais, utilizamos o objeto $workflow ou $execution dentro dos nós de código ou expressões. A sintaxe é direta, mas requer atenção para não sobrescrever dados críticos acidentalmente.
// Salvando uma variável no contexto do workflow
$workflow.setValue('chave_secreta', 'valor_protegido');
// Recuperando a variável em um nó posterior
const valorRecuperado = $workflow.getValue('chave_secreta');
// Trabalhando com o contexto de execução
$execution.setData('temp_log', new Date().toISOString());O uso correto dessas variáveis globais permite criar workflows mais robustos, que mantêm estado e podem tomar decisões baseadas em execuções anteriores ou configurações externas dinâmicas.
Diferenças Práticas: Quando Usar Cada Abordagem?
A escolha entre usar dados locais ou variáveis globais depende inteiramente da natureza da informação que você está manipulando. Utilizar a ferramenta errada para o trabalho pode levar a workflows complexos, lentos e difíceis de manter.
1. Use Escopo Local Quando:
- Dados transitórios: Você precisa processar um registro específico (ex: um email, um pedido) e passar o resultado para o próximo passo.
- Mapeamento de dados: Você está transformando a estrutura do JSON, extraindo campos ou calculando valores baseados nos dados atuais do item.
- Performance em lotes: O n8n é otimizado para processar múltiplos itens em paralelo. Manter os dados no fluxo local permite que o motor de execução aproveite o paralelismo nativo.
2. Use Variáveis Globais Quando:
- Persistência de estado: Você precisa lembrar algo sobre o workflow entre execuções (ex: "quantas vezes este erro ocorreu na última semana").
- Dados sensíveis ou estáticos: Chaves de API, tokens de sessão ou configurações que não mudam frequentemente e devem ser acessadas por múltiplos nós sem passar pelo fluxo de dados principal.
- Controle de fluxo condicional complexo: Em alguns casos, salvar um indicador no contexto global pode simplificar a lógica de decisão em ramos divergentes do workflow.
Passo a Passo: Implementando Variáveis Globais em um Workflow
Vamos criar um exemplo prático. Imagine um cenário onde você tem um workflow que processa uma lista de usuários e precisa manter um contador global de quantos usuários foram processados com sucesso durante a execução atual.
Etapa 1: Inicialização do Contexto
No primeiro nó do seu workflow (por exemplo, um nó Trigger ou um Code Node inicial), você deve inicializar a variável global. Isso garante que ela exista antes de ser incrementada.
// Code Node: Inicializador
// Verifica se a variável já existe, se não, inicia com 0
let contador = $execution.getData('contagem_sucesso') || 0;
// Salva no contexto de execução
$execution.setData('contagem_sucesso', contador);
// Retorna o item original para continuar o fluxo normal
return $input.all();Etapa 2: Processamento e Incremento
No nó onde você valida os dados do usuário (por exemplo, um Code Node que verifica se o email é válido), você recupera o contador atual, incrementa e salva de volta.
// Code Node: Processador de Validação
const items = $input.all();
let contador = $execution.getData('contagem_sucesso') || 0;
items.forEach((item) => {
const email = item.json.email;
// Lógica simples de validação
if (email && email.includes('@')) {
item.json.valido = true;
contador++;
} else {
item.json.valido = false;
}
});
// Atualiza o contexto global com o novo valor
$execution.setData('contagem_sucesso', contador);
return items;Etapa 3: Acesso Final
No último nó do workflow, você pode exibir ou enviar um resumo contendo o total de processamentos.
// Code Node: Relatório Final
const total = $execution.getData('contagem_sucesso');
return {
json: {
mensagem: `Processamento concluído. Total de usuários válidos: ${total}`
}
};Neste exemplo, o escopo local cuidou do processamento individual de cada item (validação do email), enquanto a variável global ($execution) manteve o estado agregado (contador total). A separação clara dessas responsabilidades torna o código mais legível e menos propenso a erros.
Erros Comuns e Boas Práticas
Ao trabalhar com n8n, especialmente ao misturar escopo local e global, certos erros são frequentes. Abaixo, listamos as armadilhas mais comuns e como evitá-las.
1. Confundindo $json com Variáveis Globais
Muitos desenvolvedores tentam acessar variáveis globais usando a sintaxe $json.nome_variavel. Isso está incorreto. O $json refere-se estritamente aos dados do item atual no fluxo local. Para acessar o contexto global, você deve usar as funções específicas como $workflow.getValue() ou $execution.getData().
2. Sobrescrita Acidental em Loops
Se você estiver processando um loop de itens e tentar salvar uma variável global dentro do loop sem cuidado, pode haver conflitos se o workflow for executado em paralelo ou se houver múltiplos ramos ativos. Sempre verifique o valor existente antes de sobrescrever.
// INCORRETO: Pode perder dados anteriores
$execution.setData('contador', 1);
// CORRETO: Incrementa o valor atual
let atual = $execution.getData('contador') || 0;
$execution.setData('contador', atual + 1);3. Uso Excessivo de Variáveis Globais para Dados Locais
Não use variáveis globais para passar dados simples entre nós consecutivos. Se o Node A precisa enviar um dado ao Node B, coloque esse dado no JSON de saída do Node A. O uso desnecessário do contexto global adiciona overhead de memória e complexidade desnecessária ao seu workflow.
4. Persistência Indesejada
Lembre-se que o Workflow Context é persistente. Se você salvar dados temporários de depuração no $workflow, eles permanecerão lá até que sejam explicitamente removidos ou o workflow seja editado. Use o Execution Context para dados que são relevantes apenas durante aquela execução específica.
Depuração de Variáveis e Escopos
Uma das melhores ferramentas para entender o que está acontecendo com seus dados é o nó Debug. Ele permite visualizar tanto os itens locais quanto as variáveis globais configuradas.
- Conecte um nó Debug após o ponto onde você espera que uma variável global seja definida.
- Abra a aba "Debug" na interface do n8n.
- Execute o workflow.
- No painel de debug, você verá as informações detalhadas. Procure pela seção que exibe os dados do item (escopo local) e verifique se há indicações de variáveis de contexto.
Além disso, ao usar Code Nodes, você pode adicionar logs temporários para verificar o estado das variáveis:
// Debug no terminal/logs do n8n
console.log('Valor atual do contador:', $execution.getData('contagem_sucesso'));Isso é especialmente útil em workflows complexos com múltiplos ramos condicionais, onde o fluxo de dados pode não ser imediatamente óbvio.
Conclusão: Dominando a Gestão de Estado no n8n
A compreensão profunda da diferença entre variáveis globais e escopo local é um marco na evolução de um usuário do n8n de iniciante para avançado. O escopo local é o canal principal de comunicação entre nós, otimizado para throughput e transformação de dados item a item. Já as variáveis globais servem como uma camada de memória persistente ou transiente que permite ao workflow manter estado e tomar decisões contextuais.
Ao seguir as práticas recomendadas — utilizando o escopo local para fluxo de dados padrão e reservando variáveis globais para persistência, configuração e agregação de estado — você criará automações mais eficientes, escaláveis e fáceis de manter. Lembre-se sempre de testar seus workflows em modo de execução única e verificar os logs de debug para validar o comportamento das suas variáveis.
Com este conhecimento, você está preparado para construir workflows no n8n que não apenas automatizam tarefas, mas também gerenciam inteligência de estado de forma elegante e eficiente. Continue explorando as capacidades do n8n, experimente diferentes combinações de nós e utilize o contexto global estrategicamente para resolver problemas complexos de integração.