Traffic Light KPI Custom Field

The Traffic Light KPI custom field lets you store a numeric value per issue and display it as a visual indicator in three colors — 🔴 red, 🟡 yellow and 🟢 green — resolved from configurable thresholds per context.

It is designed to represent KPIs, service levels, response times, completion percentages, risks or any other indicator where the numeric value matters but, above all, where it is important to communicate at a glance whether the situation is good, intermediate or critical.

This section describes how to create the field, configure thresholds for each context and understand the indicator's behavior.

Create the Traffic Light field

1. Navigate to Jira Administration > Issues.

2. In the left sidebar, under Fields, click Custom fields.

3. Click Add custom field in the upper-right corner.

4. On the "Select a field type" screen, open the Advanced category and select Traffic Light KPI. Click Next.

   💡 You will recognize it by its description: "Numeric field that renders a colored indicator (red/yellow/green) based on configurable thresholds per context." and by its preview image (the three traffic-light bulbs).

   

5. Name and Description:

   • Enter a Name for the field (for example, "Compliance level", "Project risk", "Service SLA").
   • Add an optional Description. This text will appear below the field to guide users.

6. Click Create.

7. Associate it with screens: Jira will ask you to select the screens on which the field will appear (creation, edit, view). Check the ones that apply and click Update.

From this point on, the field will be available on the configured screens. However, the indicator will not display colors yet: to enable them you must configure the thresholds on each field context (next section).

Values without configured thresholds

While a field context has no thresholds defined, the stored numeric values are rendered in gray (no state). This is intentional: it avoids communicating a color that could lead to wrong interpretations until the administrator defines the business rule.

Configure thresholds (per context)

The Traffic Light field thresholds are always tied to the active configuration context (FieldConfigContext) of the field. This means you can define different thresholds per project or per issue type, according to the contexts you have created on the field.

Thresholds model

Each context requires two numeric values and an interpretation mode:

• Red max — Maximum value considered red. Any value less than or equal to this threshold renders a red indicator.
• Yellow max — Maximum value considered yellow. Values greater than Red max and less than or equal to Yellow max render yellow. Values greater than Yellow max render green.
• Lower is better — Optional checkbox that inverts the color assignment when the KPI works the other way around (a low value indicates better performance).

The rule applied in the default mode (higher is better) is:

Issue value	Resulting color
value <= Red max	🔴 Red
Red max < value <= Yellow max	🟡 Yellow
value > Yellow max	🟢 Green
Empty value / context without thresholds	⚪ Gray (no state)

When Lower is better is enabled, the assignment is inverted without changing the order of the thresholds:

Issue value	Resulting color
value <= Red max	🟢 Green
Red max < value <= Yellow max	🟡 Yellow
value > Yellow max	🔴 Red
Empty value / context without thresholds	⚪ Gray (no state)

When to enable "lower is better"?

Enable it on KPIs where a lower value indicates a better result: resolution time, number of incidents, open defects, average response time, etc. In those cases, the indicator will show green for low (desirable) values and red for high (critical) values, without having to manually invert the meaning of the thresholds.

Invariant

The editor enforces: Red max < Yellow max. If you enter values that do not respect this relation, the form will reject the save with an error message.

Steps to configure the thresholds

1. Navigate to Jira Administration > Issues > Custom fields.
2. Locate the Traffic Light field you created and click the actions icon (⋯) > Configure.
3. On the field configuration page you will see the list of associated contexts. For each context an additional row called Thresholds is contributed by this add-on.
4. On the Thresholds row:
   • If the context has no thresholds yet, you will see the text "No thresholds configured. Values render gray."
   • If thresholds are already defined, you will see a summary such as "Red max: 30 — Yellow max: 70".
5. Click Edit to the right of the Thresholds row.
6. In the Edit Traffic Light KPI Thresholds form:
   • Enter the value for Red max.
   • Enter the value for Yellow max.
   • Check the Lower is better box if your KPI works the other way around (low values = good performance).
   • Click Save.

After saving, you will return to the field configuration page and the Thresholds row will show the new summary. The summary also indicates the active mode (for example, "Red max: 30 — Yellow max: 70 — Lower is better"). Issues associated with that context will start to render the indicator with the corresponding colors.

Example: compliance KPI (0–100)

Consider a Traffic Light field called "Compliance level" expressed as a percentage:

• Red max: 30 → from 0 to 30 is considered critical (red).
• Yellow max: 70 → from 31 to 70 is considered at risk (yellow).
• Greater than 70 → adequate compliance (green).
• Lower is better: disabled (higher values are better).

If the same field is reused across several projects with different tolerances, just create one context per project and define independent thresholds in each one.

Example: average resolution time ("lower is better" mode)

For a Traffic Light field called "Resolution time (hours)", where a low value is desirable:

• Red max: 4 → from 0 to 4 hours is considered excellent (green).
• Yellow max: 12 → from 5 to 12 hours is considered acceptable (yellow).
• Greater than 12 → slow response (red).
• Lower is better: enabled.

Note that the thresholds keep the Red max < Yellow max order; the semantics change is provided by the Lower is better option.

Possible validation errors

The editor validates input and shows specific messages when:

