Campo Personalizado Traffic Light KPI

El campo personalizado Traffic Light KPI permite almacenar un valor numérico por issue y mostrarlo como un indicador visual en tres colores — 🔴 rojo, 🟡 amarillo y 🟢 verde — resuelto a partir de umbrales configurables por contexto.

Está pensado para representar KPIs, niveles de servicio, tiempos de respuesta, porcentajes de avance, riesgos u otros indicadores donde el valor numérico es relevante pero, sobre todo, importa comunicar de un vistazo si la situación es buena, intermedia o crítica.

Este apartado describe cómo crear el campo, configurar los umbrales para cada contexto y entender el comportamiento del indicador.

Crear el campo Traffic Light KPI

1. Navegue a Administración de Jira > Incidencias.

2. En la barra lateral izquierda, dentro de la sección Campos, haga clic en Campos personalizados.

3. Haga clic en Añadir campo personalizado en la esquina superior derecha.

4. En la pantalla "Seleccione un tipo de campo", abra la categoría Advanced y seleccione Traffic Light KPI. Haga clic en Siguiente.

   💡 Lo reconocerá por su descripción: "Numeric field that renders a colored indicator (red/yellow/green) based on configurable thresholds per context." y por su imagen de vista previa (los tres focos del semáforo).

   

5. Nombre y Descripción:

   • Introduzca un Nombre para el campo (por ejemplo, "Nivel de cumplimiento", "Riesgo del proyecto", "SLA de atención").
   • Añada una Descripción opcional. Este texto aparecerá debajo del campo para guiar a los usuarios.

6. Haga clic en Crear.

7. Asociar a pantallas: Jira le solicitará seleccionar las pantallas en las que aparecerá el campo (creación, edición, vista). Marque las que correspondan y haga clic en Actualizar.

A partir de este momento, el campo estará disponible en las pantallas configuradas. No obstante, el indicador aún no mostrará colores: para ello debe configurar los umbrales en cada contexto del campo (siguiente apartado).

Valores sin configuración de umbrales

Mientras un contexto del campo no tenga umbrales definidos, los valores numéricos guardados se renderizan en color gris (sin estado). Esto es intencional: evita comunicar un color que pueda inducir a interpretaciones equivocadas hasta que el administrador defina la regla de negocio.

Configurar los umbrales (por contexto)

Los umbrales del campo Traffic Light KPI están siempre asociados al contexto de configuración (FieldConfigContext) activo del campo. Esto significa que puede definir umbrales distintos por proyecto o por tipo de issue, según los contextos que haya creado en el campo.

Modelo de umbrales

Cada contexto requiere dos valores numéricos y un modo de interpretación:

• Red max — Valor máximo que se considera rojo. Cualquier valor menor o igual a este umbral renderiza un indicador rojo.
• Yellow max — Valor máximo que se considera amarillo. Valores mayores que Red max y menores o iguales a Yellow max renderizan amarillo. Valores mayores que Yellow max renderizan verde.
• Lower is better (menor es mejor) — Casilla opcional que invierte la asignación de colores cuando el KPI funciona al revés (un valor bajo indica mejor desempeño).

La regla aplicada en el modo por defecto (más alto es mejor) es:

Valor del issue	Color resultante
value <= Red max	🔴 Rojo
Red max < value <= Yellow max	🟡 Amarillo
value > Yellow max	🟢 Verde
Valor vacío / contexto sin umbrales	⚪ Gris (sin estado)

Cuando se activa Lower is better, la asignación se invierte sin alterar el orden de los umbrales:

Valor del issue	Color resultante
value <= Red max	🟢 Verde
Red max < value <= Yellow max	🟡 Amarillo
value > Yellow max	🔴 Rojo
Valor vacío / contexto sin umbrales	⚪ Gris (sin estado)

¿Cuándo activar "menor es mejor"?

Actívelo en KPIs donde un valor menor indica un mejor resultado: tiempo de resolución, número de incidencias, defectos abiertos, tiempo medio de respuesta, etc. En esos casos el indicador comunicará verde para los valores bajos (deseables) y rojo para los altos (críticos), sin necesidad de invertir manualmente el significado de los umbrales.

Invariante

El editor obliga a que se cumpla: Red max < Yellow max. Si introduce valores que no respetan esta relación, el formulario rechazará el guardado con un mensaje de error.

Pasos para configurar los umbrales

1. Navegue a Administración de Jira > Incidencias > Campos personalizados.
2. Localice el campo Traffic Light KPI que creó y haga clic en el icono de acciones (⋯) > Configurar.
3. En la página de configuración del campo verá la lista de contextos asociados. Para cada contexto aparece una fila adicional llamada Thresholds (Umbrales) aportada por este complemento.
4. En la fila Thresholds:
   • Si el contexto aún no tiene umbrales, verá el texto "No thresholds configured. Values render gray."
   • Si ya tiene umbrales definidos, verá un resumen del estilo "Red max: 30 — Yellow max: 70".
