Time Between Dates field


What is a Time Between Dates field?

A Time Between Dates field calculates the elapsed working time between two date or datetime fields on an issue. The field is purely based on date field values: no events are involved.

Common use cases:

  • Created to Resolved - how long from issue creation to resolution
  • Due Date to Resolved - whether issues are resolved before their due date
  • Committed date vs Delivered date - delivery accuracy
  • Any two custom date fields - flexible SLA and metric tracking

Creating the field

  1. Go to Jira Settings > Issues > Custom fields
  2. Click Create custom field
  3. Select Time Between Dates from the field type list
  4. Enter a name (e.g., “Resolution Time”, “Delivery Accuracy”)
  5. Choose the field context
  6. Click Create

Field setting reference

Create and manage field settings in the admin panel > Time Between Dates tab.

Form layout

The form has four tabs: General (Name, Is active, Issue date limit, JQL filter), Dates (Start field, End field, Absolute value), Calendar (Default Calendar, Calendar Select Field) and Display (Display mode, Time Format, rounding). 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 (Is active, Absolute value, rounding) is a toggle under the name of the option: the toggle shows the state, the name stays the same.

General

Setting Description Default
Name 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

Dates

Setting Description Default
Start field The date or date-time field where the period starts. Current Date Time (the current moment) turns the field into a countdown - see Countdown / SLA mode below. Created
End field The date or date-time field where the period ends. Current Date Time makes the field grow continuously. Current Date Time
Absolute value Applies when both fields are issue dates. When on, the dates are swapped if the start is after the end, so the result is always positive. When off, a pair of dates in the wrong order produces no value: the field goes Inactive rather than showing a negative number. When one side is Current Date Time, the order is handled automatically and this setting has no effect. off

Start field and End field list every date and date-time field of the site and Current Date Time. The two fields must be different, and they cannot both be Current Date Time. 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.

Countdown / SLA mode

Setting Start field to Current Date Time and End field to a date on the issue - a due date, a delivery date, a custom deadline - reverses the direction of the calculation: the field measures from now until that date and shrinks as the date approaches. This is the countdown, or SLA, mode of Time Between Dates.

Two things follow from it:

  • The field recalculates continuously, the same way it does when Current Date Time is the end field.
  • Once the target date is in the past, the field stays Active and keeps counting: time left is shown as 0, time spent shows how much working time has passed since the date, and the LeftTimeSeconds property turns negative by that overrun. Search for LeftTimeSeconds < 0 to find issues past their deadline - see JQL search. Use Absolute Value does not change this.

Calendar

Setting Description Default
Default Calendar Only working time of the calendar is counted. Default 24x7
Calendar Select Field The calendar chosen on the issue in this Calendar Select field overrides the calendar above. None (use static calendar)

Display

Setting Values Default
Display mode See Display modes Goal time
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

The goal of a Time Between Dates field is not a separate setting: it is the working time between the start and end dates, counted by the field’s calendar. Time spent is the part of that interval already behind the current moment, time left is the part still ahead. With Current Date Time as the end field, time spent and goal both equal the time since the start date. In countdown mode, time spent stays 0 until the target date and then shows the overrun.

Mode Shows
Goal time Working time of the whole period between the two dates; in a countdown it shrinks as the date comes closer
Time spent The part of the period that has passed (e.g., “2d 4h”)
Left time The part still ahead (0 once the end has passed)
Time spent / Goal time Elapsed / goal (e.g., “2d / 5d”)
Time spent + Icon, Left time + Icon, Time spent / Goal time + Icon The same value with ▶️ after it while the period is active
Icon + Time spent, Icon + Left time, Icon + Time spent / Goal time The same value with ▶️ before it while the period is active

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 Start and End fields with their dates on the issue (“now” for Current Date Time, “not set” when there is no period), the state, the time between the dates, the time spent and the time left. When there is no period (a date is empty, or the start is after the end and Absolute value is off), the preview says so;
  • 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 that could not be read.

While the form has errors that change the calculation (no Start or End field, the same field on both sides, Current Date Time on both sides, a JQL filter with ORDER BY), 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.


Binding to a field context

After creating the field and field setting:

  1. Go to Jira Settings > Issues > Custom fields
  2. Find your Time Between Dates field and click … (more actions) > Contexts and default value
  3. In the block of the context, open Custom field config and click Edit custom field config (the context name itself is not a link)
  4. Select the field setting in the app panel and save
  5. Values for existing issues of the context are calculated in the background; see Recalculation

See Field context configuration for details.


Tips

  • Current Date Time as end field: use this to create a continuously updating field that shows “time since Created” or “time since a custom date.”
  • Current Date Time as start field: the mirror image - a countdown to a due date or deadline. See Countdown / SLA mode.
  • Absolute value: enable this when the order of two issue dates is uncertain (e.g., comparing two custom dates where either could be first). Without it, a reversed pair leaves the field Inactive instead of producing a negative value. Settings with Current Date Time do not need it.
  • Calendar matters: without a calendar, all 24 hours count. With a business-hours calendar, weekends and non-working time are excluded.