Dashboard

Represents a dashboard. Dashboards are visual representations of data that allow you to see key metrics and performance at a glance.

For more information, see “Edit Dashboards in Accessibility Mode in Salesforce Classic” in the Salesforce online help.

Redeploying a dashboard with the same fullName as a previously deleted dashboard via Metadata API restores the deleted dashboard instead of creating a new one, even if the dashboard was removed from the Recycle Bin. The restored dashboard keeps its original Id, CreatedDate, and CreatedById.

This type extends Metadata and inherits its fields.

Dashboards are stored in the dashboards directory of the corresponding package directory. The file name matches the dashboard title and the extension is .dashboard.

You can’t use the wildcard (*) symbol with dashboards in package.xml. To retrieve the list of dashboards for populating package.xml with explicit names, call listMetadata() and pass in DashboardFolder as the type. Note that DashboardFolder is not returned as a type in describeMetadata(). Dashboard is returned from describeMetadata() with an associated attribute of inFolder set to true. If that attribute is set to true, you can construct the type by using the component name with the word Folder, such as DashboardFolder.

The following example shows folders in package.xml. The names used in package.xml must be developer names, not dashboard titles.

Introduced in API version 14.0.

• Type: string
• Required: Yes
• Description: Required. A dashboard can have a gradient color change on its charts. This field defines the second color for the gradient and backgroundStartColor defines the first color. If you prefer your background to be all one color or do not want a gradient color change, select the same color for this field and backgroundStartColor. The color is in hexadecimal format; for example #FF6600.

• Type: ChartBackgroundDirection (enumeration of type string)
• Required: Yes
• Description: Required. The direction of the gradient color change, defined by the backgroundStartColor and backgroundEndColor fields.
• Possible values:
  • Diagonal
  • LeftToRight
  • TopToBottom

• Type: string
• Required: Yes
• Description: Required. The starting color for the gradient color change on the dashboard’s charts. See backgroundEndColor for more information. The color is in hexadecimal format; for example #FF6600.

• Type: ChartTheme (enumeration of type string)
• Required: No
• Introduced: API version 42.0
• Version: Replaces dashboardChartTheme for API v42.0 and later.
• Description: Determines the default theme for all dashboard charts.
• Possible values:
  • light — Light-colored theme.
  • dark — Dark-colored theme.

• Type: ChartColorPalettes (enumeration of type string)
• Required: No
• Introduced: API version 42.0
• Version: Replaces dashboardColorPalette for API v42.0 and later.
• Description: Determines the default palette for all dashboard charts.
• Possible values:
  • accessible
  • bluegrass
  • branding
  • colorSafe
  • Default
  • dusk
  • earth
  • fire
  • gray
  • heat
  • justice
  • nightfall
  • pond
  • sunrise
  • tropic
  • unity
  • water
  • watermelon

• Type: ChartTheme (enumeration of type string)

• Required: No

• Description: Determines the default theme for all dashboard charts.

  This field is available to maintain backward compatibility with versions prior to API version 42.0.

• Possible values:

  • light — Light-colored theme.
  • dark — Dark-colored theme.

• Type: ChartColorPalettes (enumeration of type string)

• Required: No

• Description: Determines the default palette for all dashboard charts.

  This field is available to maintain backward compatibility with versions prior to API version 42.0.

• Possible values:

  • accessible
  • bluegrass
  • colorSafe
  • Default
  • dusk
  • earth
  • fire
  • gray
  • heat
  • justice
  • nightfall
  • pond
  • sunrise
  • tropic
  • unity
  • water
  • watermelon

• Type: DashboardFilter[]
• Required: No
• Introduced: API version 23.0
• Description: The list of filters in a dashboard.

• Type: DashboardGridLayout
• Required: No
• Introduced: API version 35.0
• Description: Lists the included DashboardGridComponent objects, specifies the number of dashboard columns, and sets each dashboard row’s height in pixels.

• Type: string
• Required: No
• Description: Required. Date that the dashboard was last refreshed.

• Type: string
• Required: No
• Description: Required. User currently accessing the dashboard.

• Type: DashboardType (enumeration of type string)
• Required: No
• Introduced: API version 19.0
• Description: Determines the way visibility settings are set for a dashboard.
• Possible values:
  • SpecifiedUser — All users see data at the access level of one specific running user, specified in the runningUser field, regardless of their own security settings.
  • LoggedInUser — Each logged-in user sees data according to his or her own access level.
  • MyTeamUser — Managers can choose to view the dashboard from the point of view of their subordinates in the role hierarchy. This value is available in API version 20.0 and later.

