一覧へ戻る
ITSM

ServiceNow における日付フォーマットの取得：保存値（Internal Value）と表示値（Display Value）の使い分け

ServiceNow のサーバーサイドスクリプトでは、現在日時を取得し、用途に応じて適切なフォーマットで出力・表示する処理が頻繁に求められます。本記事では、標準 API である GlideDateTime および GlideDate を活用し、今日の日付を 「MM-dd-yyyy」 形式で取得する方法と、実務で最も重要な 「保存値」 と 「表示値」 の違いについて解説します。

■ 日付・日時 API の基本

ServiceNow では、扱うデータの種類に応じて以下の 2 つのクラスを使い分けます。

  • GlideDate: 日付（年月日）のみを扱う場合に適しています。
  • GlideDateTime: 日付に加え、時刻（タイムスタンプ）まで扱う場合に使用します。

実装コード例

✅ 方法①：getByFormat() による特定形式の取得（連携・ロジック用）

外部システムとの連携や、特定の固定フォーマットが必要なバッチ処理などで使用します。

var gdt = new GlideDateTime();
// 内部値を元に、指定したフォーマット（月-日-年）の文字列に変換
var formattedDate = gdt.getDate().getByFormat("MM-dd-yyyy");

// 出力例：04-14-2026
gs.info("フォーマット済み日付: " + formattedDate);

✅ 方法②：getDisplayValue() による表示値の取得（ユーザー表示用）

ユーザーのプロファイル設定（タイムゾーンや日付形式）に合わせて自動変換された値が必要な場合に使用します。

var gdt = new GlideDateTime();

// 内部値ベース（固定フォーマット）
var formattedDate = gdt.getDate().getByFormat("MM-dd-yyyy");
gs.info("フォーマット済み日付: " + formattedDate);

// ユーザー表示（タイムゾーン反映）
gs.info("ユーザー表示形式: " + gdt.getDisplayValue());
ServiceNowの日付フォーマットとユーザー表示形式の違い（getByFormatとgetDisplayValueの比較）
同じ日時から取得しているにも関わらず、getByFormat()（内部値）とgetDisplayValue()（ユーザー表示）で結果が異なることが確認できます。

同じ日時を元にしているにも関わらず、出力結果が異なることが確認できます。

これは、
・getByFormat() → 内部値（UTC基準）
・getDisplayValue() → ユーザーのタイムゾーンという違いによるものです。

保存値（Internal Value）と表示値（Display Value）の比較

ServiceNow の日付処理においてバグを防ぐための最も重要なポイントは、「システム内部での保持形式」 と 「ユーザーへの表示形式」 を明確に区別することです。

  • 保存値 (Internal Value / UTC)
    • 基準: 常に UTC（協定世界時） です。
    • 用途: データベースへの保存、システム間のデータ連携、日付計算、ログ出力など。
    • メソッド: getValue(), getByFormat() など。
  • 表示値 (Display Value / Local Time)
    • 基準: ユーザーのタイムゾーン および インスタンスの表示設定 です。
    • 用途: 画面上のメッセージ表示、通知メール、レポート、フォーム上の値表示など。
    • メソッド: getDisplayValue(), getDisplayValueInternal() など。

まとめ

日付処理の実装において、「MM」と「mm」の指定ミス と並んで多いトラブルが、このタイムゾーンの考慮漏れです。

  • システム外部へデータを渡す際は、必ず UTC 基準の保存値（Internal Value） をベースに getByFormat() などで整形してください。
  • ユーザー向けのメッセージを作成する際は、混乱を避けるために getDisplayValue() を使用して、ユーザー個々の設定に基づいた日時を表示してください。

👉 ServiceNow の日付処理の極意は、「DB に保存された UTC の値」 と 「画面に表示されるローカルの値」 を分けて考えることにあります。この 2 つを混同しないことが、プロフェッショナルな開発者への第一歩です。