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:

• 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.

La regla aplicada 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)

Semántica "más alto es mejor"

En esta versión el modelo asume que valores más altos son mejores (por ejemplo: cobertura de tests, porcentaje de avance, NPS). Si su KPI funciona al revés (donde un valor bajo es lo deseable, por ejemplo: tiempo de respuesta o número de incidencias), modele los umbrales invirtiendo el significado del rango o utilice un cálculo intermedio. En futuras versiones se prevé un modo "menor es mejor" nativo.

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.
   • 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. 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).

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.

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).

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.

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 Traffic Light KPI (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.