Expressões: $json, $(’Nó’) e datas

Field Note

O relatório diário sai à meia-noite e meia, horário de Brasília. O título diz “Vendas de 21/10”. Só que o relatório é do dia 22, e o dia 21 já tinha saído na noite anterior. Duas planilhas com o mesmo nome, uma delas com os números errados no título. A expressão estava certa: $now formatado como dia e mês. O fuso não estava. O workflow nunca teve fuso configurado, e o n8n fez a conta no horário de Nova York, onde ainda era dia 21. Ninguém escreveu código errado. Alguém deixou de escrever uma configuração.

Conceito

Até aqui, cada campo dos seus nós tinha um valor fixo. Expressão é o que faz o campo usar o dado que chegou. Você coloca o campo em modo de expressão e escreve entre chaves duplas, {{ }}. A doc dá o exemplo de pegar a cidade que veio no corpo de um webhook:

{{ $json.body.city }}
{{ $json["body"]["city"] }}

As duas formas fazem a mesma coisa. A segunda serve quando o nome do campo tem espaço ou caractere estranho. Você também pode arrastar um campo do painel INPUT para o parâmetro, e o n8n escreve a expressão para você.

O que vai dentro das chaves é JavaScript. Dá para usar operador, método de texto, condição curta. Se precisar de várias instruções, a doc manda usar uma função que se executa na hora (IIFE). Se chegou nesse ponto, a doc mesma sugere: transformação de verdade fica melhor num Edit Fields ou num Code node do que espalhada em expressões.

De onde vem o dado. As variáveis que você vai usar quase sempre:

• $json: o json do item que está sendo processado agora. É um atalho para $input.item.json.
• $input.item, $input.first(), $input.last(), $input.all(): a entrada do nó atual, item a item ou em conjunto.
• $("Nome do nó").item: o item daquele nó anterior que gerou o item atual. É o item linking da lição passada trabalhando.
• $("Nome do nó").first(), .last(), .all(): o primeiro, o último ou todos os itens que aquele nó devolveu, sem olhar a ligação.

A diferença entre .item e .first() é a que mais derruba gente. .item segue a corrente e muda a cada item. .first() é sempre o mesmo. Se o nó anterior devolveu uma configuração só (um token, uma data de corte), use .first(). Se devolveu uma linha por cliente e você quer o cliente certo, use .item.

No meu laboratório, o nó open source de consulta de CNPJ aceita expressão no campo de intervalo entre requisições. Em vez de um número fixo, dá para escrever {{ $json.isPriority ? 500 : 2000 }}: item prioritário espera meio segundo, o resto espera dois. Um campo que era configuração vira decisão por item. É essa a virada da lição.

Datas com Luxon. $now é o momento atual e $today é a meia-noite de hoje. Os dois são DateTimes do Luxon, então têm métodos. Os que a referência oficial documenta:

{{ $now.format("dd/LL/yyyy") }}
{{ $today.plus(7, "days") }}
{{ $today.minus(7, "days") }}
{{ $now.startOf("month") }}
{{ $now.setZone("America/Sao_Paulo") }}
{{ $now.toISO() }}

No exemplo oficial, LL é o mês com dois dígitos. Agora o fuso: o Luxon usa o fuso do n8n, que vem da configuração do workflow, da variável GENERIC_TIMEZONE da instância ou do padrão America/New York. Foi assim que a Field Note perdeu um dia.

Quando usar

• Quando o valor do campo depende do item: nome, e-mail, ID, valor.
• Para datas relativas: hoje, daqui a sete dias, início do mês.
• Para referenciar um nó anterior que não é o imediatamente anterior.
• Para um ajuste curto: juntar dois campos, valor padrão quando o campo vem vazio.

Quando não usar

• Lógica com várias etapas ou que você vai repetir em vários campos. Use Edit Fields ou Code.
• Segredo e senha. Isso vai em credencial, não em texto de campo.
• Regra que alguém de negócio precisa ler e mudar. Expressão escondida num parâmetro não é documentação.

Faça agora

O entregável é uma Cola de expressões testadas: cada linha com a expressão, o resultado que você viu e o nó onde testou.

1. Abra o workflow da lição anterior. Antes de tudo, vá no menu de três pontos, Settings, e defina Timezone para o seu fuso.
2. Execute com Execute workflow para os nós terem dados.
3. No Edit Fields, crie um campo nome_formatado em modo de expressão. Arraste um campo do INPUT e veja a expressão aparecer.
4. Crie um campo origem usando $("HTTP Request").item.json com o nome de um campo real da resposta. Depois troque .item por .first() e compare os resultados quando houver mais de um item.
5. Crie três campos de data: hoje formatado, daqui a sete dias e início do mês. Execute e confira se a data bate com o seu relógio.
6. Crie um campo com valor padrão para quando o dado faltar, por exemplo {{ $json.email || "sem email" }}. Teste com um item que não tenha o campo.
7. Quebre de propósito: digite o nome de um nó que não existe e deixe um ponto sobrando no fim de uma expressão. Anote a mensagem que aparece.
8. Copie para a cola só o que funcionou, com o resultado observado.

Armadilhas

• Campo que nem sempre vem. A doc avisa: o erro mais comum de JSON inválido é campo ausente em alguns itens. Use valor padrão.
• Nome de nó errado. $("Nome do nó") precisa do nome exato, com maiúscula e espaço. Expressão copiada de outro workflow costuma apontar para um nó que aqui tem outro nome.
• Nó que ainda não rodou. A expressão não tem de onde ler. Execute até aquele nó, ou confira com $("Nome do nó").isExecuted.
• .item depois de Merge ou Aggregate. Vem o erro “Multiple matching items for expression”. A doc manda usar .first(), .last() ou .all()[índice].
• Referência a outro ramo. O erro “is on another branch” aparece quando o item atual não passou pelo nó citado. Mesma saída: .first() ou um Merge em modo Combine.
• Fuso no padrão. Sem configurar, a conta é feita em Nova York. Defina no workflow ou na instância.

Material para levar

Cola de expressões:

Workflow:
Fuso configurado (Settings > Timezone):

Expressão:
  Onde testei (nó e campo):
  Resultado observado:
  Quando usar:

Expressão:
  Onde testei:
  Resultado observado:
  Quando usar:

(repita para cada uma)

Erros que provoquei e a mensagem que apareceu:
  Nome de nó errado:
  Ponto sobrando:
  Campo ausente:

Regras de bolso:

Expressão vai entre {{ }} com o campo em modo de expressão
$json é o item atual
.item segue a ligação, .first() é sempre o mesmo
Depois de Merge ou Aggregate, prefira .first() ou .all()[i]
$now e $today são Luxon: format, plus, minus, setZone
Configure o fuso antes de confiar em qualquer data
Lógica longa vai para Edit Fields ou Code