Campo Personalizado Semáforo (Traffic Light KPI)

El campo personalizado Traffic Light KPI (Semáforo) 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 Semáforo

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 Semáforo 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 Semáforo 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 Semáforo 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 Semáforo 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 Semáforo 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.

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, por ejemplo, "todos los issues en rojo" combine los operadores JQL con los mismos umbrales del contexto: "Nivel de cumplimiento" <= 30.

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

Internacionalización (i18n)

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