Timer - Field setting reference


Overview

A Timer field setting defines the rules for how a timer counts toward its goal, like an SLA: it starts, pauses and stops on the events you choose. Create and manage field settings in the admin panel > Timer tab > Field Settings.

Each field setting is bound to one or more field contexts.


Form layout

The form has five tabs: General, Events, Goals, Calendar and Display. A tab with errors is marked (has errors); on Save the form opens the first such tab.

The header button switches the form between One column and Two columns; your browser remembers the choice, and it is the same for the forms of the other fields. The second column is the Preview. In a narrow window (for example 1024 px with the Jira sidebar open) the preview goes under the form even in the two-column layout.

An on/off option (for example Is active) is a toggle under the name of the option: the toggle shows the state, the name stays the same.


General

Setting Description Default
Name Unique name of the setting, up to 150 characters, without \ / > < & %. empty
Is active A disabled setting stops all value updates. on
Issue date limit Only issues created or updated on or after this date are calculated. Leave empty for all issues. empty: the field shows No limit
JQL filter Only issues that match this JQL are calculated. Up to 4000 characters, without ORDER BY. empty

Events

Event triggers control when the timer changes state. At least one start or stop event is required. Defaults: no events, Allow restart from any state off, Calculate type All starts.

Slot Effect Description
Start Events Inactive/Paused/Completed/Failed → Running Triggers that start or resume the timer. From a stopped state (Completed or Failed) a start opens a new cycle, unless Calculate type is Only first start.
Pause Events Running → Paused Triggers that pause the timer
Stop Events Running/Paused → Completed Triggers that complete the timer (if within goal)
Restart Events Completed/Failed → Running (new cycle); Paused → Running (resume) Triggers that begin a new run. Restart from Running requires Allow restart from any state.

See Event triggers reference for all trigger types.

Allow restart from any state

Setting Description
Allow restart from any state Controls restart from the Running state only. When off (default), a restart trigger that fires while the timer is already running is ignored. When on, it closes the current cycle and starts a new one. Restart from a stopped state (Completed or Failed) always works, with or without this setting; restart from Paused always behaves as a resume, keeping the accumulated time.

Which cycles end up in the value is decided by Calculate type: with All starts a restart increments RestartCount and the new cycle is added to the running total, while Only last start discards the earlier cycles and shows the most recent one alone.

Calculate type

Value Description
All starts Accumulate time from all start-stop cycles.
Only first start Only count the first cycle.
Only last start Only count the most recent cycle.

Goals

Goals define the target time for the timer. See Timer goal configuration for full details.

Default goal is required. Its Goal time source is one of:

Goal time source Goal
Static time A fixed time, for example 8h, 2d 4h, 1w. Units: y, M (month), w, d, h, m, s. A day here is 24 hours of counted time and a week 168 hours, whatever the calendar.
End of next business day Working time from the start until the end of the next business day of the calendar. Without a work calendar (24x7) every day is a business day: the goal ends at the end of the next calendar day in the site’s time zone, which is UTC in this app.
DateTime field value Working time from the start until the date in a date or date-time field of the issue. A date without time (Due date, a custom Date field) means the end of that day in the time zone of the calendar; without a calendar time zone - in the site’s time zone, which is UTC in this app.

Each goal can have its own Calendar and Calendar Select Field.

Additional Goals apply a different goal to issues that match a JQL condition, for example priority = High. Goals are checked top to bottom (drag to reorder) and the first match wins; an issue that matches none gets the default goal. The JQL condition is required; up to 10 additional goals.

A deadline that has already passed puts the timer in Failed at once, and a goal that cannot be resolved leaves the timer running with no goal side at all - see Timer goal configuration.

Goals are always re-evaluated when the timer is recalculated - there is no setting to freeze a goal. If issue data changes so that a different additional goal matches (for example, its priority changed), the timer picks up the new goal on the next calculation.

Calendar used for an issue, from the first that is set: the goal’s Calendar Select field, the goal’s calendar, the setting’s Calendar Select field, the setting’s default calendar.


Calendar

Setting Description Default
Default Calendar Work calendar for time calculation. Default 24x7
Calendar Select Field Optional Calendar Select field for per-issue override. None (use static calendar)
Calendar overrides Rules “JQL -> Rule calendar”: issues that match a rule are counted with its calendar. The first matching rule wins; up to 10 rules. no rules

Calendar override priority (highest to lowest):

  1. Calendar Select field value on the issue
  2. Calendar overrides (calendar of the first matching JQL rule)
  3. Default calendar
  4. 24x7, when nothing above resolves to a calendar

Display

Setting Values Default
Display mode See Display modes Time spent
Time format One of the time formats 13h 48m 03s
Use rounding for display Cuts the shown value down to the step of the format on

Display modes

Mode Shows
Time spent Time spent (e.g., “2h 30m”)
Left time Time remaining until the goal; never below 0
Goal time The goal
Time spent + Icon, Left time + Icon, Goal time + Icon The same value with ▶️ after it while the timer is counting
Icon + Time spent, Icon + Left time, Icon + Goal time The same value with ▶️ before it while the timer is counting
Pause time Accumulated pause time
Failed date The time left until the goal is missed, then the moment it was missed

Preview

Next to the form, enter an issue key to see the value the unsaved setting gives on that issue. The key is remembered for this setting, including the key entered while the setting was created. The preview updates by itself half a second after a change (the name does not count) and shows:

  • Field on the issue - the field bound to this setting (or “not bound”) and its value;
  • How it was counted - the state of the timer, time spent, time left, time on pause, the moment the goal was missed, the goal applied to the issue (an additional goal or the default goal) and its time, or why the goal cannot be computed for this issue, and the intervals of counting and pauses;
  • whether the value would be written on this issue at all: an inactive setting, a JQL filter mismatch, the issue date limit, a project excluded from the app, an issue outside the bound field contexts, a setting that is not bound, or a calendar, goal condition or status categories that could not be read.

While the form has errors that change the calculation (no events, no default goal, a goal without JQL), the preview asks to fix them first. The preview writes nothing.


After you change a setting

When you save a change that changes the values, the app opens the Configuration changed window: Recalculate now or Later. A change of the name needs no recalculation; a change of the goals starts the recalculation by itself. See Configuration changed.


Timer states

State Description
Inactive No events have triggered the timer.
Running Timer is actively counting.
Paused Timer is paused.
Completed Timer stopped within goal time - or stopped while no goal was in force at all.
Failed Elapsed time exceeded goal time, or the resolved deadline is already in the past.

State transitions

Inactive   ──[Start]──→ Running
Running    ──[Pause]──→ Paused
Running    ──[Stop]───→ Completed (if time <= goal)
Running    ──[time > goal]→ Failed
Running    ──[Restart]→ Running (new cycle, only with Allow restart from any state)
Paused     ──[Start]──→ Running (resume)
Paused     ──[Restart]→ Running (resume, accumulated time is kept)
Paused     ──[Stop]───→ Completed
Completed  ──[Start]──→ Running (new cycle, unless Calculate type is Only first start)
Completed  ──[Restart]→ Running (new cycle, no flag required)
Failed     ──[Start]──→ Running (new cycle, unless Calculate type is Only first start)
Failed     ──[Restart]→ Running (new cycle, no flag required)
Failed     ──[Stop]───→ Failed (state unchanged, but stop event recorded)