ダッシュボード API - ServiceNow Fluent

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間：21分

    • ダッシュボード API は、データを視覚的に整理および共有するためのダッシュボード [par_dashboard] を定義します。

    注:
    最新の ServiceNow Fluent API ドキュメントと例については、 ServiceNow Fluent API リファレンス および ServiceNow SDK のサンプルリポジトリ ( GitHub)。

    ダッシュボードは、タブ、ウィジェット、可視化、および権限で構成されます。各タブには、データの可視化、見出し、リッチテキスト、およびその他のコンポーネントを表示するウィジェットが含まれています。

    ダッシュボードは、ダッシュボードオブジェクトの可視化アレイから 1 つ以上のワークスペースを参照することによって、ワークスペースのホームページとして使用できます。 ワークスペースを作成するには、「 ワークスペース API - ServiceNow Fluent」を参照してください。

    ダッシュボードに関する一般的な情報については、「Dashboards in Platform Analytics」を参照してください。

    ダッシュボードオブジェクト

    データの可視化、フィルター、タブ、ウィジェット、権限、およびヴィジビリティルールを含む共有可能なダッシュボード [par_dashboard] を作成します。

    表 : 1. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    name 文字列 必須。ダッシュボードに表示する名前。
    アクティブ ブール ダッシュボードがアクティブかどうかを示すフラグ。

    デフォルト：true
    タブ アレイ ダッシュボードに表示するタブのリスト。詳細については、「タブアレイ」を参照してください。
    permissions アレイ ダッシュボードへのアクセスに必要なユーザー権限のリスト。詳細については、「権限アレイ」を参照してください。
    ヴィジビリティ アレイ ダッシュボードを表示する UX エクスペリエンスを制御するヴィジビリティルールのリスト。詳細については、「ヴィジビリティアレイ」を参照してください。

    デフォルト:sys_id 08c73d60537101100834ddeeff7b1287 のデフォルトのヴィジビリティルールが使用されます。
    $meta オブジェクト アプリケーションメタデータのメタデータ。
    installMethod プロパティを使用すると、特定の状況でのみロードされる出力ディレクトリにアプリケーションメタデータをマップできます。
    $meta: {
      installMethod: 'String'
}
    installMethod の有効な値:
    • demo:[デモデータのロード] オプションが選択されている場合、アプリケーションメタデータを metadata/unload.demo ディレクトリに出力して、アプリケーションとともにインストールします。
    • 初回インストール:アプリケーションがインスタンスに初めてインストールされたときにのみインストールされるように 、アプリケーションメタデータをメタデータ/アンロード ディレクトリに出力します。
    		 
    import { Dashboard } from "@servicenow/sdk/core";

