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 issue 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.
¿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 issue 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.
Campos compatibles
| Campo | Disponible desde |
|---|---|
| Traffic Light KPI | v5.0.0 |
| Percentage Field | v5.0.0 |
Claves de propiedad
Cada campo almacena su color en una propiedad propia, identificada por el ID del campo (fieldId).
| Campo | Clave de propiedad |
|---|---|
| Traffic Light KPI | admin-essentials.traffic-light.{fieldId}.color |
| Percentage Field | admin-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.
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 propiedad | Significado |
|---|---|
"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 issue nunca ha sido guardado desde que se instaló la v5.0.0 |
Cuando el campo se vacía, la propiedad se elimina del issue.
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 issue (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 issue, 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 issue.
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 issue, la API devuelve un error 404.
Limitaciones importantes
No es posible buscar issues por color de banda usando JQL libre (por ejemplo, una consulta del tipo "Mi Semáforo" = red no está disponible). Jira Cloud solo puede indexar propiedades de issue para JQL cuando la clave de propiedad es fija y está registrada de forma específica; las claves de banda de color incluyen el ID del campo en cada instalación, lo que impide ese tipo de indexación.
Alternativa: para listar issues por color, combine los operadores numéricos del campo con los umbrales del contexto. Por ejemplo, si el umbral rojo de su campo Traffic Light es ≤ 30, puede escribir "Mi Semáforo KPI" <= 30 en JQL para obtener todos los issues en rojo.
Los issues 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 issue (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 issues en lote mediante una regla de Jira Automation o la API.
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 issues. El color corregido se calculará la próxima vez que cada issue sea guardado.
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 issues.