Referências e Variáveis

Entenda como referenciar campos no ENSPACE

Ao trabalhar com templates de documento, eventos de campo, condicionais, relatórios, expressões e Spaceflows, você vai encontrar diferentes formas de se referir aos campos. As variações mais comuns são:

• nome_cliente — referência técnica do campo
• data.nome_cliente — referência com prefixo data.
• {{data.nome_cliente}} — variável entre chaves duplas
• %data.nome_cliente% — referência entre porcentagens (em condicionais)

Cada uma tem um propósito diferente, e usá-las no contexto errado é uma das causas mais comuns de erros. Esta página explica cada uma, do mais simples ao mais complexo.

A estrutura dos dados no ENSPACE

O ENSPACE possui três entidades principais com dados referenciáveis: Itens, Tarefas Agendadas e Tarefas Rápidas. Cada uma tem seus próprios campos nativos, mas apenas os itens possuem campos personalizados — o agrupamento data onde ficam os campos que você cria na categoria. As tarefas (agendadas e rápidas) possuem somente campos nativos do sistema.

Para a lista completa de todos os campos disponíveis em cada entidade, consulte Dados por entidade.

Itens

Itens possuem dois grupos de informações:

• Metadados — campos nativos do sistema (id, reference, created_at, etc.). Ficam na raiz.
• Campos personalizados — os campos que você cria na categoria. Ficam dentro de data.

É por isso que a sintaxe para campos personalizados usa data.: {{data.nome_cliente}}. Metadados ficam na raiz: {{reference}}.

Tarefas agendadas

Tarefas agendadas (de fluxos de categoria) possuem apenas campos nativos — não há campos personalizados nem agrupamento data. Todos os campos ficam na raiz e são acessados diretamente.

Tarefas rápidas

Tarefas rápidas possuem apenas campos nativos — não há campos personalizados nem agrupamento data. Todos os campos ficam na raiz. Alguns campos são do tipo objeto e possuem subcampos acessíveis com notação de ponto (ex: {{creator.email}}).

Nível 1 — Referência direta (apontar para um campo)

Existem dois modos de usar campos no ENSPACE:

• Referência — quando o sistema precisa saber qual campo usar para buscar, filtrar, ordenar ou mapear um dado. É uma indicação técnica de caminho, sem gerar texto. Exemplo: data.nome, data.status.
• Variável — quando o sistema precisa inserir o valor de um campo dentro de um texto, documento ou expressão. Exemplo: Olá, {{data.nome}}.

Na maioria das funcionalidades (templates de documento, relatórios, expressões), você não precisa digitar referências manualmente — o sistema oferece botões, dropdowns ou listas que inserem a sintaxe correta. A referência acontece "por trás" da interface.

Existem dois contextos onde você pode digitar referências manualmente: os Eventos de Campo e o campo Valor das Condicionais.

Referências nos Eventos de Campo

Nos eventos, a referência ao campo alvo usa apenas a referência técnica — sem data. e sem {{}}:

Isso acontece porque os eventos já operam dentro do contexto dos campos da categoria. O sistema já sabe que nome_cliente está dentro de data, então o prefixo é desnecessário.

Na prática: independentemente do tipo de ação (Editar, Redefinir, Invalidar ou Recarregar), o campo "Campo" sempre recebe a referência direta:

Compare com a coluna "Valor" da mesma configuração, onde você busca um dado — ali sim as chaves duplas são necessárias:

A coluna Campo aponta. A coluna Valor busca.

Para a documentação completa de Eventos de Campo, consulte Eventos de Campo.

Referências nas Condicionais (sintaxe com %)

Nas condicionais (de formulários, regras de responsabilidade e eventos), ao configurar o campo Valor, você pode comparar o valor de um campo com o valor de outro campo em vez de um valor fixo. Para isso, use a referência do campo entre sinais de porcentagem:

O data. é necessário para campos personalizados. Para metadados, use a referência direta:

Na prática: imagine que você quer verificar se o campo "Usuário Solicitante" tem o mesmo valor que o campo "Usuário Responsável":

Outros exemplos:

Note a diferença: no último exemplo, request_email é um metadado e não leva data.. Nos dois primeiros, data_limite e valor_solicitado são campos personalizados e levam data..

Nível 2 — Variáveis (buscar o valor de um campo)