Dashboard({
  $id: Now.ID["incident_management_dashboard"],
  name: "Incident Management Dashboard",
  tabs: [
    {
      $id: Now.ID["incident_overview_tab"],
      name: "Overview",
      widgets: [
        // Single Score: Total Open Incidents
        {
          $id: Now.ID["total_open_incidents_widget"],
          component: "single-score",
          componentProps: {
            dataSources: [
              {
                label: "Incident",
                sourceType: "table",
                tableOrViewName: "incident",
                filterQuery: "",
                reportSourceSysId: "d94d6f62d7632100b96d45a3ce6103d2",
                id: "dGFibGVpbmNpZGVudDE3NjMzOTI0OTY5ODE="
              }
            ],
            headerTitle: "Open Incidents",
            metrics: [
              {
                dataSource: "dGFibGVpbmNpZGVudDE3NjMzOTI0OTY5ODE=",
                id: "ZEdGaWJHVnBibU5wWkdWdWRERTNOak16T1RJME9UWTVPREU9MTc2MzM5MjQ5Nzc5OQ==",
                aggregateFunction: "COUNT",
                axisId: "primary"
              }
            ],
            sortBy: "value"
          },
          height: 14,
          width: 14,
          position: { x: 0, y: 0 }
        },
        // Vertical Bar: Incidents by Priority
        {
          $id: Now.ID["incidents_by_priority_widget"],
          component: "vertical-bar",
          componentProps: {
            dataSources: [
              {
                label: "Incident",
                sourceType: "table",
                tableOrViewName: "incident",
                filterQuery: "",
                reportSourceSysId: "d94d6f62d7632100b96d45a3ce6103d2",
                id: "dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA="
              }
            ],
            headerTitle: "Incidents by Priority",
            metrics: [
              {
                dataSource: "dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA=",
                id: "ZEdGaWJHVnBibU5wWkdWdWRERTNOakkzT1RVNE9UZzNOREE9MTc2Mjc5NTg5OTM5OA==",
                aggregateFunction: "COUNT",
                axisId: "primary"
              }
            ],
            groupBy: [
              {
                groupBy: [
                  {
                    dataSource: "dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA=",
                    groupByField: "priority"
                  }
                ],
                maxNumberOfGroups: 10,
                numberOfGroupsBasedOn: "NO_OF_GROUP_BASED_ON_PER_METRIC",
                showOthers: false,
                disableRanges: false
              }
            ],
            sortBy: "value"
          },
          height: 14,
          width: 17,
          position: { x: 14, y: 0 }
        },
        // Vertical Bar: Incidents by State
        {
          $id: Now.ID["incidents_by_state_widget"],
          component: "vertical-bar",
          componentProps: {
            dataSources: [
              {
                label: "Incident",
                sourceType: "table",
                tableOrViewName: "incident",
                filterQuery: "",
                reportSourceSysId: "d94d6f62d7632100b96d45a3ce6103d2",
                id: "dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA="
              }
            ],
            headerTitle: "Incidents by State",
            metrics: [
              {
                dataSource: "dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA=",
                id: "ZEdGaWJHVnBibU5wWkdWdWRERTNOakkzT1RVNE9UZzNOREE9MTc2Mjc5NTg5OTM5OA==",
                aggregateFunction: "COUNT",
                axisId: "primary"
              }
            ],
            groupBy: [
              {
                groupBy: [
                  {
                    dataSource: "dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA=",
                    groupByField: "state"
                  }
                ],
                maxNumberOfGroups: 10,
                numberOfGroupsBasedOn: "NO_OF_GROUP_BASED_ON_PER_METRIC",
                showOthers: false,
                disableRanges: false
              }
            ],
            sortBy: "value"
          },
          height: 14,
          width: 17,
          position: { x: 31, y: 0 }
        }
      ]
    },
    {
      $id: Now.ID["incident_trends_tab"],
      name: "Trends",
      widgets: [] // Can be populated later or left empty
    }
  ],
  visibilities: [
    {
      $id: Now.ID["incident_dashboard_visibility"],
      experience: incidentWorkspace
    }
  ],
  permissions: []
})
    参照されるワークスペースは、 ワークスペース オブジェクトを使用して定義されます。
    import { Workspace } from "@servicenow/sdk/core";

