{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":2447,"path":"application-development/servicenow-sdk/fluent-dashboard-api.md","title":"Dashboard API - ServiceNow Fluent","bundle":null,"doc_type":null,"release":"australia","body":"\n# Dashboard API - ServiceNow Fluent\n\nThe Dashboard API defines dashboards \\[par\\_dashboard\\] for organizing and sharing data visually.\n\n**Note:** For the latest ServiceNow Fluent API documentation and examples, see the [ServiceNow Fluent API reference](https://servicenow.github.io/sdk/category/api-reference) and [ServiceNow SDK examples repository](https://github.com/ServiceNow/sdk-examples) on GitHub.\n\nA dashboard consists of tabs, widgets, visibilities, and permissions. Each tab contains widgets that display data visualizations, headings, rich text, and other components.\n\nDashboards can be used as the home page of a workspace by referring to one or more workspaces from the visibilities array of the Dashboard object. To create a workspace, see [Workspace API - ServiceNow Fluent](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/fluent-workspace-api.md).\n\nFor general information about dashboards, see [Dashboards in Platform Analytics](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/now-intelligence/analytics-center-dashboards.md).\n\n**Parent Topic:**[ServiceNow Fluent API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/servicenow-fluent-api-reference.md)\n\n**Related topics** \n\n\n[ServiceNow Fluent](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-fluent.md)\n\n## Dashboard object\n\nCreate a shareable dashboard \\[par\\_dashboard\\] with data visualizations, filters, tabs, widgets, permissions, and visibility rules.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\n$id\n\n\n\nString or Number\n\n\n\nRequired. 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/fluent-constructs.md).Format: `Now.ID['String' or Number]`\n\n
\n\nname\n\n\n\nString\n\n\n\nRequired. A name to display for the dashboard.\n\n
\n\nactive\n\n\n\nBoolean\n\n\n\nFlag that indicates whether the dashboard is active.Default: true\n\n
\n\ntabs\n\n\n\nArray\n\n\n\nA list of tabs to display in the dashboard. For more information, see [tabs array](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/fluent-dashboard-api.md).\n\n
\n\npermissions\n\n\n\nArray\n\n\n\nA list of user permissions required to access the dashboard. For more information, see [permissions array](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/fluent-dashboard-api.md).\n\n
\n\nvisibilities\n\n\n\nArray\n\n\n\nA list of visibility rules that control which UX experiences display the dashboard. For more information, see [visibilities array](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/fluent-dashboard-api.md).Default: A default visibility rule with sys\\_id 08c73d60537101100834ddeeff7b1287 is used.\n\n
\n\n$meta\n\n\n\nObject\n\n\n\nMetadata for the application metadata.With the installMethod property, you can map the application metadata to an output directory that loads only in specific circumstances.\n\n```javascript\n$meta: {\n      installMethod: 'String'\n}\n```\n\nValid values for installMethod:\n\n- 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.\n- 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.\n\n
```javascript\nimport { Dashboard } from \"@servicenow/sdk/core\";\n\nDashboard({\n $id: Now.ID[\"incident_management_dashboard\"],\n name: \"Incident Management Dashboard\",\n tabs: [\n {\n $id: Now.ID[\"incident_overview_tab\"],\n name: \"Overview\",\n widgets: [\n // Single Score: Total Open Incidents\n {\n $id: Now.ID[\"total_open_incidents_widget\"],\n component: \"single-score\",\n componentProps: {\n dataSources: [\n {\n label: \"Incident\",\n sourceType: \"table\",\n tableOrViewName: \"incident\",\n filterQuery: \"\",\n reportSourceSysId: \"d94d6f62d7632100b96d45a3ce6103d2\",\n id: \"dGFibGVpbmNpZGVudDE3NjMzOTI0OTY5ODE=\"\n }\n ],\n headerTitle: \"Open Incidents\",\n metrics: [\n {\n dataSource: \"dGFibGVpbmNpZGVudDE3NjMzOTI0OTY5ODE=\",\n id: \"ZEdGaWJHVnBibU5wWkdWdWRERTNOak16T1RJME9UWTVPREU9MTc2MzM5MjQ5Nzc5OQ==\",\n aggregateFunction: \"COUNT\",\n axisId: \"primary\"\n }\n ],\n sortBy: \"value\"\n },\n height: 14,\n width: 14,\n position: { x: 0, y: 0 }\n },\n // Vertical Bar: Incidents by Priority\n {\n $id: Now.ID[\"incidents_by_priority_widget\"],\n component: \"vertical-bar\",\n componentProps: {\n dataSources: [\n {\n label: \"Incident\",\n sourceType: \"table\",\n tableOrViewName: \"incident\",\n filterQuery: \"\",\n reportSourceSysId: \"d94d6f62d7632100b96d45a3ce6103d2\",\n id: \"dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA=\"\n }\n ],\n headerTitle: \"Incidents by Priority\",\n metrics: [\n {\n dataSource: \"dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA=\",\n id: \"ZEdGaWJHVnBibU5wWkdWdWRERTNOakkzT1RVNE9UZzNOREE9MTc2Mjc5NTg5OTM5OA==\",\n aggregateFunction: \"COUNT\",\n axisId: \"primary\"\n }\n ],\n groupBy: [\n {\n groupBy: [\n {\n dataSource: \"dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA=\",\n groupByField: \"priority\"\n }\n ],\n maxNumberOfGroups: 10,\n numberOfGroupsBasedOn: \"NO_OF_GROUP_BASED_ON_PER_METRIC\",\n showOthers: false,\n disableRanges: false\n }\n ],\n sortBy: \"value\"\n },\n height: 14,\n width: 17,\n position: { x: 14, y: 0 }\n },\n // Vertical Bar: Incidents by State\n {\n $id: Now.ID[\"incidents_by_state_widget\"],\n component: \"vertical-bar\",\n componentProps: {\n dataSources: [\n {\n label: \"Incident\",\n sourceType: \"table\",\n tableOrViewName: \"incident\",\n filterQuery: \"\",\n reportSourceSysId: \"d94d6f62d7632100b96d45a3ce6103d2\",\n id: \"dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA=\"\n }\n ],\n headerTitle: \"Incidents by State\",\n metrics: [\n {\n dataSource: \"dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA=\",\n id: \"ZEdGaWJHVnBibU5wWkdWdWRERTNOakkzT1RVNE9UZzNOREE9MTc2Mjc5NTg5OTM5OA==\",\n aggregateFunction: \"COUNT\",\n axisId: \"primary\"\n }\n ],\n groupBy: [\n {\n groupBy: [\n {\n dataSource: \"dGFibGVpbmNpZGVudDE3NjI3OTU4OTg3NDA=\",\n groupByField: \"state\"\n }\n ],\n maxNumberOfGroups: 10,\n numberOfGroupsBasedOn: \"NO_OF_GROUP_BASED_ON_PER_METRIC\",\n showOthers: false,\n disableRanges: false\n }\n ],\n sortBy: \"value\"\n },\n height: 14,\n width: 17,\n position: { x: 31, y: 0 }\n }\n ]\n },\n {\n $id: Now.ID[\"incident_trends_tab\"],\n name: \"Trends\",\n widgets: [] // Can be populated later or left empty\n }\n ],\n visibilities: [\n {\n $id: Now.ID[\"incident_dashboard_visibility\"],\n experience: incidentWorkspace\n }\n ],\n permissions: []\n})\n```\n\nThe workspace referenced is defined using the Workspace object:\n\n```javascript\nimport { Workspace } from \"@servicenow/sdk/core\";\n\nexport const myWorkspace = Workspace({\n $id: Now.ID[\"my_workspace\"],\n title: \"My Workspace\",\n path: \"my-workspace\",\n tables: [\"incident\"],\n listConfig: myListConfig\n})\n```\n\n## tabs array\n\nCreate tabs \\[par\\_dashboard\\_tab\\] that contain widgets for a dashboard.\n\nWithin a dashboard, tabs are ordered using their position in the array.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\n$id\n\n\n\nString or Number\n\n\n\nRequired. 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/fluent-constructs.md).Format: `Now.ID['String' or Number]`\n\n
\n\nname\n\n\n\nString\n\n\n\nRequired. A name to display on the tab.\n\n
\n\nactive\n\n\n\nBoolean\n\n\n\nFlag that indicates whether the tab is active.Default: true\n\n**Note:** This flag is not used in the application and its value does not change the status of the tab.\n\n
\n\nwidgets\n\n\n\nArray\n\n\n\nA list of widgets to display in the tab. For more information, see [widgets array](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/fluent-dashboard-api.md).\n\n
```javascript\ntabs: [\n {\n $id: Now.ID[\"my_dashboard_tab1\"],\n name: \"Overview\",\n widgets: [\n {\n $id: Now.ID[\"my_dashboard_widget_1\"],\n component: \"single-score\",\n componentProps: {\n dataSources: [\n {\n label: \"Incident\",\n sourceType: \"table\",\n tableOrViewName: \"incident\",\n filterQuery: \"\",\n reportSourceSysId: \"d94d6f62d7632100b96d45a3ce6103d2\",\n id: \"dGFibGVpbmNpZGVudDE3NjMzOTI0OTY5ODE=\"\n }\n ],\n headerTitle: \"Open Incidents\",\n metrics: [\n {\n dataSource: \"dGFibGVpbmNpZGVudDE3NjMzOTI0OTY5ODE=\",\n id: \"ZEdGaWJHVnBibU5wWkdWdWRERTNOak16T1RJME9UWTVPREU9MTc2MzM5MjQ5Nzc5OQ==\",\n aggregateFunction: \"COUNT\",\n axisId: \"primary\"\n }\n ],\n sortBy: \"value\"\n },\n height: 14,\n width: 14,\n position: { x: 0, y: 0 }\n }\n ]\n }\n]\n```\n\n### widgets array\n\nCreate widgets \\[par\\_dashboard\\_widget\\] within a tab in a grid layout.\n\nDashboards use a 48-point grid system for positioning widgets.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\n$id\n\n\n\nString or Number\n\n\n\nRequired. 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/fluent-constructs.md).Format: `Now.ID['String' or Number]`\n\n
\n\ncomponent\n\n\n\nReference or String\n\n\n\nRequired. The name of a component \\(such as line or single-score\\) 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.\n\n
\n\nheight\n\n\n\nNumber\n\n\n\nRequired. The height of the widget in grid units.\n\n
\n\nwidth\n\n\n\nNumber\n\n\n\nRequired. The width of the widget in grid units.Maximum value: 48\n\n
\n\nposition\n\n\n\nObject\n\n\n\nRequired. 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.\n\n
\n\ncomponentProps\n\n\n\nObject\n\n\n\nThe property configuration of a component. For more information, see [componentProps object](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/fluent-dashboard-api.md).\n\n
```javascript\nwidgets: [\n {\n $id: Now.ID['incident-count-chart'],\n component: 'vertical-bar', // Vertical bar chart\n componentProps: {\n title: 'Incident Count',\n dataSource: 'incident',\n aggregation: 'count'\n },\n height: 8,\n width: 6,\n position: { x: 0, y: 0 },\n },\n {\n $id: Now.ID['recent-incidents-list'],\n component: 'list', // List component\n componentProps: {\n table: 'incident',\n filter: 'active=true',\n limit: 10,\n columns: ['number', 'short_description', 'priority', 'state']\n },\n height: 8,\n width: 6,\n position: { x: 6, y: 0 },\n }\n ],\n },\n {\n $id: Now.ID['analytics'],\n name: 'Analytics',\n widgets: [\n {\n $id: Now.ID['metrics-widget'],\n component: 'single-score', // Single score component\n componentProps: {\n title: 'Key Metrics',\n scoreSize: 'large'\n },\n height: 12,\n width: 12,\n position: { x: 0, y: 0 },\n }\n]\n```\n\n### componentProps object\n\nConfigure the properties of widgets \\[par\\_dashboard\\_widget\\].\n\nThe available properties are determined by the component specified with the component property of the Dashboard object.\n\n- Trend data components require the dataSources, metrics, and trendBy properties. The groupBy property is optional.\n- Group data components require the dataSources, metrics, and groupBy properties. The trendBy property isn't supported in these visualizations.\n- Simple data components require the dataSources and metrics properties. The groupBy and trendBy properties aren't supported in these visualizations.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\ndataSources\n\n\n\nArray\n\n\n\nA list of data sources for the component. For example:```javascript\ndataSources: [\n {\n label: \"Incident\", // Human-readable label\n sourceType: \"table\", // Type of data source\n tableOrViewName: \"incident\", // ServiceNow table name\n filterQuery: \"\", // Optional encoded query filter\n id: \"data_source_1\" // Unique data source ID\n },\n...\n]\n```\n\n
\n\nheaderTitle\n\n\n\nString\n\n\n\nA title to display with the widget.\n\n
\n\nmetrics\n\n\n\nArray\n\n\n\nA list of metrics to measure for the data source. For example:```javascript\nmetrics: [\n {\n dataSource: 'data_source_1', // Must match dataSource id\n id: 'metric_1', // Unique metric ID\n aggregateFunction: 'AVG', // COUNT, SUM, AVG, MIN, MAX, COUNT_DISTINCT\n aggregateField: 'business_duration' // Field to be used for aggregation.\n axisId: 'primary', // Which axis to display the series\n },\n...\n]\n```\n\n
\n\ngroupBy\n\n\n\nArray\n\n\n\nA list of configurations for grouping and organizing data by data source. For example:```javascript\ngroupBy: [\n {\n groupBy: [\n {\n dataSource: \"data_source_1\", // Must match dataSource id\n groupByField: \"state\" // Field to group by\n }\n ],\n maxNumberOfGroups: 10, // Maximum categories to show\n showOthers: false // Show \"Others\" category\n },\n...\n]\n```\n\n
\n\ntrendBy\n\n\n\nObject\n\n\n\nA configuration for trend charts. For example:```javascript\ntrendBy: {\n \"trendByFrequency\": \"year\", // Frequency of the trend (date, week, month, year)\n \"trendByFields\": [\n {\n \"field\": \"sys_created_on\", // Field to trend on (from the table of the dataSource)\n \"metric\": \"metric_1\" // ID of the metric\n }\n ]\n}\n```\n\n
\n\nsortBy\n\n\n\nString\n\n\n\nThe method of sorting data.Valid values:\n\n- value\n- label\n- field\n\n
In the following example, the `line` component, which is a trend data type visualization, is used to show how a metric changes over time.\n\n```javascript\n{\n component: 'line',\n componentProps: {\n dataSources: [\n {\n label: 'Incident',\n sourceType: 'table',\n tableOrViewName: 'incident',\n filterQuery: '',\n id: 'data_source_1',\n },\n ],\n headerTitle: 'Incidents by State',\n metrics: [\n {\n dataSource: 'data_source_1',\n id: 'metric_1',\n aggregateFunction: 'COUNT',\n axisId: 'primary',\n },\n ],\n trendBy: {\n trendByFrequency: \"year\",\n trendByFields: [\n {\n field: \"sys_created_on\",\n metric: \"metric_1\"\n }\n ]\n },\n },\n height: 14,\n width: 17,\n position: { x: 0, y: 0 },\n}\n```\n\nIn the following example, the `single-score` component, which is a simple data type visualization, is used to show a single count metric.\n\n```javascript\n{\n component: 'single-score',\n componentProps: {\n dataSources: [\n {\n label: 'Incident',\n sourceType: 'table',\n tableOrViewName: 'incident',\n filterQuery: '',\n id: 'data_source_1',\n },\n ],\n headerTitle: 'Open Incidents',\n metrics: [\n {\n dataSource: 'data_source_1',\n id: 'metric_1',\n aggregateFunction: 'COUNT',\n axisId: 'primary',\n },\n ]\n },\n height: 14,\n width: 14,\n position: { x: 0, y: 0 },\n}\n```\n\n## permissions array\n\nDefine permissions \\[par\\_dashboard\\_permission\\] to read, edit, and share a dashboard.\n\nAt least one of the user, group, or role properties must be specified for each permission in the array.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\n$id\n\n\n\nString or Number\n\n\n\nRequired. 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/fluent-constructs.md).Format: `Now.ID['String' or Number]`\n\n
\n\nuser\n\n\n\nReference or String\n\n\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/record-api-now-ts.md).\n\n
\n\ngroup\n\n\n\nReference or String\n\n\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/record-api-now-ts.md).\n\n
\n\nrole\n\n\n\nReference or String\n\n\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/role-api-now-ts.md).\n\n
\n\ncanRead\n\n\n\nBoolean\n\n\n\nFlag that indicates whether the user, group, or role can view the dashboard.Default: true\n\n
\n\ncanWrite\n\n\n\nBoolean\n\n\n\nFlag that indicates whether the user, group, or role can edit the dashboard.Default: false\n\n
\n\ncanShare\n\n\n\nBoolean\n\n\n\nFlag that indicates whether the user, group, or role can share the dashboard.Default: false\n\n
\n\nowner\n\n\n\nBoolean\n\n\n\nFlag 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\n\n
```javascript\npermissions: [\n {\n $id: Now.ID['manager-user-permission'],\n user: 'a8f98bb0eb32010045e1a5115206fe3a', // sys_id of manager user\n canRead: true,\n canWrite: true,\n owner: true,\n },\n {\n $id: Now.ID['itil-role-permission'],\n role: '2831a114c611228501d4ea6c309d626d', // sys_id of itil role\n canRead: true,\n canWrite: false,\n },\n {\n $id: Now.ID['support-group-permission'],\n group: 'd625dccec0a8016700a222a0f7900d06', // sys_id of Service Desk group\n canRead: true,\n canWrite: false,\n }\n]\n```\n\n## visibilities array\n\nDefine visibility rules \\[par\\_dashboard\\_visibility\\] for which UX experiences display the dashboard.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\n$id\n\n\n\nString or Number\n\n\n\nRequired. 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/fluent-constructs.md).Format: `Now.ID['String' or Number]`\n\n
\n\nexperience\n\n\n\nReference or String\n\n\n\nRequired. 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-sdk/fluent-workspace-api.md).\n\n
```javascript\nvisibilities: [\n {\n $id: Now.ID[\"dashboard_visibility_1\"],\n experience: myWorkspace // Reference to Workspace object\n }\n]\n```\n\n"}}