• Type: string
• Required: No
• Description: Description for the dashboard. Maximum of 255 characters.

• Type: string
• Required: No
• Introduced: API version 35.0
• Description: Name of the folder that houses the dashboard.

• Type: string

• Required: No

• Description: Inherited from Metadata, this field is defined in the WSDL for this metadata type. It must be specified when creating, updating, or deleting. See createMetadata() to see an example of this field specified for a call.

  This field specifies the folder and dashboard title; for example folderSales/California.

• Type: boolean

• Required: No

• Introduced: API version 35.0

• Description: Specifies whether a dashboard uses the Lightning Experience layout (true) or not (false).

  Lightning Experience allows dashboards with more than three columns with components that span multiple columns and multiple rows in size.

• Type: DashboardComponentSection
• Required: No
• Description: Required. The left section or column of the dashboard.

• Type: DashboardComponentSection
• Required: No
• Description: The middle section or column of the dashboard.

• Type: int
• Required: No
• Introduced: API version 42.0
• Description: Number of subscriptions reported on the dashboard.

• Type: string
• Required: No
• Description: The creator of the dashboard.

• Type: DashboardComponentSection
• Required: No
• Description: Required. The right section or column of the dashboard.

• Type: string

• Required: No

• Description: The username of the user whose role and sharing settings are used to determine the data shown in the dashboard.

  When you deploy a dashboard and the value in this field is not defined or does not correspond to a valid user, the field is populated with the username of the user performing the deployment.

  Regardless of their security settings, all users viewing a dashboard see exactly the same data, because dashboards are always run using the security settings of a particular user.

To avoid inappropriate exposure of sensitive data, save the dashboard to a folder that is visible only to appropriate users.

• Type: string
• Required: Yes
• Description: Required. Color of the text on each chart in the dashboard. The color is in hexadecimal format; for example #FF6600.

• Type: string
• Required: Yes
• Description: Required. The dashboard title.

• Type: string
• Required: Yes
• Description: Required. Color of the titles on each dashboard component. The color is in hexadecimal format; for example #FF6600.

• Type: int
• Required: Yes
• Description: Required. Size of characters in title text. For example, a value of 12 indicates 12pt text.

A dashboard consists of a group of different components or elements that display data. Each component can use a custom report or a custom s-control as their data source to display corporate metrics or key performance indicators. You can create several dashboard components and display them all in one dashboard aligned in up to three columns.

• Type: boolean
• Required: No

• Type: ChartRangeType (enumeration of type string)
• Required: No
• Description: A manual or automatic axis range for bar or line charts.
• Possible values:
  • auto
  • manual

• Type: double
• Required: No
• Description: The maximum axis range to be displayed. This only applies to bar and line charts in which the manual axis range is selected for the chartAxisRange field.

• Type: double
• Required: No
• Description: The minimum axis range to be displayed. This only applies to bar and line charts in which the manual axis range is selected for the chartAxisRange field.

• Type: ChartSummary[]
• Required: No
• Introduced: API version 25.0
• Description: Specifies the summary field for the chart data. Required if isAutoSelectFromReport is set to false.

• Type: ChartTheme (enumeration of type string)
• Required: No

• Type: DashboardComponentType (enumeration of type string)
• Required: Yes

• Type: DashboardComponentContent[]
• Required: No
• Introduced: API version 58.0
• Description: A list of dashboard component contents.

• Type: DashboardDynamicValue[]
• Required: No
• Introduced: API version 36.0
• Description: A list of dashboard dynamic values.

• Type: DashboardFilterColumn[]
• Required: No
• Introduced: API version 23.0
• Description: A list of dashboard filter columns. Each report-based component must have a dashboard filter column that defines the column that the filter applies to.

• Type: DashboardTableColumn[]
• Required: No
• Description: Represents a list of columns on a customized dashboard table component.

• Type: int
• Required: No

• Type: ChartUnits (enumeration of type string)
• Required: No
• Description: Chart Units.
• Possible values:
  • Auto
  • Integer
  • Hundreds
  • Thousands
  • Millions
  • Billions
  • Trillions

• Type: string
• Required: No
• Description: For charts, specifies a URL that users go to when they click the dashboard component. Use this option to send users to another dashboard, report, record detail page, or other system that uses a Web interface. This field overrides the drillEnabled and drillToDetailEnabled fields.

• Type: boolean

• Required: No

• Introduced: API version 17.0

• Description: Specifies whether to take users to the full or filtered source report when they click the dashboard component. Set to false to drill to the full source report; set to true to drill to the source report filtered by what they clicked. If set to true, users can click individual groups, axis values, or legend entries.

  This overrides the drillToDetailEnabled field.

