Expressões
Antes de utilizar expressões, é necessário entender como funcionam as variáveis e a formatação de dados. Consulte a documentação de Variáveis e Formatação antes de continuar.
Crie cálculos, aplique lógica e transforme dados dinamicamente
As expressões do ENSPACE permitem realizar cálculos, aplicar regras condicionais, manipular datas e combinar dados dinamicamente dentro da plataforma.
Elas podem ser utilizadas em diversos contextos, como:
- Campos virtuais
- Relatórios
- Templates de documento
- Automação de fluxos
- Condicionais e regras
Sempre que um campo aceita lógica ou cálculo, você pode utilizar expressões.
Quando usar expressões
Use expressões sempre que precisar:
- Fazer cálculos
- Aplicar regras condicionais
- Trabalhar com datas
- Agregar listas
- Combinar valores dinamicamente
Como funcionam as expressões
As expressões do ENSPACE são baseadas em três funções principais:
math()— cálculos matemáticos, comparações, lógica e manipulação de textodayjs()— manipulação e cálculo com datassumArray()— agregação de valores em listas (repetidores)
Em qualquer função, você pode utilizar variáveis para acessar dados dos itens.
Expressões matemáticas
O ENSPACE suporta duas formas equivalentes para escrever operações matemáticas.
Para escrever esses cálculos dentro do sistema, utilizamos a função math(), que interpreta e executa a expressão.
Forma recomendada — operadores diretos
Nesta forma, você escreve os cálculos de maneira direta, utilizando os operadores matemáticos tradicionais (+, -, *, /), como em uma calculadora.
É a forma mais simples e fácil de ler, sendo a recomendada para a maioria dos casos.
math({{data.valor_a}} + {{data.valor_b}})
Nesse exemplo:
{{data.valor_a}}e{{data.valor_b}}são valores numéricos- o operador
+realiza a soma entre eles - o resultado final é retornado pela função
math()
Operadores disponíveis:
| Operador | Operação |
|---|---|
+ | Soma |
- | Subtração |
* | Multiplicação |
/ | Divisão |
Exemplos:
- Soma:
math({{data.a}} + {{data.b}})→ soma dois valores - Subtração:
math({{data.total}} - {{data.desconto}})→ subtrai o desconto do total - Multiplicação:
math({{data.preco}} * {{data.quantidade}})→ calcula o total com base em preço e quantidade - Média:
math(({{data.n1}} + {{data.n2}} + {{data.n3}}) / 3)→ soma os valores e divide por 3
Forma alternativa — funções nomeadas
Nesta forma, você escreve os cálculos utilizando funções com nomes descritivos como sum, subtract, multiply e divide, em vez de operadores.
Ela segue a mesma lógica da forma anterior, mas organiza as operações como chamadas de função.
math(sum({{data.valor_a}}, {{data.valor_b}}))
Nesse exemplo:
{{data.valor_a}}e{{data.valor_b}}são valores numéricos- a função
sum()realiza a soma entre eles - o resultado final é retornado pela função
math()
Funções disponíveis:
| Função | Equivalente |
|---|---|
sum(a, b) | a + b |
subtract(a, b) | a - b |
multiply(a, b) | a * b |
divide(a, b) | a / b |
Exemplos:
- Soma:
math(sum({{data.a}}, {{data.b}}))→ soma dois valores - Subtração:
math(subtract({{data.total}}, {{data.desconto}}))→ subtrai o desconto do total - Multiplicação:
math(multiply({{data.preco}}, {{data.quantidade}}))→ calcula o total com base em preço e quantidade - Média:
math(divide(sum({{data.a}}, {{data.b}}), 2))→ soma os valores e divide por 2
Expressões matemáticas com listas
A função sumArray() é usada para somar valores dentro de listas (como repetidores), sendo útil para totais de itens, parcelas ou registros relacionados.
| Situação | Expressão | Resultado |
|---|---|---|
| Somar valores de uma lista | sumArray(data.parcelas, valor) | Retorna a soma de todos os valores do campo valor dentro da lista data.parcelas |
| Somar itens de um pedido | sumArray(data.itens, preco) | Retorna o total dos preços de todos os itens |
| Somar quantidades | sumArray(data.produtos, quantidade) | Retorna a soma das quantidades dos produtos |
Expressões textuais
Você pode combinar textos e valores de campos em uma única saída. Esse processo é chamado de concatenação.
Considere dois campos:
{{data.nome}}→ "João"{{data.sobrenome}}→ "Silva"
| Situação | Expressão | Resultado |
|---|---|---|
| Com espaço entre nome e sobrenome | {{data.nome}} {{data.sobrenome}} | "João Silva" |
| Sem espaço entre os valores | {{data.nome}}{{data.sobrenome}} | "JoãoSilva" |
| Com texto fixo | Cliente: {{data.nome}} | "Cliente: João" |
Comparações e lógica
Comparações
As comparações permitem verificar condições entre valores e retornam true (verdadeiro) ou false (falso).
| Situação | Expressão | Resultado |
|---|---|---|
| Valor maior que 1000 | math({{data.valor}} > 1000) | true se o valor for maior que 1000, false caso contrário |
| Status igual a "aprovado" | math({{data.status}} == 'aprovado') | true se o status for "aprovado", false caso contrário |
| Status diferente de "cancelado" | math({{data.status}} != 'cancelado') | true se o status for diferente de "cancelado", false caso contrário |
| Valor menor que 1000 | math({{data.valor}} < 1000) | true se o valor for menor que 1000, false caso contrário |
Operadores lógicos
Os operadores lógicos permitem combinar múltiplas condições em uma única expressão.
| Situação | Expressão | Resultado |
|---|---|---|
Ambas as condições precisam ser verdadeiras (and) | math({{data.aprovado}} == true and {{data.pago}} == true) | true apenas se ambas forem verdadeiras, false caso contrário |
Pelo menos uma condição deve ser verdadeira (or) | math({{data.aprovado}} == true or {{data.pago}} == true) | true se uma ou ambas forem verdadeiras, false se nenhuma for |
Negar uma condição (not) | math(not {{data.aprovado}}) | true se o valor for false, false se o valor for true |
Condicionais
As condicionais permitem retornar valores diferentes com base em uma condição (formato “se / então / senão”).
| Situação | Expressão | Resultado |
|---|---|---|
| Classificar valor como alto ou baixo | math({{data.valor}} > 10000 ? 'Alto' : 'Baixo') | 'Alto' se o valor for maior que 10000, 'Baixo' caso contrário |
| Aplicar desconto | math({{data.valor}} > 100 ? {{data.valor}} * 0.9 : {{data.valor}}) | Aplica 10% de desconto se o valor for maior que 100. Senão mantém o valor original |
| Verificar status aprovado | math({{data.status}} == 'aprovado' ? 'OK' : 'Pendente') | 'OK' se o status for "aprovado", 'Pendente' caso contrário |
| Verificar prazo cumprido | math({{data.data_conclusao}} <= {{data.data_limite}} ? 'No prazo' : 'Atrasado') | 'No prazo' se concluído dentro do limite, 'Atrasado' se passou da data |
| Retornar valor padrão | math({{data.valor}} ? {{data.valor}} : 0) | Retorna o valor se existir; Retorna 0 se estiver vazio ou nulo |
Coalescência nula
A coalescência nula permite definir um valor padrão caso o primeiro valor seja null (vazio).
| Situação | Expressão | Resultado |
|---|---|---|
| Usar apelido ou nome | math({{data.apelido}} ?? {{data.nome}}) | Retorna apelido se existirCaso contrário, retorna nome |
| Usar valor ou padrão numérico | math({{data.valor}} ?? 0) | Retorna o valor se existirCaso contrário, retorna 0 |
| Usar e-mail secundário ou principal | math({{data.email_secundario}} ?? {{data.email_principal}}) | Retorna o e-mail secundário se existirCaso contrário, retorna o principal |
| Definir texto padrão | math({{data.descricao}} ?? 'Não informado') | Retorna a descrição se existirCaso contrário, retorna "Não informado" |
| Prioridade entre múltiplos campos | math({{data.apelido}} ?? {{data.nome}} ?? 'Cliente') | Retorna o primeiro valor disponível na sequênciaEx: apelido → nome → "Cliente" |
Expressões com data
A função dayjs() é usada para trabalhar com datas, permitindo criar, modificar e comparar valores de tempo — útil para cálculos de prazo, SLA e diferenças entre datas.
Manipular datas
Permite criar ou converter valores em datas manipuláveis, que podem ser usadas em cálculos e comparações.
| Situação | Expressão | Resultado |
|---|---|---|
| Data atual | dayjs() | Retorna a data e hora atual do sistema |
| Data fixa | dayjs('2024-01-01') | Cria uma data específica (1º de janeiro de 2024) |
| Data vinda de um campo | dayjs({{data.data_inicio}}) | Converte o valor do campo em uma data utilizável nas expressões |
Adicionar ou subtrair tempo
Permite ajustar uma data existente, somando ou subtraindo períodos de tempo.
| Situação | Expressão | Resultado |
|---|---|---|
| Adicionar dias | dayjs({{data.data}}).add(30, 'day') | Retorna a data original acrescida de 30 dias |
| Subtrair meses | dayjs({{data.data}}).subtract(1, 'month') | Retorna a data original com 1 mês a menos |
| Adicionar anos | dayjs({{data.data}}).add(1, 'year') | Retorna a data original acrescida de 1 ano |
| Subtrair dias | dayjs({{data.data}}).subtract(7, 'day') | Retorna a data original com 7 dias a menos |
Diferença entre datas
Permite calcular o intervalo entre duas datas, retornando o valor em uma unidade de tempo específica.
| Situação | Expressão | Resultado |
|---|---|---|
| Diferença em dias | dayjs({{data.fim}}).diff(dayjs({{data.inicio}}), 'day') | Retorna a quantidade de dias entre as duas datas |
| Diferença em meses | dayjs({{data.fim}}).diff(dayjs({{data.inicio}}), 'month') | Retorna a quantidade de meses entre as duas datas |
| Diferença em anos | dayjs({{data.fim}}).diff(dayjs({{data.inicio}}), 'year') | Retorna a quantidade de anos entre as duas datas |
| Diferença em horas | dayjs({{data.fim}}).diff(dayjs({{data.inicio}}), 'hour') | Retorna a quantidade de horas entre as duas datas |
Ordem de execução das expressões
sumArray → math → dayjs → format
sumArrayé executado primeiro- depois
math - depois
dayjs - e por último
format
Quando você combina várias funções na mesma expressão, o ENSPACE segue uma ordem fixa de execução.
Isso significa que algumas funções sempre serão resolvidas antes de outras, independentemente de como a expressão foi escrita.
Como interpretar essa ordem
Você só pode usar o resultado de uma função dentro de outra se ela vier antes na ordem de execução.
| Situação | Expressão | Resultado |
|---|---|---|
✅ Correto — math antes de format | format(math({{data.a}} + {{data.b}}), {"type": "number"}) | math() é executado primeiro. O resultado é passado para format(), que formata o resultado |
❌ Incorreto — dayjs dentro de math | math(dayjs({{data.data}})) | dayjs é executado depois de math. O sistema não consegue resolver corretamente |
✅ Correto — sumArray antes de math | math(sumArray(data.parcelas, valor) * 2) | sumArray() é executado primeiroo resultado é usado no cálculo do math() |
| ❌ Incorreto — função fora da ordem | dayjs(math({{data.valor}})) | math não pode ser resolvido dentro de dayjse a expressão retorna erro |
Limitação importante
Essa ordem também se aplica a expressões mais complexas.
Por exemplo:
- você pode usar
dayjs()dentro demath() - mas não pode usar
math()dentro dedayjs() - você pode usar
sumArray()antes demath() - mas não pode aninhar
sumArray()dentro de outrosumArrayque esteja em um nível inferior
Se a ordem não for respeitada, a expressão pode retornar erro ou não funcionar como esperado.
Exemplos práticos
Financeiro
Exemplos comuns de cálculos financeiros.
| Situação | Expressão | Resultado |
|---|---|---|
| Valor com acréscimo de 15% | math({{data.valor}} + {{data.valor}} * 0.15) | Calcula o valor com acréscimo de 15%. Ex: 100 → 115 |
| Média de três valores | math(({{data.a}} + {{data.b}} + {{data.c}}) / 3) | Soma os três valores e divide por 3 |
| Aplicar desconto condicional | math({{data.valor}} > 100 ? {{data.valor}} * 0.9 : {{data.valor}}) | Aplica 10% de desconto se o valor for maior que 100. Senão mantém o valor original |
Operacional
Exemplo de regra de processo.
| Situação | Expressão | Resultado |
|---|---|---|
| Verificar prazo da tarefa | math({{data.data_conclusao}} <= {{data.data_limite}} ? 'Sim' : 'Não') | "Sim" se a tarefa foi concluída no prazo; "Não" se houve atraso |
Datas
Exemplo de cálculo com prazos.
| Situação | Expressão | Resultado |
|---|---|---|
| Dias até a data limite | dayjs({{data.data_limite}}).diff(dayjs(), 'day') | Retorna quantos dias faltam até a data limite |
Listas
Exemplo de agregação de dados.
| Situação | Expressão | Resultado |
|---|---|---|
| Soma de parcelas | sumArray(data.parcelas, valor) | Soma todos os valores das parcelas |
Variáveis e formatação
Para aprender como exibir e formatar os resultados dessas expressões, consulte a documentação de Variáveis e Formatação