• Any of the fields is empty → "This field is required."
• The entered value is not a valid number → "Please enter a valid number."
• Red max is greater than or equal to Yellow max → "Red max must be strictly less than Yellow max."
• The context cannot be resolved (uncommon case; usually happens when opening the form from a stale URL) → "The field configuration could not be located. Please return to the custom field configuration page and try again."

Rendering on the issue view

When an issue has a numeric value stored in the Traffic Light field and its context has thresholds defined, the add-on renders a three-bulb indicator (green, yellow, red) along with the field's numeric value. The lit bulb reflects the color resolved by the thresholds and an accessible aria-label describes the state for screen readers.

The indicator appears in:

• The issue detail view (lateral field panel).
• The column view of the issue navigator, gadgets and boards (compact mode, ideal for listings).

Thresholds legend on the issue view

Starting with this version, the issue detail view includes a descriptive legend below the indicator showing the ranges configured in the context. The legend automatically adapts to the active mode:

• In the default mode, it shows the increasing ranges (≤ Red max in red, Red max < … ≤ Yellow max in yellow, > Yellow max in green).
• In Lower is better mode, the ranges remain the same but the color assignment reflects the inversion.

The legend is rendered with texts in the user's language and respects Jira's theme (light and dark mode).

Hover tooltip

When hovering over the color indicator, a tooltip is shown with the exact range the issue value belongs to (for example, "Red: ≤ 30" or "Green: > 70"). This allows interpreting the state at a glance without having to open the field configuration.

Dark mode compatibility

The legend, the tooltip and the indicator's numeric value are rendered with accessible colors in both Jira's light and dark themes. The contrast of the number remains readable in both modes.

Search support (searcher) and JQL

The Traffic Light field is registered with Jira's standard Number Range Searcher, which enables searches and filters by numeric range. This allows you to:

• Filter issues by value from the basic issue search (equal, greater than, less than, etc.).

• Use the field in JQL queries, for example:

  "Compliance level" < 30
  "Compliance level" >= 70 AND project = "ACME"

  where Compliance level is the name you assigned to the field when creating it.

Values are indexed automatically as issues are created or updated; no additional configuration is required.

Filtering Traffic Light zones with JQL

JQL searches the stored numeric value of the field, not the rendered color. This means there is no syntax like "My Field" = "RED": to locate issues in the red, yellow or green zone you need to translate the zone into a numeric range using the thresholds of the active configuration context.

Why by context and not by color?

The color shown on each issue is the result of comparing the numeric value against the thresholds of the configuration context the issue belongs to. If the same field is used across several projects with different thresholds, the numeric range that represents "red" is different in each context. It is not possible to write a single JQL query that means "all red issues" across the entire instance when the field has contexts with different thresholds.

Built-in JQL examples in the threshold editor

Starting with version 1.3.0, the Edit Traffic Light KPI Thresholds editor includes a help block with ready-to-use JQL queries. The queries are generated automatically from:

• The real field name as registered in Jira.
• The Red max and Yellow max values entered in the form.

The queries update live as you change the thresholds or toggle the Lower is better option.

To copy a query, click the Copy button next to each zone. The copied query is ready to be pasted directly into the issue search or any saved filter.

Dark mode compatibility

The JQL help block uses Atlassian Design System color tokens, so it adapts automatically to Jira's light and dark themes with no additional configuration.

JQL templates

If you need to build queries outside the editor, use the following templates. Replace <FieldName> with the field name and <LOW> / <HIGH> with the Red max and Yellow max values of the context you are targeting.

Default mode (higher is better):

Zone	JQL expression
🔴 Red	"<FieldName>" <= <LOW>
🟡 Yellow	"<FieldName>" > <LOW> AND "<FieldName>" <= <HIGH>
🟢 Green	"<FieldName>" > <HIGH>

Inverted mode (Lower is better enabled): The numeric ranges are the same, but the color meaning of the extreme zones is swapped.

Zone	JQL expression
🟢 Green	"<FieldName>" <= <LOW>
🟡 Yellow	"<FieldName>" > <LOW> AND "<FieldName>" <= <HIGH>
🔴 Red	"<FieldName>" > <HIGH>

Practical example

Consider a field called "Customer Health" with Red max = 30 and Yellow max = 70 (default mode):

"Customer Health" <= 30                                         → Red zone
"Customer Health" > 30 AND "Customer Health" <= 70              → Yellow zone
"Customer Health" > 70                                          → Green zone

If another context of the same field has Red max = 50 and Yellow max = 80, the first query would return wrong results for that context. Each query is specific to the context from which the thresholds originate.

How to find the thresholds for a context

Navigate to Jira Administration > Issues > Custom fields, locate the Traffic Light KPI field and click Configure. In the Thresholds column for each context you will find the threshold summary (e.g. "Red max: 30 — Yellow max: 70"). You can also open the editor to see the automatically generated queries and copy them with a single click.

Known limitation

There is no mechanism in Jira Data Center that indexes the calculated Traffic Light color as an independent searchable field. The only way to filter by zone is to use numeric ranges with the thresholds of the target context. If you need a global color search (e.g. "all red issues across every project"), you will need to run one query per context with different thresholds and combine the results.

Internationalization (i18n)

All administrative and UI texts of the Traffic Light field (field name, configuration row, thresholds form, error messages, accessible labels and the new JQL help block) are internationalized and respect the Jira user's language, with English and Spanish support included in the package.