日付と時刻を操作する

ワークフローのルールは、多くの場合、日付と時刻に依存します。期日前にユーザーに通知したり、フォローアップの日付を設定したり、課題が進行中の期間を計算したり、作業項目が間違った日付で記録された場合に更新を停止したりできます。

JavaScript ワークフローでは、ほとんどの日付と時刻の値はミリ秒単位の Unix タイムスタンプとして表現されます。つまり、Date.now()、日付および日時カスタムフィールド、created、updated、resolved などの課題プロパティによって返される値は、数値として比較できます。

日付と時刻の値

ワークフロー規則では、以下の値が一般的に使用されます。

値	説明
`Date.now()`	現在の Unix タイムスタンプをミリ秒単位で返します。
課題のプロパティ	`created`、`updated`、`resolved` プロパティにはタイムスタンプが格納されます。`resolved` プロパティは、未解決の課題の場合は空になります。
日付カスタムフィールド	`date` 型のカスタムフィールドには、選択されたカレンダー日付のタイムスタンプが格納されます。YouTrack で日付が選択されると、格納されているタイムスタンプはその日付の UTC（協定世界時）である 12:00 に正規化されます。
日付と時刻のカスタムフィールド	`date and time` 型のカスタムフィールドには、ユーザーが選択した、またはワークフローによって割り当てられた正確なタイムスタンプが格納されます。
期間別カスタムフィールド	`period` 型のカスタムフィールドには、期間値が格納されます。期間値を作成するには `date-time` モジュールを使用し、その構成要素を読み取るには期間オブジェクトのメソッドを使用します。
作業項目の日付	作業項目の日付はタイムスタンプとしても利用可能です。`Date.now()` と比較したり、JavaScript の `Date` オブジェクトで正規化したりできます。

ルールでカスタムフィールドの読み取りまたは書き込みを行う場合は、ルール要件で対応するフィールドタイプを使用してください。

        requirements: {
          DueDate: {
            type: entities.Field.dateType,
            name: 'Due Date'
          },
          Reminder: {
            type: entities.Field.dateTimeType,
            name: 'Reminder'
          },
          Estimation: {
            type: entities.Field.periodType
          }
        }
    

日付を比較する

日付と日時値はタイムスタンプであるため、関係演算子を使用して比較できます。比較する前に、オプション値が存在するかどうかを必ず確認してください。

        const entities = require('@jetbrains/youtrack-scripting-api/entities');

        exports.rule = entities.Issue.onSchedule({
            title: 'Find overdue issues',
            search: '#Unresolved has: {Due Date}',
            cron: '0 0 10 ? * MON-FRI',
            guard: (ctx) => {
                const dueDate = ctx.issue.fields.DueDate;
                return dueDate && dueDate < Date.now();
            },
            action: (ctx) => {
                ctx.issue.addComment('This issue is overdue.');
            },
            requirements: {
                DueDate: {
                    type: entities.Field.dateType,
                    name: 'Due Date'
                }
            }
        });
    

次の例では、作業項目が 1 週間以上前の日付で追加されたかどうかを確認します。両方の値は、比較対象の前の UTC 日の開始時点を基準として正規化されています。

        const entities = require('@jetbrains/youtrack-scripting-api/entities');
        const workflow = require('@jetbrains/youtrack-scripting-api/workflow');

        const WEEK_IN_MS = 7 * 24 * 60 * 60 * 1000;

        exports.rule = entities.Issue.onChange({
          title: 'Reject old work items',
          guard: (ctx) => {
            return ctx.issue.workItems.added.isNotEmpty();
          },
          action: (ctx) => {
            const today = new Date().setUTCHours(0, 0, 0, 0);
            ctx.issue.workItems.added.forEach((item) => {
              const itemDate = new Date(item.date).setUTCHours(0, 0, 0, 0);
              workflow.check(itemDate >= today - WEEK_IN_MS,
                  'Adding work more than one week in the past is not allowed.');
            });
          },
          requirements: {}
        });
    

値の解析とフォーマット

ワークフロー API には @jetbrains/youtrack-scripting-api/date-time モジュールが含まれています。このモジュールは、ユーザーが入力したテキストを解析したり、メッセージや検索クエリのタイムスタンプをフォーマットしたり、ピリオドを加算または減算して日付を計算したりする必要がある場合に使用します。

標準の JavaScript メソッド Date.parse() の代わりに dateTime.parse() を使用してください。このワークフローメソッドでは、1 つ以上の想定フォーマットとオプションのタイムゾーンを渡すことができます。

        const dateTime = require('@jetbrains/youtrack-scripting-api/date-time');

        const start = dateTime.parse(
            '2026-05-15 09:00',
            'yyyy-MM-dd HH:mm',
            'Europe/Lisbon'
        );
    

