Stopwatch - Field setting reference


Overview

A Stopwatch field setting defines the rules for how a stopwatch accumulates time. You create and manage field settings in the admin panel > Stopwatch tab > Field Settings.

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


Form layout

The form has four tabs: General, Events, 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 all field setting forms. 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 \ / > < & %. Used to identify the setting in the admin panel and context configuration. 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 stopwatch 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/Stopped → Running Triggers that start or resume the stopwatch. From Stopped, a start opens a new cycle (unless Calculate type is Only first start).
Pause Events Running → Paused Triggers that pause the stopwatch
Stop Events Running/Paused → Stopped Triggers that stop the stopwatch
Restart Events Stopped → 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 available 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 stopwatch is already running is ignored. When on, it restarts the running stopwatch. Restart from Stopped always works, with or without this setting; restart from Paused always behaves as a resume.

What restart does to accumulated time

Restart does not blindly reset the counter - the effect depends on the state it fires from and on the Calculate type:

From state Effect
Paused Resume. Accumulated time is kept, nothing is reset.
Stopped A new cycle starts. RestartCount is incremented.
Running Only with Allow restart from any state: the current cycle is closed and a new one starts. RestartCount is incremented.

With All starts, a restart increments RestartCount and the new cycle is added to the running total - previously accumulated time is not discarded. Only Only last start drops the earlier cycles, so the field shows the time of the most recent cycle alone.

Calculate type

Determines how the stopwatch aggregates time when it restarts.

Value Description
All starts Accumulate time from all start-stop cycles. The total time is the sum of all running periods.
Only first start Only count the first start-stop cycle. Subsequent restarts are ignored for the total time.
Only last start Only count the most recent start-stop cycle. Previous cycles are discarded.

Calendar

Setting Description Default
Default Calendar The work calendar used for time calculation. Select a custom calendar to count only business hours. See Work calendars. Default 24x7
Calendar Select Field The calendar chosen on the issue in this Calendar Select field overrides the other calendars. None (use static calendar)
Calendar overrides Rules “JQL -> Rule calendar”: issues that match a rule are counted with its calendar. Rules are checked top to bottom, the first match 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 numbers for JQL down to the step of the format on
Rounding for display Cuts the shown value down to the step of the format (together with the option above) on

Display modes

Mode Shows
Time spent Time as text only (e.g., “2h 30m”)
Time spent + Icon Time with ▶️ after it while the stopwatch is running (e.g., “2h 30m ▶️”)
Icon + Time spent ▶️ before the time while the stopwatch is running (e.g., “▶️ 2h 30m”)
Pause time Accumulated pause time instead of active time

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 (a new name does not restart it) and shows:

  • Field on the issue - the field bound to this setting (or “not bound”) and its value;
  • How it was counted - the stopwatch state (Running, Paused, Stopped or Inactive), the number of restarts, and the counted and paused intervals with their dates and time (the last 20; the number of earlier ones is shown below);
  • 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, or a setting that is not bound. If the value cannot be calculated (for example, the calendar of the issue is not available), the preview says Not calculated and why.

While the form has errors that stop the calculation (for example, no start or stop event), 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. See Configuration changed.


Stopwatch states

State Description
Inactive Initial state. No events have triggered the stopwatch yet.
Running Stopwatch is actively accumulating time.
Paused Stopwatch is paused. Time does not accumulate.
Stopped Stopwatch is stopped. Final time is recorded.

State transitions

Inactive ──[Start]──→ Running
Running  ──[Pause]──→ Paused
Running  ──[Stop]───→ Stopped
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]───→ Stopped
Stopped  ──[Start]──→ Running (new cycle, unless Calculate type is Only first start)
Stopped  ──[Restart]→ Running (new cycle, no flag required)