Como visto no Nível 1, referências apontam para um campo. Variáveis vão além: elas buscam o valor armazenado naquele campo e o inserem no lugar da marcação. É o que acontece quando você quer que o sistema escreva "João da Silva" no lugar de {{data.nome_cliente}}.

Para montar uma variável, você precisa de duas coisas:

1. Chaves duplas {{}} — indicam que o sistema deve buscar o valor, não apenas apontar.
2. O caminho até o campo — data.campo para campos personalizados, ou apenas campo para metadados.

Campos personalizados

Como ficam dentro do agrupamento data, o caminho é:

Metadados do sistema

Como ficam na raiz, não levam data., sendo o caminho somente:

Para a lista completa de metadados de cada entidade, consulte Dados disponíveis por entidade.

Na prática

As variáveis aparecem em diversos contextos da plataforma. Na maioria deles, o sistema oferece botões ou listas que inserem a variável automaticamente — você não precisa digitá-la:

Nos eventos de campo, note que a fonte de dados muda: em vez de data., usa-se form_value. (para valores do formulário), payload (para o campo gatilho) ou item_related.data. (para campos de um item relacionado). Cada fonte tem seu contexto — para mais detalhes, consulte Eventos de Campo.

Nível 3 — Referências sem chaves em contextos de expressão

Em alguns contextos, você referencia campos dentro de uma estrutura que já é uma expressão. Nesses casos, usa data.campo mas sem chaves duplas — as chaves já fazem parte da estrutura ao redor.

Blocos IF/FOR em Templates de Documento

Dentro de blocos condicionais e de repetição, a referência ao campo fica sem chaves próprias:

O data. está presente (porque é um campo personalizado), mas não há {{}} ao redor de data.status — porque ele já está dentro da estrutura {{IF ... }}.

Função sumArray() em Expressões

A função sumArray() espera referências diretas, sem chaves:

O primeiro argumento (data.parcelas) é o caminho até o repetidor — como é um campo personalizado, precisa do prefixo data. para indicar que está dentro do agrupamento de campos da categoria.

O segundo argumento (valor) é o subcampo dentro do repetidor — como o primeiro argumento já levou o sistema até dentro do repetidor, o subcampo é acessado diretamente pela sua referência técnica, sem precisar repetir data.. É a mesma lógica dos eventos de campo: quando o sistema já está dentro do contexto correto, o prefixo é desnecessário.

Nível 4 — Acessando dados de outras origens

Dois contextos do ENSPACE possuem sintaxes próprias para acessar dados que não estão no item ou contexto atual — cada um com seus próprios prefixos.

Eventos de Campo — fontes de dados especiais

Nos eventos de campo, o campo "Valor" pode buscar dados de três fontes diferentes, cada uma com sua sintaxe:

Para a documentação completa das fontes de dados, tipos especiais de campo e exemplos de configuração, consulte Eventos de Campo.

Spaceflow — variáveis entre nós

Ao construir um Spaceflow, cada nó gera suas próprias variáveis de saída. Você não precisa digitar essas referências manualmente — o sistema as insere automaticamente quando você arrasta variáveis no canvas. Esta seção explica o que elas significam quando você as vê.

O formato é {{nodes.ID_DO_NO.campo}}, onde o ID é o identificador único do nó:

A mesma hierarquia se mantém: metadados na raiz (nodes.ID.reference) e campos personalizados dentro de data (nodes.ID.data.campo).

Para a documentação completa do Spaceflow, consulte Spaceflow.

Regra geral

Quando usar {{}}?

Use chaves duplas quando quiser buscar o valor armazenado em um campo. Se você está apenas apontando para um campo (dizendo ao sistema qual campo será afetado), não use chaves.

Quando usar data.?

Use data. quando precisar indicar que o campo é personalizado (criado por você na categoria), diferenciando-o dos metadados do sistema. A exceção é nos eventos de campo, onde o sistema já opera dentro do contexto de data e o prefixo é desnecessário.

Quando usar %?

Use porcentagens quando estiver no campo Valor de uma condicional e quiser comparar com o valor de outro campo em vez de um valor fixo.

Em caso de dúvida sobre a referência técnica de um campo, acesse Configurações > Estrutura > Categorias > Campos e verifique o valor do campo Referência técnica na aba Definição.