5. Haga clic en Edit (Editar) a la derecha de la fila Thresholds.
6. En el formulario Edit Traffic Light KPI Thresholds:
   • Introduzca el valor de Red max.
   • Introduzca el valor de Yellow max.
   • Marque la casilla Lower is better si su KPI funciona en sentido inverso (valores bajos = buen desempeño).
   • Haga clic en Save (Guardar).

Tras guardar volverá a la página de configuración del campo y la fila Thresholds mostrará el nuevo resumen. El resumen también indica el modo activo (por ejemplo, "Red max: 30 — Yellow max: 70 — Lower is better"). Los issues asociados a ese contexto comenzarán a renderizar el indicador con los colores correspondientes.

Ejemplo: KPI de cumplimiento (0–100)

Supongamos un campo Traffic Light KPI llamado "Nivel de cumplimiento" expresado como porcentaje:

• Red max: 30 → de 0 a 30 se considera crítico (rojo).
• Yellow max: 70 → de 31 a 70 se considera en riesgo (amarillo).
• Mayores a 70 → cumplimiento adecuado (verde).
• Lower is better: desactivado (valores altos son mejores).

Si un mismo campo se reutiliza en varios proyectos con tolerancias distintas, basta con crear un contexto por proyecto y definir umbrales independientes en cada uno.

Ejemplo: Tiempo medio de resolución (modo "menor es mejor")

Para un campo Semáforo llamado "Tiempo de resolución (horas)", donde un valor bajo es deseable:

• Red max: 4 → de 0 a 4 horas se considera excelente (verde).
• Yellow max: 12 → de 5 a 12 horas se considera aceptable (amarillo).
• Mayores a 12 → respuesta lenta (rojo).
• Lower is better: activado.

Observe que los umbrales mantienen el orden Red max < Yellow max; el cambio de semántica lo aporta la opción Lower is better.

Errores de validación posibles

El editor valida la entrada y muestra mensajes específicos cuando:

• Alguno de los campos está vacío → "This field is required."
• El valor introducido no es un número válido → "Please enter a valid number."
• Red max es mayor o igual que Yellow max → "Red max must be strictly less than Yellow max."
• El contexto no puede resolverse (caso poco común; suele ocurrir al abrir el formulario por una URL caducada) → "The field configuration could not be located. Please return to the custom field configuration page and try again."

Renderizado en la vista del issue

Cuando un issue tiene un valor numérico guardado en el campo Traffic Light KPI y su contexto tiene umbrales definidos, el complemento renderiza un indicador de tres focos (verde, amarillo, rojo) acompañado del valor numérico del campo. El foco encendido refleja el color resuelto por los umbrales y un aria-label accesible describe el estado para lectores de pantalla.

El indicador aparece en:

• La vista detalle del issue (panel lateral de campos).
• La vista en columna del navegador de issues, los gadgets y los tableros (modo compacto, ideal para listados).

Leyenda de umbrales en la vista del issue

A partir de esta versión, la vista detalle del issue incluye una leyenda descriptiva debajo del indicador con los rangos configurados en el contexto. La leyenda se adapta automáticamente al modo activo:

• En el modo por defecto, muestra los rangos crecientes (≤ Red max en rojo, Red max < … ≤ Yellow max en amarillo, > Yellow max en verde).
• En el modo Lower is better, los rangos siguen siendo los mismos pero la asignación de color refleja la inversión.

La leyenda se renderiza con los textos del idioma del usuario y respeta el tema de Jira (modo claro y modo oscuro).

Tooltip al pasar el cursor

Al pasar el cursor sobre el indicador de color, se muestra un tooltip con el rango exacto al que pertenece el valor del issue (por ejemplo, "Rojo: ≤ 30" o "Verde: > 70"). Esto permite interpretar el estado de un vistazo sin necesidad de abrir la configuración del campo.

Compatibilidad con modo oscuro

La leyenda, el tooltip y el valor numérico del indicador se renderizan con colores accesibles tanto en el tema claro como en el tema oscuro de Jira. El contraste del número se mantiene legible en ambos modos.

Soporte de búsqueda (searcher) y JQL

El campo Traffic Light KPI se registra con el Number Range Searcher estándar de Jira, lo que habilita búsquedas y filtros por rango numérico. Esto le permite:

• Filtrar issues por valor desde el buscador básico (igual, mayor que, menor que, etc.).

