Depurando e Escrevendo Expressões

Este guia explica como escrever expressões para propriedades personalizadas, como usar o Rastreamento de Avaliação para depurá-las e como diferentes tipos de campo (texto, número e booleano) se comportam dentro de uma expressão.

Uma expressão é uma fórmula que calcula um valor automaticamente a partir de outros campos no registro. Aqui está um exemplo que produz uma pontuação ponderada:

([ROI / Payback Period-Value] * .30) + ([Customer Experience-Value] * .25)
  + ([Scalability-Value] * .25) + ([Implementation Complexity-Value] * .40) + 3 + 2

Quando a expressão acima é avaliada em relação a um registro onde:

• [ROI / Payback Period-Value] → 4

• [Customer Experience-Value] → 2

• [Scalability-Value] → 1

• [Implementation Complexity-Value] → 2

o resultado é 7,75.

Quando você clica em Avaliar no editor de expressões, um resultado é exibido. O Rastreamento de Avaliação se expande abaixo e percorre cada etapa que o mecanismo executou para chegar a esse resultado. Clique em Mostrar rastreamento para revelá-lo e em Ocultar rastreamento para recolhê-lo.

O rastreamento tem quatro seções:

Lista cada referência de campo encontrada na expressão junto com seu valor atual do registro de amostra carregado.

[ROI / Payback Period-Value]       ⇒ 4
[Customer Experience-Value]        ⇒ 2
[Scalability-Value]                ⇒ 1
[Implementation Complexity-Value]  ⇒ 2

Dica: Se um campo mostrar (null) aqui, o registro não possui um valor para esse campo. Campos nulos podem causar resultados inesperados — consulte Tratamento de Valores NULL abaixo.

O mecanismo substitui cada referência de campo pelo seu valor resolvido para que você possa ver o cálculo bruto:

(4 * .30) + (2 * .25) + (1 * .25) + (2 * .40) + 3 + 2

Isso é útil para identificar quando um campo foi resolvido para um valor inesperado.

Cada grupo entre parênteses é avaliado individualmente:

(4 * .30)  ⇒ 1.2
(2 * .25)  ⇒ 0.5
(1 * .25)  ⇒ 0.25
(2 * .40)  ⇒ 0.8

Se uma subexpressão produzir um número inesperado, concentre sua depuração nela.

A resposta totalmente calculada:

Result ⇒ 7.75

Antes de avaliar uma expressão, você precisa de um contexto de amostra — um conjunto real ou representativo de valores de campo para testar.

1. Carregamento automático — Quando você ativa expressões em uma propriedade personalizada e começa a editar, o editor carrega automaticamente um contexto de amostra do tipo de entidade atual (Projeto, Ação ou Pessoa). O menu suspenso Campos no rodapé do editor lista todos os nomes de campo disponíveis e seus valores de amostra.

2. Inserindo campos — Clique no botão Campos para navegar pelos nomes de campo disponíveis. Selecionar um campo o insere na expressão entre colchetes, por exemplo, [Priority].

3. Verificando a validade do campo — O editor destaca qualquer token de campo que não existe no contexto carregado. Se você vir um emblema vermelho "Inválido" ao lado de um token, o nome do campo está incorreto ou não está disponível para este tipo de entidade.

4. Revisando valores — Abra o menu suspenso Campos para ver o valor de amostra ao lado de cada nome de campo. Isso indica se o campo é um número, um texto, um booleano ou nulo.

Campos numéricos (por exemplo, propriedades de Pontuação e Número) são resolvidos para um valor numérico no contexto da expressão.

• Você pode usar operadores aritméticos diretamente: [Score] * 2, [Budget] + 1000.

• A divisão por zero produzirá um erro de avaliação.

• Se um campo numérico estiver vazio (nulo), operações aritméticas com ele retornam nulo. Proteja-se contra isso com COALESCE([Score], 0).

Campos de texto (por exemplo, Status, Categoria, o texto de exibição de uma Opção) são resolvidos para um valor de string.

• Compare com aspas: [Status] = "Active".

• A comparação de strings é insensível a maiúsculas e minúsculas.

• O operador + em duas strings realiza concatenação: "Phase: " + [Phase] produz Phase: Build.

Campos Sim/Não são resolvidos para verdadeiro ou falso.

• Use-os diretamente em condições: IF([IsActive], "Yes", "No").

• Combine com AND / OR: [IsActive] AND [HasBudget].

• Os valores FALSE, 0, "" (string vazia), NULL e a string literal "false" são todos tratados como falsy. Todo o resto é truthy.

• Esteja ciente de que a string "false" é um caso especial — mesmo sendo uma string não vazia, o mecanismo a trata como falsy para alinhar com o tipo de dado Sim/Não.

• As datas são comparadas cronologicamente: [DueDate] < [StartDate].

• Use a função DIFF para obter a diferença entre duas datas: DIFF([StartDate], [EndDate], "day").

Se um campo é do tipo texto (string) e você tenta usá-lo em uma operação aritmética como multiplicação ou subtração, o mecanismo de expressão tentará converter a string em um número.

Aviso de validação: Ao salvar uma definição de propriedade, o editor valida a expressão substituindo valores de espaço reservado para cada campo referenciado. Se um campo de texto for usado em uma posição onde um número é esperado, a validação sinalizará isso como um erro. Corrija-o de uma das seguintes formas:

• Alterando o campo referenciado para o tipo de dado Número, ou

• Envolvendo o campo em uma proteção: IF([TextField] = NULL, 0, [TextField]) para que sempre resolva para um número.

Quando você usa + e um dos lados é uma string, o mecanismo converte o número em texto e concatena:

"Score=" + [Score]

Se [Score] for 85, o resultado é a string "Score=85".

1. Sempre clique em Avaliar após escrever ou alterar uma expressão. O rastreamento mostra imediatamente se os valores dos campos são o que você espera.

2. Verifique a Expressão Substituída para ver o cálculo bruto. Se um campo foi resolvido como null ou uma string inesperada, essa é a origem do problema.

3. Observe os Resultados de Sub-Expressões para isolar qual grupo está produzindo o número errado.

4. Fique atento a incompatibilidades de tipo. Um campo que você considera numérico pode estar armazenado como texto (por exemplo, um valor de opção). O rastreamento mostrará seu tipo resolvido.

5. Use COALESCE para segurança. Envolva qualquer campo que possa estar vazio: COALESCE([OptionalScore], 0) garante um zero em vez de nulo.

6. Use IF para ramificações. Proteja expressões com IF([Field] = NULL, <default>, <calculation>) para evitar erros em registros incompletos.

7. Verifique tokens inválidos. Se o emblema do nome de um campo aparecer em vermelho abaixo da expressão, o nome não corresponde a nenhum campo disponível. Verifique a ortografia, os espaços e as maiúsculas/minúsculas.

Objetivo: Calcular uma pontuação de prioridade ponderada a partir de quatro campos de avaliação e adicionar uma linha de base fixa de 5.

Expressão:

([ROI / Payback Period-Value] * .30) + ([Customer Experience-Value] * .25)
  + ([Scalability-Value] * .25) + ([Implementation Complexity-Value] * .40) + 3 + 2

Saída do rastreamento com valores de exemplo:

Se alguma dessas avaliações estivesse vazia, envolvê-las em COALESCE evitaria um resultado nulo:

(COALESCE([ROI / Payback Period-Value], 0) * .30)
  + (COALESCE([Customer Experience-Value], 0) * .25)
  + (COALESCE([Scalability-Value], 0) * .25)
  + (COALESCE([Implementation Complexity-Value], 0) * .40) + 3 + 2