YouTrack InCloud 2017.3 Help

Working with Dates and Times

When you write workflow rules, especially on-schedule rules and scheduled transitions in state-machine rules, you use conditions that evaluate dates, periods, and durations. JavaScript does not support a strict date data type. Instead, you work with dates and times using the Date object and its methods.

YouTrack stores time-related data in formats that can be compared strictly with other time-related values. This time-related information can be referenced in the following contexts:

Data TypeContextDescription
Date Date.now() A static method that returns the number of milliseconds elapsed since the UNIX epoch. This represents the current date and time in UTC.
Issue fieldThe 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.
Custom fieldA 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 literalA 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.

PeriodCustom fieldA custom field that uses the period data type.
Period literalA period constant value. Represented by an integer and the time period. For example, 1 week.
Duration[date] - [date] operationA 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 that is returned by the Date.now() method.

  • 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:

var entities = require('@jetbrains/youtrack-scripting-api/entities'); exports.rule = entities.Issue.onSchedule({ title: 'Notify assignees when an issue is due today', search: '#Unresolved has: Assignee', cron: '0 0 8 * * ?', action: function(ctx) { var issue = ctx.issue; if (issue.fields.DueDate < Date.now()) { var userToNotify = issue.fields.Assignee; var notificationText = *'Please fix this issue today.' + ' <a href="' + issue.url + '">' + issue.summary + '</a><p style="color: gray;font-size: 12px;margin-top: 1em;border-top: 1px solid #D4D5D6">' + 'Sincerely yours, YouTrack' + '</p>'); userToNotify.notify('[YouTrack, Issue is Due Today]', notificationText); } }, requirements: { DueDate: { type: entities.Field.dateType, name: "Due Date" }, Assignee: { type: entities.User.fieldType } } });

The cron property for an on-schedule rule uses the time zone setting for your YouTrack server. The issue.fields.DueDate references a custom field that stores the date and time as 12:00 UTC.

  • If your office is in Seattle (UTC-7), the value returned by the Date.now() method at 08:00 is equivalent to 15:00. The initial if statement 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 returned by the Date.now() method 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 if statement would look something like this:
    if (issue.fields.DueDate < 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 OperationReturnsRelational OperationReturns
date + perioddatedate < dateBoolean
date + durationdatedate > dateBoolean
date - perioddatedate <= dateBoolean
date - durationdatedate >= dateBoolean
date - datedurationdate == dateBoolean

Additional Methods for Working with Dates and Times

The workflow API includes its own module for working with dates and times. Here, you will find additional methods that let you work with date-related values.

For more information, see .

Last modified: 18 August 2017