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 work item 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.

From version 1.9.0, you can also search work items by colour with JQL using the trafficLightBand and percentageBand functions. See JQL search by colour band below.

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 a work item when a percentage indicator turns red.
• REST API — read the current field colour from an external integration without having to interpret thresholds.
• Filters, dashboards, and JSM queues — list the work items in red (or yellow, or green) with a JQL query, without repeating each context's 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.

How to find the field ID

Go to Jira Settings → Work items → 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 work item has never been saved since v5.0.0 was installed

When the field is cleared, the property is removed from the work item.

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 work item (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 work item 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 work item 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 work item, the API returns a 404 error.

JQL search by colour band

From version 1.9.0, two JQL functions find work items by the colour a Traffic Light KPI or Percentage Field shows:

Function	Field
trafficLightBand	Traffic Light KPI
percentageBand	Percentage Field

They work anywhere Jira accepts JQL: work item search, saved filters, dashboard gadgets based on a filter (for example, Filter Results or Two Dimensional Filter Statistics), and JSM queues.

Syntax

issue in trafficLightBand("red")                          -- red in ANY Traffic Light KPI field
issue in trafficLightBand("yellow", "customfield_10042")  -- one field, by ID
issue in trafficLightBand("green", "10042")               -- one field, by numeric ID
issue in trafficLightBand("red", "Delivery KPI")          -- one field, by name (must be unique)
issue not in trafficLightBand("red")                      -- everything that is not red (includes empty fields)
issue in percentageBand("red")                            -- same syntax for Percentage fields

• First argument (required): the band, "red", "yellow", or "green". Case-insensitive. The values are always these English words, whatever the user's language, so a saved filter returns the same results for everyone.
• Second argument (optional): the field, by ID ("customfield_10042"), by numeric ID ("10042"), or by name. If omitted, the function searches every field of that type on the site. If two fields share a name, use the ID.
• Operators: in and not in.

With two Traffic Light KPI fields on the site, issue in trafficLightBand("red", "customfield_10042") returns only the work items that are red in that field; without the second argument, it returns those that are red in either one.

Which work items match

• Every work item whose numeric value falls in the requested band matches, using the thresholds of the field context that applies to that work item (space / work type). The same value can be red in one space and yellow in another.
• No backfill needed: the functions don't read the colour property; they read the field value. So they also include work items created before upgrading to 1.9.0, or never saved again.
• An empty field matches no band. If a work item's field is cleared, it drops out of the filter.
• A Traffic Light KPI context without thresholds renders the indicator gray, so its work items match no band. Percentage contexts without saved thresholds use the defaults (40 / 70), like the bar.
• The field's numeric operators (=, !=, <, <=, >, >=, is EMPTY, is not EMPTY, in, not in) keep working as before. The functions are an additional option, not a replacement.

When a change shows up

• A work item's value changes: the work item moves to the filter of its new band once Jira indexes it. It usually takes a few seconds; this is standard Jira search behaviour, not a bug.
• A context's thresholds change: when the thresholds are saved, the app updates the searches within a few seconds. Affected work items move to their new band without having to be saved again.
• Spaces or work types are added to or removed from a context: Jira doesn't notify the app of this change; an automatic hourly refresh picks it up.

Limits

• Jira accepts at most 1,000 values (space IDs, work type IDs, and thresholds) in a function's result. On sites with many space-scoped contexts, pass the field as the second argument to narrow the search. If the limit is exceeded, the function returns an explicit error.
• Jira stores the internal result of each argument combination and drops it if it isn't used for 7 days; the next search computes it again. No administrator action is needed.

Error messages

If the query has an unknown band, a field that doesn't exist or is ambiguous, or an unsupported operator, Jira shows the error in the language of the user's profile. For example: "Only "in" and "not in" are supported, e.g. issue in trafficLightBand("red")."

Important limitations

The colour property is not searchable with JQL

The work item property itself (admin-essentials.traffic-light.{fieldId}.color) can't be used in a JQL clause: Jira Cloud only indexes properties with a fixed key, and these keys include the field ID. To search by colour, use the trafficLightBand and percentageBand functions, which don't depend on the property. The property is still the way to go for the Field Dependency validator, Jira Automation, and the REST API.

Existing work items without a colour property

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 work item (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 work items to have the property immediately, you can update them in bulk using a Jira Automation rule or the API.

This limitation doesn't affect the JQL colour functions, which read the field value.

Threshold changes are not retroactive

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 work items. The corrected colour will be calculated the next time each work item is saved.

The JQL colour functions do apply the new thresholds without the work items having to be 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 work items.