Saltar al contenido principal
Version: Next 🚀

Propiedades de banda de color

Desde la versión 5.0.0, los campos Traffic Light KPI y Percentage Field sincronizan automáticamente su banda de color derivada — 🔴 rojo, 🟡 amarillo o 🟢 verde — en una propiedad del work item de Jira.

Esto permite que validadores de workflow, automatizaciones y otras integraciones consulten el color actual de estos campos sin necesidad de conocer los umbrales numéricos configurados en cada contexto.

Desde la versión 1.9.0, además, puede buscar work items por color con JQL mediante las funciones trafficLightBand y percentageBand. Consulte Búsqueda JQL por banda de color más abajo.

¿Para qué sirve?​

Algunos casos de uso habituales:

  • Validador de workflow — bloquear una transición si el Traffic Light KPI está en rojo: "Si el semáforo es rojo → exigir que Assignee esté asignado antes de cerrar".
  • Jira Automation — enviar una notificación automática o escalar un work item cuando un indicador de porcentaje pasa a rojo.
  • REST API — leer el color actual del campo desde una integración externa sin necesidad de interpretar umbrales.
  • Filtros, dashboards y colas JSM — listar los work items en rojo (o en amarillo, o en verde) con una consulta JQL, sin repetir los umbrales de cada contexto.

Campos compatibles​

CampoDisponible desde
Traffic Light KPIv5.0.0
Percentage Fieldv5.0.0

Claves de propiedad​

Cada campo almacena su color en una propiedad propia, identificada por el ID del campo (fieldId).

CampoClave de propiedad
Traffic Light KPIadmin-essentials.traffic-light.{fieldId}.color
Percentage Fieldadmin-essentials.percentage.{fieldId}.color

Ejemplo: si su campo Traffic Light KPI tiene el ID customfield_10256, la clave de propiedad será admin-essentials.traffic-light.customfield_10256.color.

¿Cómo encontrar el ID del campo?

Vaya a Jira Settings → Issues → Custom fields y haga clic sobre el nombre del campo. La URL del navegador mostrará el ID numérico del campo (por ejemplo, .../custom-fields/10256/...). El ID que debe usar en la clave de propiedad incluye el prefijo customfield_, quedando como customfield_10256.

Valores posibles​

Valor de la propiedadSignificado
"red"El campo se encuentra en la banda roja según los umbrales del contexto
"yellow"El campo se encuentra en la banda amarilla
"green"El campo se encuentra en la banda verde
(ausente)El campo está vacío, o el work item nunca ha sido guardado desde que se instaló la v5.0.0

Cuando el campo se vacía, la propiedad se elimina del work item.

Cómo se mantiene sincronizado el color​

La propiedad de color se actualiza por dos vías complementarias que se activan automáticamente:

  • Al guardar desde la UI del campo — cuando un usuario edita el campo directamente en el work item (desde el formulario de creación, edición inline o pantalla de transición), el color se escribe en la propiedad de forma inmediata al guardar.

  • Mediante un proceso automático en segundo plano — el complemento también detecta cualquier creación o actualización de work item, incluidas transiciones, ediciones masivas, cambios por API, importaciones CSV y cualquier otra operación que no pase por la UI del campo. En todos estos casos recalcula las propiedades de color de forma automática.

Ambas vías garantizan que la propiedad refleje siempre el color actual, independientemente de cómo se haya modificado el work item.

Cómo usar el color en otras superficies​

Validador Field Dependency​

La forma más directa de usar el color en reglas de workflow es a través del validador Field Dependency (Admin Essentials). Desde la v5.0.0, este validador ofrece operadores is e is not específicos para Traffic Light KPI y Percentage Field, que comparan el color directamente sin necesidad de conocer los umbrales numéricos.

Consulte la guía del Validador de Dependencia entre Campos para ver ejemplos de configuración paso a paso.

Jira Automation​

En las reglas de automatización de Jira puede leer el color mediante smart values. La propiedad está disponible como:

{{issue.properties.["admin-essentials.traffic-light.customfield_10256.color"]}}

Sustituya customfield_10256 por el ID de su campo específico. Esto le permite, por ejemplo, añadir una condición "Ejecutar solo si el valor es red" o incluir el color en el texto de una notificación.

REST API de Jira​

Puede consultar la propiedad directamente desde la API de Jira:

GET /rest/api/3/issue/{issueIdOrKey}/properties/admin-essentials.traffic-light.customfield_10256.color

La respuesta devuelve el valor actual ("red", "yellow" o "green"). Si la propiedad todavía no existe para ese work item, la API devuelve un error 404.

Búsqueda JQL por banda de color​

Desde la versión 1.9.0, dos funciones JQL encuentran los work items según el color que muestra un campo Traffic Light KPI o Percentage Field:

FunciónCampo
trafficLightBandTraffic Light KPI
percentageBandPercentage Field

Funcionan en cualquier lugar donde Jira acepta JQL: la búsqueda de work items, los filtros guardados, los gadgets de dashboard que usan un filtro (por ejemplo, Filter Results o Two Dimensional Filter Statistics) y las colas de JSM.

Sintaxis​

