Time in Status Field and timeExpression Function

This guide explains how to use the Time in Status custom field and the timeExpression JQL function to track and query time spent in various issue statuses.

Overview

The Time in Status Field is a custom field that automatically tracks how long issues spend in specific statuses. The timeExpression function converts human-readable time expressions (like "2w 3d 5h") into seconds for use in JQL queries.

Time in Status Custom Field

Creating the Field

1. Navigate to Custom Fields:

   • Go to Jira Settings → Issues → Custom Fields
   • Click Create Custom Field

2. Select Field Type:

   • Choose "Time in status field" from the available field types
   • This field type is provided by the Argon Powerful JQL Search app

3. Configure the Field:

   • Name: Give your field a descriptive name (e.g., "Time in Development", "Time in Review")
   • Description: Add a helpful description for your team
   • Click Create

   Important: After creating the field, you'll need to configure which statuses it tracks (see next section).

Configuring the Field

After creating the field, you must configure which statuses it should track:

1. Open Field Configuration:

   • Find your newly created field in the custom fields list
   • Click on the Configure button (gear icon) next to the field name

2. Select Statuses to Track:

   • You'll see a multi-select dropdown with all available statuses
   • Select one or more statuses that you want to track time for
   • Status options are organized by scope:
     • PROJECT [PROJECT_KEY] [Status Name]: Project-specific statuses (e.g., "PROJECT MYPROJ In Progress")
     • ALL PROJECTS [Status Name]: Global statuses available across all projects (e.g., "ALL PROJECTS Done")

3. Status Selection Strategy:

   • Single Status: Select only one status (e.g., "In Progress") to track time spent in that specific status
   • Multiple Statuses: Select multiple statuses (e.g., "In Progress", "In Review", "Testing") to track cumulative time across all selected statuses
   • Project-Specific: Choose project-specific statuses if you want to track time only for issues in particular projects
   • Global: Choose global statuses if you want to track time across all projects

4. Save Configuration:

   • Click Submit to save your status selection
   • Click Close to exit the configuration dialog

Adding Field to Screens

To make the field visible to users:

1. Navigate to Screens:

   • Go to Jira Settings → Issues → Screens

2. Select Screen:

   • Choose the screen where you want to display the field (e.g., "Default Screen", "View Issue Screen")

3. Add Field:

   • Click Add Field
   • Select your Time in Status field from the dropdown
   • Click Add

4. Position the Field:

   • Drag the field to your preferred position on the screen
   • Click Update

Field Display Format

The Time in Status field displays time in a human-readable format:

2w 3d 5h 30m 45s

Where:

• w = weeks
• d = days
• h = hours
• m = minutes
• s = seconds

timeExpression JQL Function

Purpose

The timeExpression function converts time expressions into seconds for use in JQL queries. It's commonly used with Time in Status fields to create time-based searches.

Syntax

timeExpression("time expression")

Time Expression Format

Time expressions support the following units:

Unit	Description	Example
w	Weeks	2w = 2 weeks
d	Days	3d = 3 days
h	Hours	5h = 5 hours
m	Minutes	30m = 30 minutes
s	Seconds	45s = 45 seconds

Compound Expressions

You can combine multiple time units in a single expression:

timeExpression("2w 3d 5h 30m 45s")

This represents: 2 weeks + 3 days + 5 hours + 30 minutes + 45 seconds

Using Time in Status Fields in JQL

Basic Syntax

To query a Time in Status field, use this format:

"Field Name.time" > timeExpression("time expression")

Important: The field name must be enclosed in quotes, and .time must be included.

Examples

Find issues that spent more than 2 weeks in development:

"Time in Development.time" > timeExpression("2w")

Find issues that spent between 1 and 3 days in review:

"Time in Review.time" > timeExpression("1d") AND "Time in Review.time" < timeExpression("3d")

Find issues that spent more than 8 hours in any status:

"Time in All Statuses.time" > timeExpression("8h")

Find issues that spent less than 30 minutes in testing:

"Time in Testing.time" < timeExpression("30m")

Complex time expressions:

"Time in Progress.time" > timeExpression("1w 2d 4h")

Supported Operators

You can use all standard JQL comparison operators:

• > (greater than)
• >= (greater than or equal)
• < (less than)
• <= (less than or equal)
• = (equals)
• != (not equals)

Combining with Other JQL

Time expressions work well with other JQL clauses:

project = "MYPROJECT" AND 
"Time in Progress.time" > timeExpression("1w") AND 
assignee = currentUser() AND 
status = "In Progress"

timeInStatus JQL Function

Purpose

The timeInStatus function finds issues that have spent a specific amount of time in a particular status, based on issue changelog data.

Syntax

issue > timeInStatus("subquery", "status", "time expression")

Parameters

• subquery (required): A JQL query defining which issues to evaluate
• status (required): The status name to track (must be a valid status in your Jira instance)
• time expression (required): Time expression in format like "2w 3d 5h 4m"

