Campo Personalizado Semáforo KPI (Traffic Light)

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

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.

Paridad con la versión Data Center

El campo Semáforo KPI de Cloud lanza la paridad funcional equivalente a la versión 1.2.0 de Data Center: umbrales por contexto, leyenda descriptiva, tooltip de regla, modo "Lower is better" y soporte de modo oscuro.

Crear el campo Semáforo KPI

1. En Jira, haga clic en el icono de Configuración (rueda dentada) en la esquina superior derecha.

2. Seleccione Issues (Incidencias).

3. En la barra lateral izquierda, en la sección Fields, haga clic en Custom fields.

4. Haga clic en Create custom field en la esquina superior derecha.

5. En la pantalla "Select a field type", busque y seleccione Traffic Light KPI (proporcionado por Admin Essentials). Haga clic en Next.

   💡 Lo reconocerá por su descripción: "Numeric KPI rendered as a red/yellow/green indicator with per-context thresholds." y por su icono de semáforo.

   

6. Nombre y descripción:

   • Introduzca un Name (Nombre) para el campo (por ejemplo, "Nivel de cumplimiento", "Riesgo del proyecto", "SLA de atención").
   • Añada una Description (Descripción) opcional.

7. Haga clic en Create.

8. Asociar a pantallas: Marque las pantallas correspondientes (creación, edición, vista, transición) y haga clic en Update.

A partir de este momento, el campo está disponible. No obstante, el indicador aún no mostrará colores: hay que 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 Semáforo KPI están siempre asociados al contexto de configuración del campo (FieldConfigContext). 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:

• Low threshold (Red max) — Valor máximo que se considera rojo. Cualquier valor menor o igual a este umbral renderiza un indicador rojo.
• High threshold (Yellow max) — Valor máximo que se considera amarillo. Valores mayores que Low y menores o iguales a High renderizan amarillo. Valores mayores que High renderizan verde.
• Lower value is better — 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 ≤ Low	🔴 Rojo
Low < value ≤ High	🟡 Amarillo
value > High	🟢 Verde
Valor vacío / contexto sin umbrales	⚪ Gris (sin estado)

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

Valor del issue	Color resultante
value ≤ Low	🟢 Verde
Low < value ≤ High	🟡 Amarillo
value > High	🔴 Rojo
Valor vacío / contexto sin umbrales	⚪ Gris (sin estado)

¿Cuándo activar "Lower is better"?

Actívelo en KPIs donde un valor menor indica un mejor resultado: tiempo de resolución, número de incidencias abiertas, defectos críticos, tiempo medio de respuesta, etc. 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: Low < High. 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. Vaya a Configuración → Issues → Custom fields.

2. Localice el campo Semáforo KPI que creó y haga clic en el icono de acciones (⋯) → Contexts and default value.

3. En la página de contextos del campo, abra el contexto que quiere configurar.

4. Dentro del contexto verá una sección aportada por Admin Essentials llamada Traffic Light thresholds con un resumen de los umbrales actuales (o el aviso "No thresholds configured. Values render gray." si aún no se han definido).

5. Complete el formulario:

   • Low threshold (Red max): valor numérico.
   • High threshold (Yellow max): valor numérico estrictamente mayor que el anterior.
   • Lower value is better: marque la casilla si su KPI funciona en sentido inverso.

6. Haga clic en Save.

   

Tras guardar, 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 llamado "Nivel de cumplimiento" expresado como porcentaje:

• Low: 30 → de 0 a 30 se considera crítico (rojo).
• High: 70 → de 31 a 70 se considera en riesgo (amarillo).
• Mayores a 70 → cumplimiento adecuado (verde).
• Lower value is better: desactivado.

Si el 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:

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

Observe que los umbrales mantienen el orden Low < High; el cambio de semántica lo aporta la opción Lower value 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."
• Low es mayor o igual que High → "Low threshold must be strictly less than the high threshold."

Renderizado en la vista del issue

Cuando un issue tiene un valor numérico guardado y su contexto tiene umbrales definidos, el complemento renderiza un indicador de color acompañado del valor numérico del campo. El color refleja el estado resuelto por los umbrales y un aria-label accesible describe el estado para lectores de pantalla.

Leyenda descriptiva

Debajo del indicador aparece una leyenda que describe los rangos configurados en el contexto. La leyenda se adapta automáticamente al modo activo:

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

Tooltip al pasar el cursor

Al pasar el cursor sobre el indicador de color, aparece un tooltip con el rango exacto al que pertenece el valor del issue (por ejemplo, "Red: ≤ 30" o "Green: > 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 están construidos con tokens de diseño de UI Kit 2 (color.text, color.text.subtlest), por lo que se renderizan con colores accesibles tanto en el tema claro como en el tema oscuro de Jira Cloud, manteniendo el contraste en ambos modos.

Soporte de búsqueda y JQL

El campo se registra en Forge con type: number, lo que habilita los operadores numéricos estándar de JQL:

Operador	Soportado	Ejemplo
= / !=	✅	"Nivel de cumplimiento" = 100
< / <= / > / >=	✅	"Nivel de cumplimiento" >= 70
is EMPTY / is not EMPTY	✅	"Nivel de cumplimiento" is not EMPTY
in / not in	✅	"Nivel de cumplimiento" in (50, 75, 100)

JQL trabaja sobre el valor, no sobre el color

Las consultas JQL operan sobre el valor numérico almacenado, no sobre el color resuelto. Para listar "todos los issues en rojo", combine los operadores JQL con los mismos umbrales del contexto: "Nivel de cumplimiento" <= 30.