export const myWorkspace = Workspace({
  $id: Now.ID["my_workspace"],
  title: "My Workspace",
  path: "my-workspace",
  tables: ["incident"],
  listConfig: myListConfig
})

    タブアレイ

    ダッシュボードのウィジェットを含むタブ [par_dashboard_tab] を作成します。

    ダッシュボード内では、タブはアレイ内の位置に基づいて順序付けされます。

    表 : 2. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    name 文字列 必須。タブに表示する名前。
    アクティブ ブール タブがアクティブかどうかを示すフラグ。

    デフォルト：true
    ウィジェット アレイ タブに表示するウィジェットのリスト。詳細については、「ウィジェットアレイ」を参照してください。 
    tabs: [
    {
      $id: Now.ID["my_dashboard_tab1"],
      name: "Overview",
      widgets: [
        {
          $id: Now.ID["my_dashboard_widget_1"],
          component: "single-score",
          componentProps: {
            dataSources: [
              {
                label: "Incident",
                sourceType: "table",
                tableOrViewName: "incident",
                filterQuery: "",
                reportSourceSysId: "d94d6f62d7632100b96d45a3ce6103d2",
                id: "dGFibGVpbmNpZGVudDE3NjMzOTI0OTY5ODE="
              }
            ],
            headerTitle: "Open Incidents",
            metrics: [
              {
                dataSource: "dGFibGVpbmNpZGVudDE3NjMzOTI0OTY5ODE=",
                id: "ZEdGaWJHVnBibU5wWkdWdWRERTNOak16T1RJME9UWTVPREU9MTc2MzM5MjQ5Nzc5OQ==",
                aggregateFunction: "COUNT",
                axisId: "primary"
              }
            ],
            sortBy: "value"
          },
          height: 14,
          width: 14,
          position: { x: 0, y: 0 }
        }
      ]
    }
]

    ウィジェットアレイ

    グリッドレイアウトのタブ内にウィジェット [par_dashboard_widget] を作成します。

    ダッシュボードは、ウィジェットの配置に 48 ポイントのグリッドシステムを使用します。

    表 : 3. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    component 参照または文字列 必須。ウィジェットとして表示するコンポーネントの名前 (線や単一スコアなど) または UX macroponent 定義 [sys_ux_macroponent] テーブルからのコンポーネントのsys_id。

    コンポーネント名は大文字と小文字を区別せず、ビルドプロセス中にsys_idsに解決されます。
    高さ 番号 必須。ウィジェットの高さ (グリッド単位)。
    幅 番号 必須。ウィジェットの幅 (グリッド単位)。

    最大値:48
    位置 オブジェクト 必須。x および y プロパティを持つグリッドレイアウト内のウィジェットの位置。たとえば、 値が { x: 0, y: 0 } の場合、ウィジェットはグリッドの左上隅に配置されます。
    componentProps オブジェクト コンポーネントのプロパティ構成。詳細については、「componentProps オブジェクト」を参照してください。 
    widgets: [
              {
                  $id: Now.ID['incident-count-chart'],
                  component: 'vertical-bar', // Vertical bar chart
                  componentProps: {
                      title: 'Incident Count',
                      dataSource: 'incident',
                      aggregation: 'count'
                  },
                  height: 8,
                  width: 6,
                  position: { x: 0, y: 0 },
              },
              {
                  $id: Now.ID['recent-incidents-list'],
                  component: 'list', // List component
                  componentProps: {
                      table: 'incident',
                      filter: 'active=true',
                      limit: 10,
                      columns: ['number', 'short_description', 'priority', 'state']
                  },
                  height: 8,
                  width: 6,
                  position: { x: 6, y: 0 },
              }
          ],
      },
      {
          $id: Now.ID['analytics'],
          name: 'Analytics',
          widgets: [
              {
                  $id: Now.ID['metrics-widget'],
                  component: 'single-score', // Single score component
                  componentProps: {
                      title: 'Key Metrics',
                      scoreSize: 'large'
                  },
                  height: 12,
                  width: 12,
                  position: { x: 0, y: 0 },
              }
]

    componentProps オブジェクト

    ウィジェット [par_dashboard_widget] のプロパティを設定します。

    使用可能なプロパティは、ダッシュボードオブジェクトのコンポーネントプロパティで指定されたコンポーネントによって決まります。

    • 傾向データコンポーネントには、 dataSources、 metrics、および trendBy プロパティが必要です。groupBy プロパティはオプションです。
    • グループデータコンポーネントには、 dataSource、 metrics、および groupBy プロパティが必要です。これらの可視化では、 trendBy プロパティはサポートされていません。
    • 単純なデータコンポーネントには、 dataSources プロパティと metrics プロパティが必要です。groupBy プロパティと trendBy プロパティは、これらの可視化ではサポートされていません。
    表 : 4. プロパティ
    名前 タイプ 説明
    データソース アレイ コンポーネントのデータソースのリスト。たとえば、次のようになります：
    dataSources: [
  {
    label: "Incident", // Human-readable label
    sourceType: "table", // Type of data source
    tableOrViewName: "incident", // ServiceNow table name
    filterQuery: "", // Optional encoded query filter
    id: "data_source_1" // Unique data source ID
  },
...
]
    headerTitle 文字列 ウィジェットとともに表示するタイトル。
    メトリクス アレイ データソースについて測定するメトリクスのリスト。たとえば、次のようになります：
    metrics: [
    {
        dataSource: 'data_source_1',  // Must match dataSource id
        id: 'metric_1',  // Unique metric ID
        aggregateFunction: 'AVG',  // COUNT, SUM, AVG, MIN, MAX, COUNT_DISTINCT
        aggregateField: 'business_duration'  // Field to be used for aggregation.
        axisId: 'primary',  // Which axis to display the series
    },
...
]
    groupBy アレイ データをデータソース別にグループ化および整理するための構成のリスト。たとえば、次のようになります：
    groupBy: [
  {
    groupBy: [
      {
        dataSource: "data_source_1", // Must match dataSource id
        groupByField: "state" // Field to group by
      }
    ],
    maxNumberOfGroups: 10, // Maximum categories to show
    showOthers: false // Show "Others" category
  },
...
]
    傾向別 オブジェクト 傾向図の構成。たとえば、次のようになります：
    trendBy: {
  "trendByFrequency": "year", // Frequency of the trend (date, week, month, year)
  "trendByFields": [
    {
      "field": "sys_created_on", // Field to trend on (from the table of the dataSource)
      "metric": "metric_1" // ID of the metric
    }
  ]
}
    sortBy 文字列 データをソートする方法。
    有効な値：
    • 値
    • ラベル
    • フィールド
    次の例では、傾向データタイプの可視化である 線コンポーネント を使用して、メトリクスが時間の経過とともにどのように変化するかを示しています。
    {
    component: 'line',
    componentProps: {
        dataSources: [
            {
                label: 'Incident',
                sourceType: 'table',
                tableOrViewName: 'incident',
                filterQuery: '',
                id: 'data_source_1',
            },
        ],
        headerTitle: 'Incidents by State',
        metrics: [
            {
                dataSource: 'data_source_1',
                id: 'metric_1',
                aggregateFunction: 'COUNT',
                axisId: 'primary',
            },
        ],
        trendBy: {
            trendByFrequency: "year",
            trendByFields: [
                {
                    field: "sys_created_on",
                    metric: "metric_1"
                }
            ]
        },
    },
    height: 14,
    width: 17,
    position: { x: 0, y: 0 },
}
    次の例では、単純なデータタイプの可視化である 単一スコア コンポーネントを使用して、単一のカウントメトリクスを示しています。
    {
    component: 'single-score',
    componentProps: {
        dataSources: [
            {
                label: 'Incident',
                sourceType: 'table',
                tableOrViewName: 'incident',
                filterQuery: '',
                id: 'data_source_1',
            },
        ],
        headerTitle: 'Open Incidents',
        metrics: [
            {
                dataSource: 'data_source_1',
                id: 'metric_1',
                aggregateFunction: 'COUNT',
                axisId: 'primary',
            },
        ]
    },
    height: 14,
    width: 14,
    position: { x: 0, y: 0 },
}

    権限アレイ

    ダッシュボードを読み取り、編集、および共有するための権限 [par_dashboard_permission] を定義します。

    アレイ内の権限ごとに、 ユーザー、 グループ、または ロール のプロパティの少なくとも 1 つを指定する必要があります。

    表 : 5. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    user 参照または文字列 権限を付与するユーザー [sys_user] の変数識別子またはsys_id。ユーザーを定義するには、 レコード API - ServiceNow Fluentを使用します。
    グループ 参照または文字列 権限を付与するユーザーグループ [sys_user_group] の変数識別子またはsys_id。ユーザーを定義するには、 レコード API - ServiceNow Fluentを使用します。
    ロール 参照または文字列 権限を付与するロール [sys_user_role] の変数識別子またはsys_id。ユーザーを定義するには、 ロール API - ServiceNow Fluentを使用します。
    canRead ブール ユーザー、グループ、またはロールがダッシュボードを表示できるかどうかを示すフラグ。

    デフォルト：true
    canWrite ブール ユーザー、グループ、またはロールがダッシュボードを編集できるかどうかを示すフラグ。

    デフォルト値：false
    canShare ブール ユーザー、グループ、またはロールがダッシュボードを共有できるかどうかを示すフラグ。

    デフォルト値：false
    所有者 ブール ユーザー、グループ、またはロールがダッシュボードの所有者であるかどうかを示すフラグ。少なくとも 1 人のユーザーについては、 owner プロパティを true に設定する必要があります。

    デフォルト値：false

    		 
    permissions: [
        {
            $id: Now.ID['manager-user-permission'],
            user: 'a8f98bb0eb32010045e1a5115206fe3a', // sys_id of manager user
            canRead: true,
            canWrite: true,
            owner: true,
        },
        {
            $id: Now.ID['itil-role-permission'],
            role: '2831a114c611228501d4ea6c309d626d', // sys_id of itil role
            canRead: true,
            canWrite: false,
        },
        {
            $id: Now.ID['support-group-permission'],
            group: 'd625dccec0a8016700a222a0f7900d06', // sys_id of Service Desk group
            canRead: true,
            canWrite: false,
        }
]

    ヴィジビリティアレイ

    UX エクスペリエンスにダッシュボードが表示される可視化ルール [par_dashboard_visibility] を定義します。

    表 : 6. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    エクスペリエンス 参照または文字列 必須。ワークスペースオブジェクトの変数識別子または UX アプリケーションのsys_id [sys_ux_page_registry]。詳細については、「ワークスペース API - ServiceNow Fluent」を参照してください。 
    visibilities: [
  {
    $id: Now.ID["dashboard_visibility_1"],
    experience: myWorkspace // Reference to Workspace object
  }
]