Examples

Find issues that spent more than 2 weeks in "In Progress":

issue > timeInStatus("project = MYPROJECT", "In Progress", "2w")

Find issues that spent less than 3 days in "To Do":

issue < timeInStatus("project = MYPROJECT", "To Do", "3d")

Find issues that spent exactly 5 hours in "In Review":

issue = timeInStatus("project = MYPROJECT", "In Review", "5h")

Find issues that spent between 1 and 5 days in "Blocked":

issue >= timeInStatus("project = MYPROJECT", "Blocked", "1d") AND 
issue <= timeInStatus("project = MYPROJECT", "Blocked", "5d")

Limitations

• Issue Limit: Maximum 2000 issues can be processed in a single query
• Performance: Processes issues in batches of 100 for optimal performance
• Status Validation: Status names are validated against your Jira instance

Important Considerations

1. Processing Delays

Time in Status fields will update within a minute after issue transitions between statuses. This means:

• Immediate queries after status changes may not reflect the latest data
• Wait 5-15 seconds, up to a minute after status transitions for accurate results
• Real-time reporting may show slight delays

2. Time Calculation

• Includes current time: If an issue is still in the tracked status, time includes up to the current moment
• Accumulates time: If an issue re-enters a status, time accumulates across all periods
• Based on changelog: Uses Jira's issue changelog for precise time tracking

3. Field Configuration

• Configuration Required: You must configure which statuses to track after creating the field - unconfigured fields will not work
• Read-only: Time in Status fields are automatically calculated and cannot be manually edited
• Status-specific: Each field can track different sets of statuses (single or multiple)
• Project-aware: Works across all projects where the field is available
• Scope Options: Can track project-specific statuses or global statuses across all projects

4. JQL Autocompletion

When typing JQL queries, Jira will show your Time in Status fields in autocompletion:

"Time in Development.time" > timeExpression("

The .time suffix will appear in the autocompletion dropdown.

Best Practices

1. Naming Conventions

Use descriptive field names that clearly indicate what they track:

• ✅ "Time in Development"
• ✅ "Time in Code Review"
• ✅ "Time in Testing"
• ❌ "Time Field 1"
• ❌ "Status Time"

2. Screen Placement

Place Time in Status fields in logical locations:

• View screens: Show time tracking information to all users
• Edit screens: Generally not needed since fields are read-only
• Transition screens: Can be helpful during status changes

3. Query Optimization

• Use specific subqueries: Narrow down the issue set to improve performance
• Combine with filters: Use project, assignee, or date filters to reduce processing
• Avoid overly broad queries: Stay within the 2000 issue limit

4. Time Expressions

• Be specific: Use appropriate time units for your context
• Consider business hours: Remember that tracking includes weekends and holidays
• Test expressions: Verify your time calculations match expected results

Troubleshooting

Common Issues

1. Field shows null values:

   • Most Common: Check if the field has been configured with statuses (click Configure button on the field)
   • Check if the issue has been in the tracked status
   • Verify webhook processing has completed (wait 10-15 seconds)
   • Ensure the field is configured for the correct statuses

2. JQL query returns no results:

   • Verify the field name is correct and enclosed in quotes
   • Check that .time is included in the field reference
   • Ensure the time expression is valid

3. "Invalid status" errors:

   • Confirm the status name exists in your Jira instance
   • Check for typos in status names
   • Ensure the status is available in the relevant project

4. Performance issues:

   • Reduce the scope of your subquery
   • Use more specific filters
   • Consider breaking large queries into smaller ones

Getting Help

If you encounter issues:

1. Check field configuration: Ensure the field is properly configured and added to relevant screens
2. Verify JQL syntax: Use Jira's JQL validator or test queries in the issue navigator
3. Review logs: Check if there are any error messages in the Jira logs
4. Contact administrator: Your Jira administrator can help with field configuration and troubleshooting

Examples Gallery

Development Team Scenarios

// Find issues stuck in code review for more than 2 days
"Time in Code Review.time" > timeExpression("2d")

// Find issues that moved through development quickly (< 4 hours)
"Time in Development.time" < timeExpression("4h")

// Find issues that spent significant time in testing
"Time in Testing.time" > timeExpression("1w")

Support Team Scenarios

// Find tickets that waited too long for first response
"Time in Open.time" > timeExpression("4h")

// Find tickets resolved quickly (< 30 minutes)
"Time in Progress.time" < timeExpression("30m")

// Find tickets that were blocked for extended periods
"Time in Blocked.time" > timeExpression("3d")

Management Reporting

// Issues that spent more than 1 week in any status
"Time in All Statuses.time" > timeExpression("1w")

// Issues with quick turnaround times
"Time in All Statuses.time" < timeExpression("2d")

// Issues that got stuck in review process
"Time in Review.time" > timeExpression("3d")

This documentation provides comprehensive guidance for using Time in Status fields and the timeExpression function effectively in your Jira instance.