대시보드 API - ServiceNow Fluent

  • 릴리스 버전: Australia
  • 업데이트 날짜 2026년 03월 12일
  • 소요 시간: 19분

    • 대시보드 API는 데이터를 시각적으로 구성하고 공유하기 위한대시보드 [par_dashboard]를 정의합니다.

    주:
    최신 ServiceNow Fluent API 설명서 및 예제는 ServiceNow Fluent API 참조 및 ServiceNow SDK 예제 리포지토리 는 의 위치에 있습니다 GitHub.

    대시보드는 탭, 위젯, 가시성 및 권한으로 구성됩니다. 각 탭에는 데이터 시각화, 제목, 서식 있는 텍스트 및 기타 구성요소를 표시하는 위젯이 있습니다.

    대시보드는 대시보드 개체의 가시성 배열에서 하나 이상의 작업 공간을 참조하여 작업 공간의 홈 페이지로 사용할 수 있습니다. 작업 공간을 생성하려면 다음 문서를 참조하십시오 작업 공간 API - ServiceNow Fluent.

    대시보드에 대한 일반적인 정보는 다음 문서를 참조하십시오Dashboards in Platform Analytics.

    대시보드 객체

    데이터 시각화, 필터, 탭, 위젯, 권한 및 가시성 규칙이 포함된 공유 가능한 대시보드[par_dashboard]를 생성합니다.

    표 1. 속성
    이름 유형 설명
    $id 문자열 또는 숫자 필수 메타데이터 객체의 고유 ID입니다. 애플리케이션을 빌드할 때 이 ID는 고유한 sys_id으로 해시됩니다. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.

    형식: Now.ID['문자열' 또는 숫자]
    이름 문자열 필수 대시보드에 표시할 이름입니다.
    활성 부울 대시보드가 활성 상태인지 여부를 나타내는 플래그입니다.

    기본값: true
    탭 배열 대시보드에 표시할 탭의 목록입니다. 자세한 내용은 탭 배열 문서를 참조하십시오.
    권한 배열 대시보드에 액세스하는 데 필요한 사용자 권한 목록입니다. 자세한 내용은 권한 배열 문서를 참조하십시오.
    가시성 배열 대시보드를 표시하는 UX 환경을 제어하는 가시성 규칙의 목록입니다. 자세한 내용은 가시성 배열 문서를 참조하십시오.

    기본값: 08c73d60537101100834ddeeff7b1287 sys_id 기본 가시성 규칙이 사용됩니다.
    $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['문자열' 또는 숫자]
    이름 문자열 필수 탭에 표시할 이름입니다.
    활성 부울 탭이 활성 상태인지 여부를 나타내는 플래그입니다.

    기본값: 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['문자열' 또는 숫자]
    구성요소 참조 또는 문자열 필수 위젯으로 표시할 구성요소의 이름(예: 선 또는 단일 점수) 또는 UX Macroponent 정의 [sys_ux_macroponent] 테이블의 구성요소 sys_id입니다.

    구성요소 이름은 대/소문자를 구분하지 않으며 빌드 프로세스 중에 해당 sys_ids로 해결됩니다.
    height 번호 필수 그리드 단위로 된 위젯의 높이입니다.
    width 번호 필수 그리드 단위로 된 위젯의 너비입니다.

    최대값: 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, 메트릭 및 groupBy 속성이 필요합니다. 이러한 시각화에서는 trendBy 속성이 지원되지 않습니다.
    • 단순 데이터 구성요소에는 dataSources 와 메트릭 속성이 필요합니다. 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: [
      {
        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]을 정의합니다.

    배열의 각 권한에 대해 사용자, 그룹 또는 역할 속성을 하나 이상 지정해야 합니다.

    표 5. 속성
    이름 유형 설명
    $id 문자열 또는 숫자 필수 메타데이터 객체의 고유 ID입니다. 애플리케이션을 빌드할 때 이 ID는 고유한 sys_id으로 해시됩니다. 자세한 내용은 ServiceNow Fluent 언어 구성 문서를 참조하십시오.

    형식: Now.ID['문자열' 또는 숫자]
    사용자 참조 또는 문자열 권한을 부여할 사용자 [sys_user]의 변수 식별자 또는 sys_id입니다. 사용자를 정의하려면 을 사용합니다 기록 API - ServiceNow Fluent.
    그룹 참조 또는 문자열 사용 권한을 부여할 사용자 그룹 [sys_user_group]의 변수 식별자 또는 sys_id입니다. 사용자를 정의하려면 을 사용합니다 기록 API - ServiceNow Fluent.
    role 참조 또는 문자열 권한을 부여할 역할 [sys_user_role]의 변수 식별자 또는 sys_id입니다. 사용자를 정의하려면 을 사용합니다 역할 API - ServiceNow Fluent.
    canRead 부울 사용자, 그룹 또는 역할이 대시보드를 볼 수 있는지 여부를 나타내는 플래그입니다.

    기본값: true
    canWrite 부울 사용자, 그룹 또는 역할이 대시보드를 편집할 수 있는지 여부를 나타내는 플래그입니다.

    기본값: false
    캔쉐어 부울 사용자, 그룹 또는 역할이 대시보드를 공유할 수 있는지 여부를 나타내는 플래그입니다.

    기본값: false
    소유자 부울 사용자, 그룹 또는 역할이 대시보드의 소유자인지 여부를 나타내는 플래그입니다. 한 명 이상의 사용자에 대해서는 소유자 속성을 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['문자열' 또는 숫자]
    경험 참조 또는 문자열 필수 작업 공간 객체의 변수 식별자 또는 UX 애플리케이션의 sys_id [sys_ux_page_registry]입니다. 자세한 내용은 작업 공간 API - ServiceNow Fluent 문서를 참조하십시오. 
    visibilities: [
  {
    $id: Now.ID["dashboard_visibility_1"],
    experience: myWorkspace // Reference to Workspace object
  }
]