• Type: boolean
• Required: No
• Introduced: API version 20.0
• Description: When enabled, users are taken to the record detail page when they click a record name, record owner, or feed post in a table or chart. When set to true users can click axis and legend values, chart elements, and table entries. The drillDownUrl and drillEnabled fields override this field.

• Type: boolean
• Required: No
• Introduced: API version 17.0
• Description: Specifies whether to display values, labels, and percentages when hovering over charts. Hover details depend on chart type. Percentages apply to pie, donut, and funnel charts only.

• Type: boolean
• Required: No
• Introduced: API version 17.0
• Description: Specifies whether to combine all groups less than or equal to 3% of the total into a single ‘Others’ wedge or segment. This only applies to pie, donut, and funnel charts. Set to true to show all values individually on the chart; set to false to combine small groups into ‘Others.’

• Type: DashboardFlexTableComponentProperties
• Required: No
• Introduced: API version 41.0
• Description: Defines metadata for Lightning Experience table columns and sorting.

• Type: string
• Required: No
• Description: Footer displayed at the bottom of the dashboard component. Maximum of 255 characters.

• Type: double
• Required: No
• Description: The maximum value on a gauge. A gauge is used to see how far you are from reaching a goal. It looks like a speedometer in a car.

• Type: double
• Required: No
• Description: The minimum value on a gauge.

• Type: string[]
• Required: No
• Introduced: API version 25.0
• Description: Specifies the field by which to group data. This data is displayed on the X-axis for vertical column charts and on the Y-axis for horizontal bar charts.

• Type: DashboardComponentGroupingSortProperties
• Required: No
• Introduced: API version 46.0
• Description: This field captures sort properties of the dashboard component. If the component has one or more groupings, sort information is stored here; otherwise, it is stored in the sortBy field.

• Type: string
• Required: No
• Description: Header displayed at the top of the dashboard component. Maximum of 80 characters.

• Type: double
• Required: No
• Description: The value that separates the indicatorLowColor from the indicatorMiddleColor on the dashboard.

• Type: double
• Required: No
• Description: The value that separates the indicatorMiddleColor from the indicatorHighColor on the dashboard.

• Type: string
• Required: No
• Description: The color representing a high number range on the gauge.

• Type: string
• Required: No
• Description: The color representing a low number range on the gauge.

• Type: string
• Required: No
• Description: The color representing a medium number range on the gauge.

• Type: ChartLegendPosition (enumeration of type string)
• Required: No

• Type: int
• Required: No
• Description: The maximum number of elements to include in the top-level grouping of the horizontal axis of a horizontal chart, vertical axis of a vertical chart, or selected axis of a stacked bar chart. For example, if you want to list only your top five salespeople, create an opportunity report that lists total opportunity amounts by owner and enter 5 in this field.

• Type: string
• Required: No
• Description: Descriptive label for the metric. This is relevant if metric is the value of the componentType field.

• Type: string
• Required: No

• Type: int
• Required: No

• Type: string
• Required: No
• Description: Name of the report associated with the component.

• Type: string
• Required: No
• Description: S-control associated with component if scontrol is the value of the componentType field. For more information, see “Defining Custom S-Controls” in the Salesforce online help.

• Type: int
• Required: No
• Description: Display height of the s-control in pixels.

• Type: boolean
• Required: No
• Description: Indicates if percentages are displayed for regions of gauges and wedges and segments of pie, donut, and funnel charts (true), or not (false).

• Type: boolean
• Required: No
• Description: Display Chatter photos for up to 20 records in a horizontal bar chart component whose source report is grouped by a user or group name field. If there are more than 20 records with photos, record names are shown instead of photos. Set Grouping Display to None to show photos. Set the Drill Down to option to Record Detail Page to take users directly to user profile or group pages when they click photos. Chatter must be enabled for photos to be displayed. Depending on your organization’s setup, you may not see photos on tables and charts.

• Type: boolean
• Required: No
• Description: Display Chatter photos for up to 20 records in a horizontal bar chart component whose source report is grouped by a user or group name field. If there are more than 20 records with photos, record names are shown instead of photos. Set Grouping Display to None to show photos. Set the Drill Down to option to Record Detail Page to take users directly to user profile or group pages when they click photos. Chatter must be enabled for photos to be displayed. Depending on your organization’s setup, you may not see photos on tables and charts.

• Type: boolean
• Required: No

• Type: boolean
• Required: No
• Description: Indicates if the total of all wedges is displayed for gauges and donut charts (true), or not (false).

