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, progress percentages, risks, or other indicators where the numeric value matters but, above all, 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 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", "Response SLA").
   • Add an optional Description. This text appears below the field to guide users.

6. Click Create.

7. Associate with screens: Jira will ask you to select the screens where the field will appear (create, edit, view). Select the appropriate ones and click Update.

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

Values without threshold configuration

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

Configure Thresholds (Per Context)

Traffic Light thresholds are always associated with the active field configuration context (FieldConfigContext). This means you can define different thresholds per project or issue type, depending on the contexts you have created for the field.

Threshold Model

Each context requires two numeric values:

• 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.

The applied rule 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)

"Higher is better" semantics

In this version the model assumes higher values are better (for example: test coverage, progress percentage, NPS). If your KPI works the other way around (where a low value is desirable, for example: response time or number of incidents), model the thresholds by inverting the meaning of the range or use an intermediate calculation. A native "lower is better" mode is planned for future releases.

Invariant

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

Steps to Configure 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 provided by this add-on.
4. In 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 Red max value.
   • Enter the Yellow max value.
   • Click Save.

After saving you will return to the field configuration page and the Thresholds row will show the new summary. Issues associated with that context will begin rendering the indicator with the corresponding colors.

Example: Compliance KPI (0–100)

Suppose a Traffic Light field named "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).

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

Possible Validation Errors

The editor validates input and shows specific messages when:

• Either field 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; usually occurs when opening the form via an expired 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) accompanied by 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 (fields side panel).
• The issue navigator column view, gadgets, and boards (compact mode, ideal for listings).

Search Support (Searcher) and JQL

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

• Filter issues by value from basic search (equals, 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 when creating the field.

JQL operates on the value, not the color

JQL queries operate on the stored numeric value, not the resolved color. To list, for example, "all red issues" combine JQL operators with the same context thresholds: "Compliance level" <= 30.

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

Internationalization (i18n)

All administrative and interface texts for the Traffic Light field (field name, configuration row, threshold form, error messages, and accessible labels) are internationalized and respect the Jira user's language, with Spanish and English support included in the package.