issue in trafficLightBand("red")                          -- rojo en CUALQUIER campo Traffic Light KPI
issue in trafficLightBand("yellow", "customfield_10042")  -- un campo concreto, por su ID
issue in trafficLightBand("green", "10042")               -- un campo concreto, por su ID numérico
issue in trafficLightBand("red", "Delivery KPI")          -- un campo concreto, por su nombre (debe ser único)
issue not in trafficLightBand("red")                      -- todo lo que no está en rojo (incluye campos vacíos)
issue in percentageBand("red")                            -- misma sintaxis para los campos Percentage
  • Primer argumento (obligatorio): la banda, "red", "yellow" o "green". No distingue mayúsculas de minúsculas. Los valores son siempre estos en inglés, sea cual sea el idioma del usuario, para que un filtro guardado devuelva lo mismo a todos.
  • Segundo argumento (opcional): el campo, por su ID ("customfield_10042"), por su ID numérico ("10042") o por su nombre. Si se omite, la función busca en todos los campos de ese tipo del site. Si dos campos comparten nombre, use el ID.
  • Operadores: in y not in.

Con dos campos Traffic Light KPI en el site, issue in trafficLightBand("red", "customfield_10042") devuelve solo los work items en rojo en ese campo; sin el segundo argumento, devuelve los que están en rojo en cualquiera de los dos.

Qué work items coinciden​

  • Coincide cada work item cuyo valor numérico cae en la banda pedida, según los umbrales del contexto del campo que aplica a ese work item (espacio / tipo de work item). Un mismo valor puede estar en rojo en un espacio y en amarillo en otro.
  • No requiere backfill: las funciones no leen la propiedad de color, sino el valor del campo. Por eso incluyen también los work items creados antes de actualizar a 1.9.0 o que nunca se volvieron a guardar.
  • Un campo vacío no coincide con ninguna banda. Si se vacía el campo de un work item, deja de aparecer en el filtro.
  • Un contexto de Traffic Light KPI sin umbrales muestra el indicador en gris, así que sus work items no coinciden con ninguna banda. Los contextos de Percentage sin umbrales guardados usan los valores por defecto (40 / 70), igual que la barra.
  • Los operadores numéricos del campo (=, !=, <, <=, >, >=, is EMPTY, is not EMPTY, in, not in) siguen funcionando igual. Las funciones son una vía adicional, no un reemplazo.

Cuándo se refleja un cambio​

  • Cambia el valor de un work item: el work item entra en el filtro de su nueva banda en cuanto Jira lo indexa. Suele tardar unos segundos; es el comportamiento estándar de la búsqueda de Jira, no un error.
  • Cambian los umbrales de un contexto: al guardar los umbrales, la app actualiza las búsquedas en pocos segundos. Los work items afectados pasan a su nueva banda sin necesidad de guardarlos de nuevo.
  • Se añaden o quitan espacios o tipos de work item de un contexto: Jira no avisa de este cambio a la app; una actualización automática cada hora lo recoge.

Límites​

  • Jira admite como máximo 1.000 valores (IDs de espacio, IDs de tipo de work item y umbrales) en el resultado de una función. En sites con muchos contextos restringidos a espacios, indique el campo como segundo argumento para acotar la búsqueda. Si se supera el límite, la función devuelve un error explícito.
  • Jira guarda el resultado interno de cada combinación de argumentos y lo descarta si no se usa durante 7 días; la siguiente búsqueda lo vuelve a calcular. No hace falta ninguna acción del administrador.

Mensajes de error​

Si la consulta tiene una banda desconocida, un campo que no existe o que es ambiguo, o un operador no soportado, Jira muestra el error en el idioma del perfil del usuario. Por ejemplo: "Solo se admiten "in" y "not in", por ejemplo: issue in trafficLightBand("red")."

Limitaciones importantes​

La propiedad de color no es buscable con JQL

La propiedad de work item en sí (admin-essentials.traffic-light.{fieldId}.color) no se puede usar en una cláusula JQL: Jira Cloud solo indexa propiedades cuya clave es fija, y estas claves incluyen el ID del campo. Para buscar por color, use las funciones trafficLightBand y percentageBand, que no dependen de la propiedad. La propiedad sigue siendo la vía para el validador Field Dependency, Jira Automation y la REST API.

Issues existentes sin propiedad de color

Los work items creados antes de actualizar a la v5.0.0 no tienen la propiedad de color hasta que el campo se modifique por primera vez en cada uno de ellos. Cualquier edición del work item (desde la UI, una transición, una actualización masiva o un cambio por API) activa el proceso automático y genera la propiedad de color.

Si necesita que todos sus issues tengan la propiedad de forma inmediata, puede actualizar los work items en lote mediante una regla de Jira Automation o la API.

Esta limitación no afecta a las funciones JQL por color, que leen el valor del campo.

Cambios de umbral no retroactivos

Si un administrador modifica los umbrales del campo (por ejemplo, cambia el límite de rojo de 30 a 40), la propiedad de color no se actualiza retroactivamente en todos los work items. El color corregido se calculará la próxima vez que cada work item sea guardado.

Las funciones JQL por color sí aplican los umbrales nuevos sin necesidad de guardar los work items.

Nota de actualización​

La sincronización de la banda de color requiere permisos adicionales sobre la API de Jira. Al actualizar a la v5.0.0 desde una versión anterior es necesario ejecutar el siguiente comando en su entorno de Forge tras el despliegue:

forge install --upgrade

Sin este paso, el complemento no podrá escribir las propiedades de color en los work items.

Última actualización en