• Type: boolean
• Required: No
• Description: Indicates if the values of individual records or groups are displayed for charts (true), or not (false).

• Type: DashboardComponentFilter (enumeration of type string)
• Required: No
• Description: The sort option for the dashboard component.

• Type: boolean
• Required: No
• Description: Specifies whether to sort the legend values for the dashboard component.

• Type: string
• Required: No
• Description: The title of the dashboard component. Maximum of 40 characters.

• Type: boolean
• Required: No
• Description: Specifies whether to use the chart defined in the source report on this dashboard component. The chart settings in the source report determine how the chart displays in the dashboard, and any chart settings you define for the dashboard are overridden. If you defined a combination chart in the source report, use this option to use that combination chart on this dashboard.

DashboardComponentColumn represents a component column in a dashboard.

Introduced in API version 41.0.

• Type: double
• Required: No
• Description: The value that separates the lowRangeColor from the midRangeColor on the dashboard.

• Type: double
• Required: No
• Description: The value that separates the midRangeColor from the highRangeColor on the dashboard.

• Type: int
• Required: No
• Description: Conditional highlighting can be applied to multiple columns. This field stores the order of conditional highlights.

• Type: int
• Required: No
• Description: The color representing a high number range on the column.

• Type: int
• Required: No
• Description: The color representing a low number range on the column.

• Type: int
• Required: No
• Description: The color representing a mid number range on the column.

• Type: string
• Required: Yes
• Description: Required. The report column code for the filter.

• Type: boolean
• Required: No

• Type: boolean
• Required: No
• Description: If true, the column total is displayed.

• Type: DashboardComponentColumnType (enumeration of type string)
• Required: Yes
• Introduced: API version 41.0
• Description: Represents the type of Lightning Experience table column:
• Possible values:
  • Details
  • Aggregates
  • Grouping

dashboardComponentContent represents the content of a dashboard’s components.

• Type: string
• Required: No
• Description: Any additional metadata the user wants to include for the component contents.

• Type: string
• Required: No
• Description: The component’s alternative text.

• Type: string
• Required: No
• Description: The parameters for the component.

• Type: string
• Required: No
• Description: The name of the component file.

• Type: Fit (enumeration of type string)
• Required: No
• Description: The image alignment type.
• Possible values:
  • FitHeight
  • FitWidth
  • Original
  • Stretch
  • Tile

• Type: HorizontalAlignment (enumeration of type string)
• Required: No
• Description: The horizontal alignment type.
• Possible values:
  • Left
  • Center
  • Right

• Type: string
• Required: No
• Description: The rich text content for the component.

• Type: string
• Required: No
• Description: The dashboard component’s tooltip.

• Type: VerticalAlignment (enumeration of type string)
• Required: No
• Description: The vertical alignment type.
• Possible values:
  • Bottom
  • Center
  • Top

DashboardComponentFilter is an enumeration of type string that lists the sort values for dashboard components.

DashboardComponentGroupingSort specifies properties for sorting on a dashboard component group.

• Type: string
• Required: Yes
• Description: Grouping at which this sort configuration is applied.

• Type: string
• Required: No
• Description: true if the sort order is picked up from an underlying report for this grouping level.

• Type: string
• Required: No
• Description: If grouping is sorted by an aggregate, this value is the aggregate value (such as sortColumn). If the grouping is sorted by its own value, this field is null.

• Type: string
• Required: No
• Description: Ascending or Descending to reflect the sort order.

DashboardComponentGroupingSortProperties is composed of multiple elements of the type DashboardComponentGroupingSort.

• Type: DashboardComponentGroupingSort[]
• Required: No
• Introduced: API version 46.0
• Description: This field stores sort information for a dashboard at each grouping level of granularity.

DashboardComponentSection represents one of the sections or columns in a dashboard.

• Type: DashboardComponentSize (enumeration of type string)
• Required: Yes
• Description: Required. The size of the column in the dashboard:
• Possible values:
  • Medium
  • Narrow
  • Wide

• Type: DashboardComponent[]
• Required: No
• Description: The list of DashboardComponent objects in the dashboard column.

DashboardFilterColumns represents a filter column in a dashboard.

• Type: string
• Required: No
• Introduced: API version 41.0
• Description: Indicates the column on which the table is sorted.

• Type: string
• Required: No
• Introduced: API version 41.0
• Description: Indicates whether column sorting is ascending or descending.

DashboardDynamicValue represents a dynamic value in a dashboard.

• Type: string
• Required: No
• Description: Any additional metadata the user wants to include for the dynamic value.

