Skip to main content

Date Handling and UTC Expectations

Overview​

All dates used in this system—whether as input, output, or in API calls—are expected to be in UTC (Coordinated Universal Time). This applies to:

  • JQL queries
  • API parameters
  • Function arguments (including scheduled triggers)
  • Test data

Why UTC?​

  • Consistency: UTC avoids ambiguity and errors caused by time zone differences, daylight saving changes, or local system settings.
  • Interoperability: Jira and most cloud services store and process dates in UTC.
  • Testing: UTC-based tests are reliable and reproducible regardless of where or when they are run.

Best Practices​

  • Always generate and store dates in UTC.
  • When formatting dates for JQL or API calls, use UTC.
  • When parsing date strings, assume they are in UTC unless explicitly specified.
  • Do not use local time or user time zones for system logic or data storage.

Examples​

JavaScript: Creating a UTC Date​

const nowUtc = new Date(); // JS Date is UTC by default
const utcString = nowUtc.toISOString(); // '2025-07-04T13:58:00.000Z'

Formatting for JQL (UTC)​

function toJqlUtcString(date) {
  // Returns 'YYYY/MM/DD HH:mm' in UTC
  const pad = n => n.toString().padStart(2, '0');
  return `${date.getUTCFullYear()}/${pad(date.getUTCMonth()+1)}/${pad(date.getUTCDate())} ` +
         `${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}`;
}

Test Data​

  • When writing tests, always use UTC dates and times.
  • If you need a specific moment, use an ISO string with 'Z' (e.g., '2025-07-04T13:58:00.000Z').

What if a date is not in UTC?​

  • The system will attempt to parse and convert, but this may lead to errors or unexpected results.
  • Always prefer UTC to avoid ambiguity.

Summary​

All dates must be in UTC.

If you have questions about date handling or need help converting dates, contact the maintainers or see the utility functions in src/utils/date-utils.jsx.