• Usar el campo en consultas JQL, por ejemplo:

  "Nivel de cumplimiento" < 30
  "Nivel de cumplimiento" >= 70 AND project = "ACME"

  donde Nivel de cumplimiento es el nombre que asignó al campo al crearlo.

Los valores se indexan automáticamente a medida que los issues se crean o actualizan; no se requiere configuración adicional.

Filtrar por zona del Semáforo con JQL

JQL busca el valor numérico almacenado en el campo, no el color que se muestra en pantalla. Por eso no existe una sintaxis del tipo "Mi Campo" = "ROJO": para localizar incidencias en zona roja, amarilla o verde hay que traducir la zona a un rango numérico usando los umbrales del contexto de configuración activo.

¿Por qué por contexto y no por color?

El color que ve en cada issue es el resultado de comparar el valor numérico con los umbrales del contexto de configuración al que pertenece el issue. Si el mismo campo se usa en varios proyectos con umbrales distintos, el rango numérico que representa "rojo" es diferente en cada contexto. No es posible escribir una sola consulta JQL que signifique "todas las incidencias en rojo" en toda la instancia cuando el campo tiene contextos con umbrales distintos.

Consultas de ejemplo integradas en el editor de umbrales

A partir de la versión 1.3.0, el editor de umbrales Edit Traffic Light KPI Thresholds incluye un bloque de ayuda con consultas JQL listas para usar. Las consultas se generan automáticamente con:

• El nombre real del campo tal como está registrado en Jira.
• Los valores de Red max y Yellow max introducidos en el formulario.

Las consultas se actualizan en vivo al cambiar los umbrales o al marcar/desmarcar la opción Lower is better.

Para copiar una consulta haga clic en el botón Copiar que aparece junto a cada zona. La consulta copiada está lista para pegarse directamente en el buscador de issues o en cualquier filtro guardado.

Compatibilidad con modo oscuro

El bloque de ayuda JQL utiliza los tokens de color del sistema de diseño de Atlassian, por lo que se adapta automáticamente al tema claro y oscuro de Jira sin necesidad de configuración adicional.

Plantillas JQL

Si necesita construir consultas fuera del editor, utilice las siguientes plantillas. Sustituya <NombreCampo> por el nombre del campo y <LOW> / <HIGH> por los valores Red max y Yellow max del contexto que le interesa.

Modo por defecto (mayor es mejor):

Zona	Expresión JQL
🔴 Roja	"<NombreCampo>" <= <LOW>
🟡 Amarilla	"<NombreCampo>" > <LOW> AND "<NombreCampo>" <= <HIGH>
🟢 Verde	"<NombreCampo>" > <HIGH>

Modo invertido (Lower is better activado): Los rangos numéricos son los mismos, pero el color de las zonas extremas se intercambia.

Zona	Expresión JQL
🟢 Verde	"<NombreCampo>" <= <LOW>
🟡 Amarilla	"<NombreCampo>" > <LOW> AND "<NombreCampo>" <= <HIGH>
🔴 Roja	"<NombreCampo>" > <HIGH>

Ejemplo práctico

Suponga un campo llamado "Salud del Cliente" con Red max = 30 y Yellow max = 70 (modo por defecto):

"Salud del Cliente" <= 30                                         → Zona roja
"Salud del Cliente" > 30 AND "Salud del Cliente" <= 70            → Zona amarilla
"Salud del Cliente" > 70                                          → Zona verde

Si en otro contexto del mismo campo los umbrales son Red max = 50 y Yellow max = 80, la primera consulta devolvería resultados incorrectos para ese contexto. Cada consulta es específica para el contexto del que provienen los umbrales.

Cómo localizar los umbrales de un contexto

Navegue a Administración de Jira > Incidencias > Campos personalizados, localice el campo Traffic Light KPI y haga clic en Configurar. En la columna Thresholds de cada contexto encontrará el resumen de umbrales (p. ej. "Red max: 30 — Yellow max: 70"). También puede abrirlo en el editor para ver las consultas generadas automáticamente y copiarlas con un clic.

Limitación conocida

No existe ningún mecanismo en Jira Data Center que indexe el color calculado del Semáforo como un campo buscable independiente. La única forma de filtrar por zona es usar rangos numéricos con los umbrales del contexto de destino. Si necesita una búsqueda global por color (p. ej. "todos los issues en rojo en cualquier proyecto"), deberá ejecutar una consulta por cada contexto con umbrales distintos y combinar los resultados.

Internacionalización (i18n)

Todos los textos administrativos y de interfaz del campo Traffic Light KPI (nombre del campo, fila de configuración, formulario de umbrales, mensajes de error, etiquetas accesibles y el nuevo bloque de ayuda JQL) están internacionalizados y respetan el idioma del usuario de Jira, con soporte de español e inglés incluido en el paquete.