• Type: string
• Required: Yes
• Description: Required. The name of the field for the dynamic value.

• Type: boolean
• Required: No
• Description: Indicates whether the value should be retrieved as the user running the dashboard (true) or not (false).

DashboardFilter represents a filter in a dashboard.

• Type: DashboardFilterOption[]
• Required: No
• Description: The list of items you can select in the Filter Options section of the Add Filter dialog.

• Type: string
• Required: Yes
• Description: Required. The filter label.

DashboardFilterColumn represents a filter column in a dashboard.

• Type: string
• Required: Yes
• Description: Required. The report column code for the filter.

DashboardFilterOption represents a filter option in a dashboard.

• Type: DashboardFilterOperation (enumeration of type string)
• Required: Yes
• Introduced: API version 24.0
• Description: Required. Represents the filter operation for this filter item. With API version 23.0, valid values are enumerated in CustomField.
• Possible values:
  • equals
  • notEqual
  • lessThan
  • greaterThan
  • lessOrEqual
  • greaterOrEqual
  • contains
  • notContain
  • startsWith
  • includes
  • excludes
  • between

The “between” operator takes two operands (for example, “between MinimumValue, MaximumValue”). Note also that the minimum value is inclusive, while the maximum value is exclusive. All other dashboard filter operations take a single operand only.

• Type: string[]
• Required: No
• Introduced: API version 24.0
• Description: Required. One or more values in the Filter Options area of the Add Filter dialog.

DashboardFlexTableComponentProperties represents a column in a customized table component in a dashboard.

• Type: int
• Required: No
• Description: For columns with numeric values, indicates the number of significant digits.

• Type: DashboardComponentColumn[]
• Required: No
• Introduced: API version 41.0
• Description: Represents a column in a Lightning Experience table component.

• Type: DashboardComponentSortInfo
• Required: No
• Introduced: API version 41.0
• Description: Represents sorting column and order in a Lightning Experience table component.

• Type: boolean
• Required: No
• Introduced: API version 41.0
• Description: If true, hides any photos from Chatter feeds.

• Type: boolean
• Required: No
• Introduced: API version 65.0
• Description: If true, users can import report table settings to this component.

Lightning Experience features dashboards with more than three columns and components that span multiple columns and multiple rows in size. DashboardGridComponent specifies location and size of a given dashboard component.

• Type: int

• Required: Yes

• Description: Required. The width of the dashboard component in columns.

  For example, if colSpan is 5, then the dashboard component spans five columns.

• Type: int
• Required: Yes
• Description: Required. The left-most column that is occupied by the dashboard component.

• Type: DashboardComponent
• Required: Yes
• Description: Required. The dashboard component that is being sized and placed.

• Type: int
• Required: Yes
• Description: Required. The top-most row that is occupied by the dashboard component.

• Type: int
• Required: Yes
• Description: Required. The height of the dashboard component in rows.

Lightning Experience features dashboards with more than three columns and components that span multiple columns and multiple rows in size. DashboardGridLayout lists the included dashboard components, specifies the number of dashboard columns, and sets each dashboard row’s height in pixels.

• Type: DashboardGridComponent[]
• Required: No
• Description: List of DashboardGridComponent objects in the dashboard.

• Type: int
• Required: Yes
• Description: Required. Total number of columns in the dashboard.

• Type: int
• Required: Yes
• Description: Required. Height of each row in pixels.

DashboardTableColumn represents a column in a customized table component in a dashboard.

• Type: ReportSummaryType (enumeration of type string)
• Required: No
• Description: Specifies the aggregation type for the table column.

• Type: boolean
• Required: No

• Type: string
• Required: Yes
• Description: Required. The label of the column to use in the table.

• Type: int
• Required: No

• Type: boolean
• Required: No

• Type: boolean
• Required: No
• Introduced: API version 19.0
• Description: Displays the totals for each summarizable column in the dashboard table.

• Type: DashboardComponentFilter (enumeration of type string)
• Required: No
• Description: The sort option for the dashboard table component. Sort on just one column per table.

A sample XML definition of a filtered dashboard is shown below. Note that this example is supported in API version 24.0 and later. The file name matches the dashboard title and the extension is .dashboard.

A sample XML definition of a dashboard is shown below. The file name matches the dashboard title and the extension is .dashboard.

A sample XML definition of a Lightning Experience dashboard with isGridLayout equals true is shown below. Note that this example is supported in API version 35.0 and later. The file name matches the dashboard title and the extension is .dashboard.

This metadata type doesn’t support the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.