Colour Band Properties
From version 5.0.0 onwards, the Traffic Light KPI and Percentage Field fields automatically sync their derived colour band — 🔴 red, 🟡 yellow, or 🟢 green — into a Jira issue property.
This lets workflow validators, automations, and other integrations query the current colour of these fields without needing to know the numeric thresholds configured in each context.
What is it for?
Some common use cases:
- Workflow validator — block a transition if the Traffic Light KPI is red: "If the traffic light is red → require Assignee to be set before closing".
- Jira Automation — automatically send a notification or escalate an issue when a percentage indicator turns red.
- REST API — read the current field colour from an external integration without having to interpret thresholds.
Supported fields
| Field | Available from |
|---|---|
| Traffic Light KPI | v5.0.0 |
| Percentage Field | v5.0.0 |
Property keys
Each field stores its colour in its own property, identified by the field ID (fieldId).
| Field | Property key |
|---|---|
| Traffic Light KPI | admin-essentials.traffic-light.{fieldId}.color |
| Percentage Field | admin-essentials.percentage.{fieldId}.color |
Example: if your Traffic Light KPI field has the ID customfield_10256, the property key will be admin-essentials.traffic-light.customfield_10256.color.
Go to Jira Settings → Issues → Custom fields and click on the field name. The browser URL will show the field's numeric ID (e.g. .../custom-fields/10256/...). The ID you should use in the property key includes the customfield_ prefix, making it customfield_10256.
Possible values
| Property value | Meaning |
|---|---|
"red" | The field is in the red band according to the context thresholds |
"yellow" | The field is in the yellow band |
"green" | The field is in the green band |
| (absent) | The field is empty, or the issue has never been saved since v5.0.0 was installed |
When the field is cleared, the property is removed from the issue.
How the colour stays in sync
The colour property is updated by two complementary paths that activate automatically:
-
When saving from the field UI — when a user edits the field directly on the issue (from the create form, inline edit, or transition screen), the colour is written to the property immediately on save.
-
Via an automatic background process — the add-on also detects any issue creation or update, including transitions, bulk edits, API changes, CSV imports, and any other operation that does not go through the field UI. In all these cases it recalculates the colour properties automatically.
Both paths ensure the property always reflects the current colour, regardless of how the issue was modified.
How to use the colour in other surfaces
Field Dependency validator
The most direct way to use the colour in workflow rules is through the Field Dependency (Admin Essentials) validator. From v5.0.0, this validator offers is and is not operators specifically for Traffic Light KPI and Percentage Field, which compare the colour directly without needing to know the numeric thresholds.
See the Field Dependency Validator guide for step-by-step configuration examples.
Jira Automation
In Jira automation rules you can read the colour using smart values. The property is available as:
{{issue.properties.["admin-essentials.traffic-light.customfield_10256.color"]}}
Replace customfield_10256 with the ID of your specific field. This lets you, for example, add a condition "Run only if the value is red" or include the colour in a notification message.
Jira REST API
You can query the property directly from the Jira API:
GET /rest/api/3/issue/{issueIdOrKey}/properties/admin-essentials.traffic-light.customfield_10256.color
The response returns the current value ("red", "yellow", or "green"). If the property does not yet exist for that issue, the API returns a 404 error.
Important limitations
It is not possible to search for issues by colour band using free JQL (for example, a query like "My Traffic Light" = red is not available). Jira Cloud can only index issue properties for JQL when the property key is fixed and specifically registered; colour band keys include the field ID for each installation, which prevents that type of indexing.
Alternative: to list issues by colour, combine the field's numeric operators with the context thresholds. For example, if your Traffic Light field's red threshold is ≤ 30, you can write "My KPI" <= 30 in JQL to get all issues in red.
Issues created before upgrading to v5.0.0 do not have the colour property until the field is modified for the first time in each one. Any edit to the issue (from the UI, a transition, a bulk update, or an API change) triggers the automatic process and generates the colour property.
If you need all your issues to have the property immediately, you can update them in bulk using a Jira Automation rule or the API.
If an administrator modifies the field thresholds (for example, changes the red limit from 30 to 40), the colour property is not updated retroactively across all issues. The corrected colour will be calculated the next time each issue is saved.
Upgrade note
Colour band synchronisation requires additional permissions on the Jira API. When upgrading to v5.0.0 from an earlier version, run the following command in your Forge environment after deployment:
forge install --upgrade
Without this step, the add-on will not be able to write colour properties to issues.