--- sourceDocument: Australia Build or modify applications sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/pt-BR/application-development Release : - australia ft:locale : - pt-BR ft:publication_title : - Australia Build or modify applications ft:clusterId : - cadev bundleId : - cadev workflow : - Development, Data, and Analytics --- # Dashboard API - ServiceNow Fluent # Dashboard API - ServiceNow Fluent {#ariaid-title1} * Versão de lançamento: Australia * * Atualizado 12 de mar. de 2026 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 9 min. de leitura The Dashboard API defines dashboards \[par_dashboard\] for organizing and sharing data visually. A dashboard consists of tabs, widgets, visibilities, and permissions. Each tab contains widgets that display data visualizations, headings, rich text, and other components. Dashboards can be used as the home page of a workspace by referencing one or more workspaces from the visibilities array of the Dashboard object. To create a workspace, see [Workspace API - ServiceNow Fluent](https://servicenow-prod.fluidtopics.net/so9VwOOsxlzVdnKOsZZybQ#fluent-workspace-api "The Workspace API defines configurable workspace experiences for organizing and sharing data visually."). For general information about dashboards, see [Dashboards in Platform Analytics](https://www.servicenow.com/docs/access?context=analytics-center-dashboards&version=australia&pubname=australia-now-intelligence&ft:locale=en-US).{#fluent-dashboard-api__fluent-api-general-info} **Conceitos relacionados** * [ServiceNow Fluent](https://servicenow-prod.fluidtopics.net/pP6OxbNArnr2tlBRkmrTfw "Define application metadata in source code using the ServiceNow Fluent domain-specific programming language.") ## Dashboard object {#ariaid-title2} Create a shareable dashboard \[par_dashboard\] with data visualizations, filters, tabs, widgets, permissions, and visibility rules. {#fluent-dashboard-object__table_i5f_wpy_23c__entry__3}{#fluent-dashboard-object__now-id-desc2} | Name | Type | Description | |-|-|-| | $id | String or Number | Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see [ServiceNow Fluent language constructs](https://servicenow-prod.fluidtopics.net/b1y7cW0gok5uzbNJ5JcSTw "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). Format: `Now.ID['String' or Number]` | | name | String | Required. A name to display for the dashboard. | | active | Boolean | Flag that indicates whether the dashboard is active. Default: true | | tabs | Array | A list of tabs to display in the dashboard. For more information, see [tabs array](https://servicenow-prod.fluidtopics.net/iElEm17uzIIeByDYaLSo9A#fluent-dashboard-tabs-array "Create tabs [par_dashboard_tab] that contain widgets for a dashboard."). | | permissions | Array | A list of user permissions required to access the dashboard. For more information, see [permissions array](https://servicenow-prod.fluidtopics.net/iElEm17uzIIeByDYaLSo9A#fluent-dashboard-permissions-array "Define permissions [par_dashboard_permission] to read, edit, and share a dashboard."). | | visibilities | Array | A list of visibility rules that control which UX experiences display the dashboard. For more information, see [visibilities array](https://servicenow-prod.fluidtopics.net/iElEm17uzIIeByDYaLSo9A#fluent-dashboard-visibilities-array "Define visibility rules [par_dashboard_visibility] for which UX experiences display the dashboard."). Default: A default visibility rule with sys_id 08c73d60537101100834ddeeff7b1287 is used. | | $meta | Object | Metadata for the application metadata. With the installMethod property, you can map the application metadata to an output directory that loads only in specific circumstances. $meta: { installMethod: 'String' } Valid values for installMethod: * demo: Outputs the application metadata to the metadata/unload.demo directory to be installed with the application when the Load demo data option is selected. * first install: Outputs the application metadata to the metadata/unload directory to be installed only the first time an application is installed on an instance. {#fluent-dashboard-object__ul_n3q_y3s_42c} | [Tabela 1. Properties] {#fluent-dashboard-object__table_i5f_wpy_23c} import { Dashboard } from '@servicenow/sdk/core' Dashboard({ $id: Now.ID['incident-dashboard'], name: 'Incident Management Dashboard', tabs: [ { $id: Now.ID['overview'], name: 'Overview', 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 }, } ], } ], permissions: [ { $id: Now.ID['admin-user-permission'], user: '6816f79cc0a8016401c5a33be04be441', // sys_id of admin user canRead: true, canWrite: true, canShare: true, owner: true, }, { $id: Now.ID['itil-role-permission'], role: '2831a114c611228501d4ea6c309d626d', // sys_id of itil role canRead: true, }, { $id: Now.ID['support-group-permission'], group: '287ebd7da9fe198100f92cc8d1d2154e', // sys_id of IT Support group canRead: true, } ], visibilities: [ { $id: Now.ID['workspace-visibility'], experience: myWorkspace, } ] }) The workspace referenced is defined using the Workspace object: export const myWorkspace = Workspace({ $id: Now.ID["my_workspace"], title: "My Workspace", path: "my-workspace", tables: ["incident"], listConfig: myListConfig }) ## tabs array {#ariaid-title3} Create tabs \[par_dashboard_tab\] that contain widgets for a dashboard. {#fluent-dashboard-tabs-array__table_j3p_yqy_23c__entry__3}{#fluent-dashboard-tabs-array__now-id-desc2} | Name | Type | Description | |-|-|-| | $id | String or Number | Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see [ServiceNow Fluent language constructs](https://servicenow-prod.fluidtopics.net/b1y7cW0gok5uzbNJ5JcSTw "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). Format: `Now.ID['String' or Number]` | | name | String | Required. A name to display on the tab. | | active | Boolean | Flag that indicates whether the tab is active. Default: true | | widgets | Array | A list of widgets to display in the tab. For more information, see [widgets array](https://servicenow-prod.fluidtopics.net/iElEm17uzIIeByDYaLSo9A#fluent-dashboard-widgets-array "Create widgets [par_dashboard_widget] within a tab in a grid layout."). | [Tabela 2. Properties] {#fluent-dashboard-tabs-array__table_j3p_yqy_23c} Within a dashboard, tabs are ordered using their position in the array. tabs: [ { $id: Now.ID['overview-tab'], name: 'Overview', widgets: [ { $id: Now.ID['chart-widget'], component: 'line', // Line chart component componentProps: { selectedElements: [], chartVariation: 'stacked', yAxisPosition: 'bottom' }, height: 12, width: 12, position: { x: 0, y: 0 }, }, { $id: Now.ID['header-widget'], component: 'heading', // Heading component componentProps: { variant: 'header-primary', label: 'Dashboard Metrics', level: '1' }, height: 4, width: 12, position: { x: 0, y: 12 }, } ], }, { $id: Now.ID['details-tab'], name: 'Details', widgets: [] } ] ### widgets array {#ariaid-title4} Create widgets \[par_dashboard_widget\] within a tab in a grid layout. Dashboards use a 48-point grid system for positioning widgets. {#fluent-dashboard-widgets-array__table_jgr_d1z_23c__entry__3}{#fluent-dashboard-widgets-array__now-id-desc2} | Name | Type | Description | |-|-|-| | $id | String or Number | Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see [ServiceNow Fluent language constructs](https://servicenow-prod.fluidtopics.net/b1y7cW0gok5uzbNJ5JcSTw "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). Format: `Now.ID['String' or Number]` | | component | Reference or String | Required. The name of a component (such as line, single-score, or heading), or the sys_id of a component from the UX Macroponent Definition \[sys_ux_macroponent\] table to display as a widget. Component names aren't case sensitive and resolve to their sys_ids during the build process. | | height | Number | Required. The height of the widget in grid units. | | width | Number | Required. The width of the widget in grid units. Maximum value: 48 | | position | Object | Required. The position of the widget in the grid layout with `x` and `y` properties. For example, a value of `{ x: 0, y: 0 }` positions the widget in the top left corner of the grid. | | componentProps | Object | The property configuration of a component. For more information, see [componentProps object](https://servicenow-prod.fluidtopics.net/iElEm17uzIIeByDYaLSo9A#fluent-dashboard-component-props-object "Configure the properties of widgets [par_dashboard_widget]."). | [Tabela 3. Properties] {#fluent-dashboard-widgets-array__table_jgr_d1z_23c} 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 object {#ariaid-title5} Configure the properties of widgets \[par_dashboard_widget\]. The available properties are determined by the component specified with the component property of the Dashboard object. * Trend data components require the dataSources, metrics, and trendBy properties. The groupBy property is optional. * Group data components require the dataSources, metrics, and groupBy properties. The trendBy property isn't supported in these visualizations. * Simple data components require the dataSources and metrics properties. The groupBy and trendBy properties aren't supported in these visualizations. {#fluent-dashboard-component-props-object__ul_w2m_xpv_33c} {#fluent-dashboard-component-props-object__table_jgr_d1z_23c__entry__3} | Name | Type | Description | |-|-|-| | dataSources | Array | A list of data sources for the component. For example: 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 | String | A title to display with the widget. | | metrics | Array | A list of metrics to measure for the data source. For example: 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 | Array | A list of configurations for grouping and organizing data by data source. For example: 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 | Object | A configuration for trend charts. For example: 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 | String | The method of sorting data. Valid values: * value * label * field {#fluent-dashboard-component-props-object__ul_b1p_ppv_33c} | [Tabela 4. Properties] {#fluent-dashboard-component-props-object__table_jgr_d1z_23c} In the following example, the `line` component, which is a trend data type visualization, is used to show how a metric changes over time. { 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 }, } In the following example, the `single-score` component, which is a simple data type visualization, is used to show a single count metric. { 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 }, } ## permissions array {#ariaid-title6} Define permissions \[par_dashboard_permission\] to read, edit, and share a dashboard. At least one of the user, group, or role properties must be specified for each permission in the array. {#fluent-dashboard-permissions-array__table_j3p_yqy_23c__entry__3}{#fluent-dashboard-permissions-array__now-id-desc2} | Name | Type | Description | |-|-|-| | $id | String or Number | Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see [ServiceNow Fluent language constructs](https://servicenow-prod.fluidtopics.net/b1y7cW0gok5uzbNJ5JcSTw "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). Format: `Now.ID['String' or Number]` | | user | Reference or String | The variable identifier or sys_id of a user \[sys_user\] to which to grant permissions. To define a user, use the [Record API - ServiceNow Fluent](https://servicenow-prod.fluidtopics.net/ZgSD9CwRLbWqLhdTkFJpZA#record-api-now-ts "The Record API defines records in any table. Use the Record API to define application metadata that doesn't have a dedicated ServiceNow Fluent API."). | | group | Reference or String | The variable identifier or sys_id of a user group \[sys_user_group\] to which to grant permissions. To define a user, use the [Record API - ServiceNow Fluent](https://servicenow-prod.fluidtopics.net/ZgSD9CwRLbWqLhdTkFJpZA#record-api-now-ts "The Record API defines records in any table. Use the Record API to define application metadata that doesn't have a dedicated ServiceNow Fluent API."). | | role | Reference or String | The variable identifier or sys_id of a role \[sys_user_role\] to which to grant permissions. To define a user, use the [Role API - ServiceNow Fluent](https://servicenow-prod.fluidtopics.net/m41jSxLL4sPO3X7b_ek1BQ#role-api-now-ts "The Role API defines roles [sys_user_role] that grant specific permissions to users of an application."). | | canRead | Boolean | Flag that indicates whether the user, group, or role can view the dashboard. Default: true | | canWrite | Boolean | Flag that indicates whether the user, group, or role can edit the dashboard. Default: false | | canShare | Boolean | Flag that indicates whether the user, group, or role can share the dashboard. Default: false | | owner | Boolean | Flag that indicates whether the user, group, or role is the owner of the dashboard. For at least one user, the owner property should be set to true. Default: false | [Tabela 5. Properties] {#fluent-dashboard-permissions-array__table_j3p_yqy_23c} 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, } ] ## visibilities array {#ariaid-title7} Define visibility rules \[par_dashboard_visibility\] for which UX experiences display the dashboard. {#fluent-dashboard-visibilities-array__table_j3p_yqy_23c__entry__3}{#fluent-dashboard-visibilities-array__now-id-desc2} | Name | Type | Description | |-|-|-| | $id | String or Number | Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see [ServiceNow Fluent language constructs](https://servicenow-prod.fluidtopics.net/b1y7cW0gok5uzbNJ5JcSTw "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). Format: `Now.ID['String' or Number]` | | experience | Reference or String | Required. The variable identifier of a Workspace object or sys_id of a UX application \[sys_ux_page_registry\]. For more information, see [Workspace API - ServiceNow Fluent](https://servicenow-prod.fluidtopics.net/so9VwOOsxlzVdnKOsZZybQ#fluent-workspace-api "The Workspace API defines configurable workspace experiences for organizing and sharing data visually."). | [Tabela 6. Properties] {#fluent-dashboard-visibilities-array__table_j3p_yqy_23c} visibilities: [ { $id: Now.ID["dashboard_visibility_1"], experience: myWorkspace // Reference to Workspace object } ]