dateTime.format() を使用すると、メッセージの読みやすい日付を作成したり、検索クエリ用に特定の形式の日付を作成したりできます。

        const formatted = dateTime.format(ctx.issue.fields.DueDate, 'yyyy-MM-dd');
        const withTimeZone = dateTime.format(Date.now(), 'yyyy-MM-dd HH:mm', 'America/New_York');
    

フォーマットやタイムゾーンを指定しない場合、YouTrack は現在のユーザープロファイルの値を使用します。ワークフローユーザーによって実行されるアクションの場合、YouTrack はグローバル日付フォーマットとデフォルトのタイムゾーンを使用します。

周期の加算と減算

Date.now() + 10 hours のような式は使用しないでください。JavaScript は周期リテラルをサポートしていません。固定ミリ秒オフセットには数値を使用するか、周期を考慮した計算には date-time モジュールを使用してください。

単純な固定間隔の場合は、間隔をミリ秒単位で定義します。

        const DAY_IN_MS = 24 * 60 * 60 * 1000;

        ctx.issue.fields.DueDate = Date.now() + 2 * DAY_IN_MS;

期間として表現すべき間隔には、dateTime.after() と dateTime.before() を使用します。期間文字列は、週、日、時間、分を含むコンパクトな形式を使用します。

        const dateTime = require('@jetbrains/youtrack-scripting-api/date-time');

        const threeHoursFromNow = dateTime.after(Date.now(), '3h');
        const twoDaysBeforeDueDate = dateTime.before(ctx.issue.fields.DueDate, '2d');
        const fullPeriod = dateTime.after(Date.now(), '2w4d3h15m');
    

期間カスタムフィールドから読み取った、または dateTime.toPeriod() で作成した期間値を渡すこともできます。

期間フィールドの操作

期間フィールドには、値を期間オブジェクトとして格納します。期間フィールドに値を割り当てるには、ミリ秒数または期間文字列を dateTime.toPeriod() を使用して変換します。

        const entities = require('@jetbrains/youtrack-scripting-api/entities');
        const dateTime = require('@jetbrains/youtrack-scripting-api/date-time');

        exports.rule = entities.Issue.onChange({
            title: 'Set default estimation',
            guard: (ctx) => {
                return ctx.issue.isReported && !ctx.issue.fields.Estimation;
            },
            action: (ctx) => {
                ctx.issue.fields.Estimation = dateTime.toPeriod('1d4h');
            },
            requirements: {
                Estimation: {
                    type: entities.Field.periodType
                }
            }
        });
    

期間値を用いて計算を行う必要がある場合は、getWeeks()、getDays()、getHours()、getMinutes() などのメソッドを使用してその構成要素を読み取ります。以下のヘルパー関数は、1 週間あたり 5 営業日、1 日あたり 8 労働時間という一般的なデフォルト値を使用して、期間値を分に変換します。

        function periodToMinutes(period) {
          return period ? period.getMinutes() +
              60 * (period.getHours() +
                  8 * (period.getDays() +
                      5 * period.getWeeks())) : 0;
        }
    

YouTrack インスタンスで異なるタイムトラッキング設定を使用している場合は、変換を作業週と作業日に合うように調整してください。

作業時間を計算する

プロジェクトの作業時間に含まれる分数を計算する場合は、Project.intervalToWorkingMinutes() を使用してください。これは、デフォルトの作業タイマーワークフローで使用される方法です。

        const started = ctx.issue.fields.TimerTime;
        const duration = ctx.issue.project.intervalToWorkingMinutes(started, Date.now());
    

開始タイムスタンプに SLA 形式の業務時間を追加する必要がある場合は、Issue.afterMinutes() を使用します。この方法は、プロジェクトの SLA カレンダーや 24 時間 365 日対応カレンダーなどのカレンダーを使用します。

        const entities = require('@jetbrains/youtrack-scripting-api/entities');

        const calendar = ctx.issue.project.slaCalendar;
        ctx.issue.fields.FirstReply = ctx.issue.afterMinutes(
            ctx.issue.created,
            60,
            calendar,
            true
        );

        ctx.issue.fields.NextReply = ctx.issue.afterMinutes(
            Date.now(),
            30,
            entities.Calendar24x7.instance(),
            false
        );
    

ヒント

日付または日時フィールドとの直接比較や割り当てには、タイムスタンプを使用してください。
日付がテキスト入力または外部サービスから取得される場合は、dateTime.parse() を使用してください。
コメント、通知、検索クエリに日付を追加する前に、dateTime.format() を使用してください。
期間フィールドに値を割り当てる前に、dateTime.toPeriod() を使用してください。
作業時間を考慮した作業タイマー計算には、Project.intervalToWorkingMinutes() を使用してください。
営業時間カレンダーを遵守する必要がある SLA スタイルの計算には、Issue.afterMinutes() を使用してください。

2026 年 9 月 10 日

YouTrack および Hub ヘルプの開発者ポータル