Depuración y escritura de expresiones

Esta guía explica cómo escribir expresiones para propiedades personalizadas, cómo usar el Rastro de evaluación para depurarlas y cómo se comportan los diferentes tipos de campo (texto, número y booleano) dentro de una expresión.

Una expresión es una fórmula que calcula un valor automáticamente a partir de otros campos del registro. A continuación se muestra un ejemplo que produce una puntuación ponderada:

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

Cuando la expresión anterior se evalúa sobre un registro donde:

• [ROI / Payback Period-Value] → 4

• [Customer Experience-Value] → 2

• [Scalability-Value] → 1

• [Implementation Complexity-Value] → 2

el resultado es 7.75.

Cuando hace clic en Evaluar en el editor de expresiones, se muestra un resultado. El Rastro de evaluación se expande a continuación y lo guía a través de cada paso que el motor siguió para llegar a ese resultado. Haga clic en Show trace para revelarlo y en Ocultar rastro para contraerlo.

El rastro tiene cuatro secciones:

Enumera cada referencia de campo encontrada en la expresión junto con su valor actual del registro de muestra cargado.

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

Sugerencia: Si un campo muestra (null) aquí, el registro no tiene un valor para ese campo. Los campos nulos pueden causar resultados inesperados — consulte Manejo de valores NULL a continuación.

El motor reemplaza cada referencia de campo por su valor resuelto para que pueda ver el cálculo en bruto:

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

Esto es útil para detectar cuándo un campo se resolvió en un valor inesperado.

Cada grupo entre paréntesis se evalúa individualmente:

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

Si una subexpresión produce un número inesperado, concentre su depuración ahí.

La respuesta totalmente calculada:

Result ⇒ 7.75

Antes de poder evaluar una expresión, necesita un contexto de muestra — un conjunto real o representativo de valores de campo con el que hacer pruebas.

1. Carga automática — Cuando habilita expresiones en una propiedad personalizada y empieza a editar, el editor carga automáticamente un contexto de muestra a partir del tipo de entidad actual (Proyecto, Acción o Persona). El menú desplegable Campos en el pie del editor enumera todos los nombres de campo disponibles y su valor de muestra.

2. Insertar campos — Haga clic en el botón Campos para explorar los nombres de campo disponibles. Al seleccionar un campo, este se inserta en la expresión entre corchetes, por ejemplo, [Priority].

3. Verificar la validez del campo — El editor resalta cualquier token de campo que no exista en el contexto cargado. Si ve una insignia roja "Inválido" junto a un token, el nombre del campo está mal escrito o no está disponible para este tipo de entidad.

4. Revisar valores — Abra el menú desplegable Campos para ver el valor de muestra junto a cada nombre de campo. Esto le indica si el campo es un número, un texto, un booleano o nulo.

Los campos numéricos (por ejemplo, las propiedades Puntuación y Número) se resuelven en un valor numérico dentro del contexto de la expresión.

• Puede usar operadores aritméticos directamente: [Score] * 2, [Budget] + 1000.

• La división por cero producirá un error de evaluación.

• Si un campo numérico está vacío (nulo), las operaciones aritméticas con él devuelven nulo. Protéjase contra esto con COALESCE([Score], 0).

Los campos de texto (por ejemplo, Estado, Categoría, el texto de visualización de una Opción) se resuelven en un valor de string.

• Compare con comillas: [Status] = "Active".

• La comparación de strings es insensible a mayúsculas y minúsculas.

• El operador + en dos strings realiza concatenación: "Phase: " + [Phase] produce Phase: Build.

Los campos Sí/No se resuelven en verdadero o falso.

• Úselos directamente en condiciones: IF([IsActive], "Yes", "No").

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

• Los valores FALSE, 0, "" (string vacío), NULL y la string literal "false" se tratan todos como falsy. Todo lo demás es truthy.

• Tenga en cuenta que la string "false" es un caso especial — aunque es una string no vacía, el motor la trata como falsy para alinearse con el tipo de dato Sí/No.

• Las fechas se comparan cronológicamente: [DueDate] < [StartDate].

• Use la función DIFF para obtener la diferencia entre dos fechas: DIFF([StartDate], [EndDate], "day").

Si un campo es de tipo texto (string) y usted intenta usarlo en una operación aritmética como la multiplicación o la resta, el motor de expresiones intentará convertir la string en un número.

Advertencia de validación: Al guardar una definición de propiedad, el editor valida la expresión sustituyendo valores de marcador de posición para cada campo referenciado. Si se usa un campo de texto en una posición donde se espera un número, la validación marcará esto como un error. Corríjalo de una de las siguientes formas:

• Cambiando el campo referenciado a un tipo de dato Número, o

• Envolviendo el campo en una protección: IF([TextField] = NULL, 0, [TextField]) para que siempre se resuelva en un número.

Cuando usa + y un lado es una string, el motor convierte el número a texto y los concatena:

"Score=" + [Score]

Si [Score] es 85, el resultado es la string "Score=85".

1. Siempre haga clic en Evaluar después de escribir o cambiar una expresión. El rastro muestra de inmediato si los valores de los campos son los que espera.

2. Revise la Expresión sustituida para ver el cálculo en bruto. Si un campo se resolvió en null o una string inesperada, esa es la fuente del problema.

3. Observe los Resultados de subexpresiones para aislar qué grupo está produciendo el número incorrecto.

4. Esté atento a los desajustes de tipo. Un campo que usted cree que es numérico podría en realidad estar almacenado como texto (por ejemplo, un valor de opción). El rastro mostrará su tipo resuelto.

5. Use COALESCE para mayor seguridad. Envuelva cualquier campo que pudiera estar vacío: COALESCE([OptionalScore], 0) garantiza un cero en lugar de nulo.

6. Use IF para ramificaciones. Proteja las expresiones con IF([Field] = NULL, <default>, <calculation>) para evitar errores en registros incompletos.

7. Verifique si hay tokens inválidos. Si aparece una insignia de nombre de campo en rojo debajo de la expresión, el nombre no coincide con ningún campo disponible. Verifique la ortografía, los espacios y las mayúsculas y minúsculas.

Objetivo: Calcular una puntuación de prioridad ponderada a partir de cuatro campos de calificación y agregar una línea base fija de 5.

Expresión:

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

Salida del rastro con valores de muestra:

Si alguna de estas calificaciones estuviera vacía, envolverlas en COALESCE evitaría un 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