Working with Dates and Times

When you write workflow rules, especially scheduled rules and scheduled transitions in state-machine rules, you use conditions that evaluate dates, periods, and durations. This time-related information can be referenced in the following contexts:

Data Type	Context	Description
Date	`now`	This keyword literal value references the current date and time in UTC.
	Field	The issue fields `created`, `updated`, and `resolved` store values as date data types. These values are stored as the actual date and time the action took place. These fields use the default timezone setting of your YouTrack server.
	CustomField	A custom field that uses the `date` data type that was created in the YouTrack user interface. When a value is set for a custom field in YouTrack, the time value is set to 12:00 UTC for the specified date. When the value is set outside of YouTrack - for example, by workflow, an integration with TeamCity (assembleDate), or by the REST API, the value is set to the actual date and time.
	Date literal	A date that is specified as a literal value in the format: `year-month-day`. For example, `2016-Jan-01`. You can specify the time of day in the format `hour-minute-second`. This value can be added to a date literal with the `T` operation. For example, `2016-Jan-01 T 12:00:00`.
Period	CustomField	A custom field that uses the `period` data type.
Period	Period literal	A period constant value. Represented by an integer and the time period. For example, `1 week`.
Duration	[date] - [date] operation	A duration is only returned when combining two dates with the `-` operator.

How Soon is Now?

When you write workflow rules that compare dates, take note of the actual times that are stored in each field, how they compare to date constants, and the value of the keyword now.

Dates that are stored in custom fields that are created in YouTrack are assigned a date value with the time as 12:00 UTC.
If you set the value of a custom field outside of YouTrack, the field stores the actual time value that is assigned to the field. This includes values that are assigned to custom fields by a workflow, an integration with TeamCity (assembleDate), or by the REST API.
Dates that are stored in issue fields are assigned a value that corresponds to the instant when the action took place in the time zone that is set for your YouTrack server.
Scheduled rules run according to the server clock.

Let's take a look at the following example:

You want to notify users of issues that need to be resolved in the current working day. You write a rule that looks identifies issues by due date. You want to notify users before they arrive in the office, so you schedule the rule to run at 08:00. Your rule would look something like this:

schedule rule Check for Due date and notify assignee

daily at 08 : 00 : 00 [issue.Due date <= now] {
    issue.Assignee.notify("Issue is due today", "Please resolve the following issue:" + issue.getId());
}

The schedule uses the date constant 08 : 00 : 00, which uses the time zone setting for your YouTrack server. The issue.Due date references a custom field that stores the date and time as 12:00 UTC.

If your office is in Seattle (UTC-7), the value of now at 08:00 is 15:00. The guard expression resolves to [<current date> 12:00:00 <= <current date> 15:00:00], which is true. You could use the rule as it is written.
If your office is in Sydney (UTC+10), the value of now at 08:00 is 22:00 for the previous day. The guard expression resolves to [<current date> 12:00:00 <= <previous date> 22:00:00], which is false.
To notify users of issues that are due today, you must offset one of the values. The modified guard expression would look something like this: [issue.Due date <= (now + 10 hours)]. The due date for issues that are due today would exactly match the value that is returned by the expression.

Operators and Time-related Values

Arithmetic and relational operators can be used with dates, periods, and durations. The data type that is returned by the operator varies based on the combination of data types.

Arithmetic Operation	Returns	Relational Operation	Returns
date + period	date	date < date	Boolean
date + duration	date	date > date	Boolean
date - period	date	date <= date	Boolean
date - duration	date	date >= date	Boolean
date - date	duration	date == date	Boolean

Last modified: 7 March 2019