Settings API - Entities list cards schema table

Entities list cards (`builtin:ua.entities-list`)

Define entities lists and reference them in screen layout.

Schema ID	Schema groups	Scope
`builtin:ua.entities-list`	`group:unified-analysis`	`ua-screen`

Retrieve schema via Settings API

GET	Managed	`https://{your-domain}/e/{your-environment-id}/api/v2/settings/schemas/builtin:ua.entities-list`
	SaaS	`https://{your-environment-id}.live.dynatrace.com/api/v2/settings/schemas/builtin:ua.entities-list`
	Environment ActiveGate	`https://{your-activegate-domain}/e/{your-environment-id}/api/v2/settings/schemas/builtin:ua.entities-list`

Authentication

To execute this request, you need an access token with Read settings (settings.read) scope. To learn how to obtain and use it, see Tokens and authentication.

Parameters

Property	Label	Type	Description	Required
key	Key	text	Unique key, which is used to map to this entities list in the screen layout config.	required
displayName	Display name	text	The title of the card.	optional
description	Description	text	The description of the card Markdown syntax can be used to enrich description. To define a link, you can only use seaOtter links (https://dt-url.net/XXXXXXX) or action expression The format of a single action expression is: actionName\|key=param\|key2=param2	optional
entitySelectorTemplate	Entity selector template	text	An entity selector that is used to fetch the selected entities. For example for a process group screen where you want to list all processes this might look like this: `type(PROCESS_GROUP_INSTANCE), fromRelationships.isInstanceOf($(entityConditions))` Please mind that the `$(entityConditions)` is a placeholder for the current ME selector. May be left empty if specified in screen layout.	optional
pageSize	Page size	integer	The number of entities displayed on one page.	required
entitiesLimit	Entities limit	integer	The limit of entities quantity fetched from the server. When the limit is exceeded, only this number of entities will be displayed and the sorting of attributes and metrics columns will be turned off. To get it back again, user needs to apply filters to reduce number of records below the limit. Raising the limit may cause performance drop and should be considered only for list with few metric columns.	required
displayProblemImpactWidget	Display problem impact widget	boolean	When true, widget, indicating that some entities are not healthy, will be displayed above the list. Make sure there is visible filtering with health state filter.	optional
displayCharts	Display charts	boolean	When true, the charts will be displayed above the list. Be aware of performance overhead with vast number of metrics and entities.	required
displayMicroCharts	Display micro charts	boolean	When true, micro charts will be displayed for added metrics. Be aware of performance overhead with vast number of metrics and entities.	optional
enableDetailsExpandability	Enable details expandable section	boolean	When true, detailed charts for each entity will be available.	required
numberOfVisibleCharts	Number of charts to display	integer	The number of charts to display above the list and in details section.	required
hideEmptyCharts	Hide empty charts	boolean	If true, All empty charts will be hidden. Decreases "Number of charts to display" to the number of available charts.	optional
charts	Charts	list	Define charts to display timeseries data in the entities list.	required
displayIcons	Display entity icon	boolean	When true, entity icon will be displayed in the name column.	required
columns	Columns	list	Define columns to show additional data in the entities list.	required
emptyState	Empty state definition	EmptyStateType	Specifies message shown when there are no entities found.	optional
initialSorting	Initial sorting definition	InitialSortingType	Specifies initial sorting configuration.	optional
filtering	Filtering	FilteringType	Specifies filtering configuration.	optional
conditions	List of conditions	set	All conditions from the list need to be fulfilled for the List of Entities to be visible	required

Request body objects

The `SplittingChartConfig` object

Property	Label	Type	Description	Required
displayChart	Display splitting chart	boolean	When true, splitting chart for this filter will be displayed	required

The `EntityFilterDefinition` object

Property	Label	Type	Description	Required
type	Type	text	-	required
entityTypes	Entity types list	set	List of entity types that are filtered by this filter. All of them must have defined relationship to entity.	required
displayName	Display name	text	-	required
freeText	Is free text filter	boolean	When true, user can type any text value. When false, user can only select one of the suggestions.	required
modifier	Text filter modifier	enum	Specifies the behavior of free text filter's value	required
defaultSearch	Is default search	boolean	When true, as user is typing it will suggest this key as default for searching. There can be only 1 default search filter in filtering.	required
distinct	Is distinct	boolean	When true, there can be only a single instance of this filter.	required
hidden	Is hidden	boolean	When true, this filter will be hidden.	optional
splittingChart	Splitting chart	SplittingChartConfig	Configure splitting chart for this filter.	optional

The `EntityFilterGroupDefinition` object

Property	Label	Type	Description	Required
displayName	Group display name	text	-	required
filters	Filters	list	Define entity filters.	required

The `FilteringType` object

Property	Label	Type	Description	Required
relationships	Entity relationships list	set	To filter related entities you need to define relationship between them. For example to filter by process attributes on a host list you need to add entity selector with relationship like this: `type(PROCESS_GROUP_INSTANCE), fromRelationship.isProcessOf(type(HOST))`. Instead of `type(HOST)` you can use variable `$(entityConditions)`. Relationships should cover all possible pairs of entity types in filters.	required
entityFilters	Entity filters list	list	-	required

The `InitialSortingType` object

Property	Label	Type	Description	Required
columnId	Column ID	text	Column ID is a unique identifier of column. There are several ID types for different column types: Entity column - 'name' Metric with selectable aggregation - 'metric-{metricDisplayName}-{aggregation}' Example: 'metric-CPU Usage-Average' metric without selectable aggregation - 'metric-{metricDisplayName}' Example: 'metric-CPU Usage' Attribute - 'attribute-{attributeKey}' Example: 'attribute-osType' Relation - 'attribute-{relationEntityType}-{relationDisplayName}' Example: 'attribute-CLOUD_APPLICATION-Workloads' Metric dimension (Metric Table only) - 'metricDimension-{dimensionKey}' Example: 'metricDimension-dt.entity.host'	required
order	Sorting order	enum	-	required

Property

Label

Type

Description

Required

columnId

Column ID

text

Column ID is a unique identifier of column. There are several ID types for different column types:

Entity column - 'name'
Metric with selectable aggregation - 'metric-{metricDisplayName}-{aggregation}' Example: 'metric-CPU Usage-Average'
metric without selectable aggregation - 'metric-{metricDisplayName}'
Example: 'metric-CPU Usage'
Attribute - 'attribute-{attributeKey}'
Example: 'attribute-osType'
Relation - 'attribute-{relationEntityType}-{relationDisplayName}'
Example: 'attribute-CLOUD_APPLICATION-Workloads'
Metric dimension (Metric Table only) - 'metricDimension-{dimensionKey}'
Example: 'metricDimension-dt.entity.host'

required

order

Sorting order

enum

required

The `EmptyStateType` object

Property	Label	Type	Description	Required
header	Message header	text	-	required
body	Message body	text	-	required

The `Threshold` object

Property	Label	Type	Description	Required
color	Color	text	RGB code of color	required
value	Threshold value	float	Value of the threshold. Area above this threshold will be marked by selected color	required

The `MetricSelector` object

Property	Label	Type	Description	Required
metricSelector	Metric selector expression	text	-	required
metricSelectorPage	Metric selector expression - page	text	A metric selector expression for a dedicated metric line This selector is used to gather data for currently selected page. It should point to the single value. By default, that selector is created based on main one. e.g. for `builtin:host.disk.free` selector, per-page one will be `builtin:host.disk.free$(entityFilter)$(userFilter):splitBy("dt.entity.disk")$(aggregation):last` For other examples, examine `pageSelector` field of metric object from screen definition generated on the entity screen. When providing custom selector, following placeholders needs to be included: $(entityFilter) - it is replaced with `filter` operator that adds context of currently visible rows. It is recommended to use directly after each metric key. e.g. for disk list it will be evaluated to `:filter(in("dt.entity.disk",entitySelector("entityId(DISK-01, DISK-02)")))` $(userFilter) - it is replaced with `filter` operator that corresponds to filters from filter bar above the table. It is recommended to use before last splitBy operator. $(aggregation) - it is replaced with aggregation operator based on selection above the chart. Should be as close to the end of expression as possible.	optional
metricSelectorSort	Metric selector expression - sort	text	A metric selector expression for a dedicated metric line This selector is used to gather data for currently sorted column. It should point to the single value. It queries data for whole table for given metric. By default, that selector is created based on main one. e.g. for `builtin:host.disk.free` selector, per-page one will be `builtin:host.disk.free$(entityFilter)$(userFilter):splitBy("dt.entity.disk")$(aggregation):last:sort(value(avg,$(sortOrder))):limit(X)` For other examples, examine `sortSelector` field of metric object from screen definition generated on the entity screen. When providing custom selector, following placeholders needs to be included: $(entityFilter) - it is replaced with `filter` operator that adds context of currently visible rows. It is recommended to use directly after each metric key. e.g. for disk list it will be evaluated to `:filter(in("dt.entity.disk",entitySelector(type(DISK) AND fromRelationship.isDiskOf(type(HOST),entityId(HOST-1)))))`, $(userFilter) - it is replaced with `filter` operator that corresponds to filters from filter bar above the table. It is recommended to use before last splitBy operator. $(aggregation) - it is replaced with aggregation operator based on selection above the chart. Should be as close to the end of expression as possible. $(sortOrder) - it is replaced with sort order constant from metric selector `descending` or `ascending`. Do not include limit operator. It will be appended automatically according to card configuration.	optional
metricSelectorDetailed	Metric selector expression - details	text	A metric selector expression for a dedicated metric line This selector is used to gather data for details section in table row. By default, that selector is created based on main one. e.g. for `builtin:host.disk.free` selector, per-page one will be `builtin:host.disk.free$(entityFilter)$(userFilter):splitBy("dt.entity.disk")$(aggregation)` For other examples, examine `detailsSelector` field of metric object from screen definition generated on the entity screen. When providing custom selector, following placeholders needs to be included: $(entityFilter) - it is replaced with `filter` operator that adds context of currently visible rows. It is recommended to use directly after each metric key. e.g. for disk list it will be evaluated to `:filter(in("dt.entity.disk",entitySelector(type(DISK) AND fromRelationship.isDiskOf(type(HOST),entityId(HOST-1)))))`, $(userFilter) - it is replaced with `filter` operator that corresponds to filters from filter bar above the table. It is recommended to use before last splitBy operator. $(aggregation) - it is replaced with aggregation operator based on selection above the chart. Should be as close to the end of expression as possible.	optional

The `SingleValueConfig` object

Property	Label	Type	Description	Required
metric	Metric	MetricSelector	Defines how to fetch data for the single value visualization, please note that it shows only the first enabled metric from the query and also various fold transformations needs to be explicitly defined here in the selector	required
defaultAggregation	Default aggregation	enum	Defines default aggregation of the chart timeseries. If not defined or selected one is not supported, it is deduced from metrics metadata.	optional
thresholds	List thresholds	set	List of defined thresholds for the chart	required
showTrend	Show trend	boolean	When true, the trend is visible	optional
showSparkline	Show sparkline	boolean	When true, the sparkline is visible	optional
displayName	Display name	text	Display name for value	optional
foldTransformation	Fold transformation	enum	Defines transformation method, which fold data into single value. If not defined, it is deduced automatically.	optional

The `ColorOverrides` object

Property	Label	Type	Description	Required
color	Color	text	RGB code of color	required
seriesName	Series Name	text	Series name should point to whole metric or single dimension name	required

The `PieChartConfig` object

Property	Label	Type	Description	Required
metric	Metric	MetricSelector	Defines how to fetch data for the pie chart, please note that various fold transformations needs to be explicitly defined here in the selector	required
defaultAggregation	Default aggregation	enum	Defines default aggregation of the chart timeseries. If not defined or selected one is not supported, it is deduced from metrics metadata.	optional
themeColor	Color theme	enum	-	optional
colorOverride	List of color overrides	set	There is possibility to override color of single series, even single dimension of a metric	required
showLegend	Show legend	boolean	When true, axis legend on the whole chart is visible	optional

The `XAxis` object

Property	Label	Type	Description	Required
name	Name	text	-	optional
visible	Is visible	boolean	When true, axis legend is visible	required

The `YAxis` object

Property	Label	Type	Description	Required
key	Y-Axis key	text	Y-axis key to be matched with metric's reference	required
name	Axis title	text	Axis title	optional
position	Position	enum	Pick a side for the axis	required
visible	Is visible	boolean	When true, axis is visible	required
min	Min	text	Minimal axis value	optional
max	Max	text	Maximal axis value	optional

The `VisualizationOptions` object

Property	Label	Type	Description	Required
themeColor	Color theme	enum	-	optional
seriesType	Series type	enum	-	optional
showLegend	Show legend	boolean	When true, axis legend on the whole chart is visible	optional

The `MetricVisualizationOptions` object

Property	Label	Type	Description	Required
themeColor	Color theme	enum	-	optional
seriesType	Series type	enum	-	optional
displayName	Display name	text	-	optional
colorOverride	List of color overrides	set	There is possibility to override color of single series, even single dimension of a metric	required

The `MetricDefinition` object

Property	Label	Type	Description	Required
metricSelector	Metric selector expression	text	A metric selector expression for a dedicated metric line For example, if you want to show the available disk space of a host, use `builtin:host.disk.free`. It also supports the ability to split by dimension, aggregate the selected metric and a lot more, for example: `builtin:host.disk.free:splitBy(dt.entity.disk):max` The filter for the ME id will be applied automatically. The Metric Browser gives an overview of all the metrics an the available operations for every metric.	required
metricSelectorPage	Metric selector expression - page	text	Override metric selector expression for current page This selector is used to gather data for currently selected page. It should point to the single value. By default, that selector is created based on main one. e.g. for `builtin:host.disk.free` selector, per-page one will be `builtin:host.disk.free$(entityFilter)$(userFilter):splitBy("dt.entity.disk")$(aggregation):last` For other examples, examine `pageSelector` field of metric object from screen definition generated on the entity screen. When providing custom selector, following placeholders needs to be included: $(entityFilter) - it is replaced with `filter` operator that adds context of currently visible rows. It is recommended to use directly after each metric key. e.g. for disk list it will be evaluated to `:filter(in("dt.entity.disk",entitySelector("entityId(DISK-01, DISK-02)")))` $(userFilter) - it is replaced with `filter` operator that corresponds to filters from filter bar above the table. It is recommended to use before last splitBy operator. $(aggregation) - it is replaced with aggregation operator based on selection above the chart. Should be as close to the end of expression as possible.	optional
metricSelectorSort	Metric selector expression - sort	text	A metric selector expression for a dedicated metric line This selector is used to gather data for currently sorted column. It should point to the single value. It queries data for whole table for given metric. By default, that selector is created based on main one. e.g. for `builtin:host.disk.free` selector, per-page one will be `builtin:host.disk.free$(entityFilter)$(userFilter):splitBy("dt.entity.disk")$(aggregation):last:sort(value(avg,$(sortOrder))):limit(X)` For other examples, examine `sortSelector` field of metric object from screen definition generated on the entity screen. When providing custom selector, following placeholders needs to be included: $(entityFilter) - it is replaced with `filter` operator that adds context of currently visible rows. It is recommended to use directly after each metric key. e.g. for disk list it will be evaluated to `:filter(in("dt.entity.disk",entitySelector(type(DISK) AND fromRelationship.isDiskOf(type(HOST),entityId(HOST-1)))))`, $(userFilter) - it is replaced with `filter` operator that corresponds to filters from filter bar above the table. It is recommended to use before last splitBy operator. $(aggregation) - it is replaced with aggregation operator based on selection above the chart. Should be as close to the end of expression as possible. $(sortOrder) - it is replaced with sort order constant from metric selector `descending` or `ascending`. Do not include limit operator. It will be appended automatically according to card configuration.	optional
metricSelectorDetailed	Metric selector expression - details	text	A metric selector expression for a dedicated metric line This selector is used to gather data for details section in table row. By default, that selector is created based on main one. e.g. for `builtin:host.disk.free` selector, per-page one will be `builtin:host.disk.free$(entityFilter)$(userFilter):splitBy("dt.entity.disk")$(aggregation)` For other examples, examine `detailsSelector` field of metric object from screen definition generated on the entity screen. When providing custom selector, following placeholders needs to be included: $(entityFilter) - it is replaced with `filter` operator that adds context of currently visible rows. It is recommended to use directly after each metric key. e.g. for disk list it will be evaluated to `:filter(in("dt.entity.disk",entitySelector(type(DISK) AND fromRelationship.isDiskOf(type(HOST),entityId(HOST-1)))))`, $(userFilter) - it is replaced with `filter` operator that corresponds to filters from filter bar above the table. It is recommended to use before last splitBy operator. $(aggregation) - it is replaced with aggregation operator based on selection above the chart. Should be as close to the end of expression as possible.	optional
visualization	Visualization	MetricVisualizationOptions	-	optional
yAxisKey	Y-Axis key	text	Select Y-axis to be matched with this metric by its key	optional

The `GraphChartConfig` object

Property	Label	Type	Description	Required
metrics	Metrics	list	Defines how to fetch data for a single line in the chart	required
defaultAggregation	Default aggregation	enum	Defines default aggregation of the chart timeseries. If not defined or selected one is not supported, it is deduced from metrics metadata.	optional
visualization	Visualization	VisualizationOptions	-	optional
thresholds	List thresholds	set	List of defined thresholds for the chart	required
yAxes	Y axes	list	You can control how each Y axis of your graph are displayed	required
xAxis	X axis	XAxis	You can control how X axis of your graph are displayed	optional
stacked	Stacked chart	boolean	When true, series on chart are stacked.	optional
connectGaps	Connect gaps	boolean	When true, gaps in charts will be connected even if there is truly no data	optional

The `ChartDefinition` object

Property	Label	Type	Description	Required
displayName	Display name	text	-	required
detailedChart	Detailed chart	boolean	If enabled, chart will be available in the expanded row of the entry in the table	required
chartAsColumn	Chart as column	boolean	If enabled, metric of that chart will generate table columns	required
conditions	List of conditions	set	All conditions from the list need to be fulfilled for the chart to be visible	required
visualizationType	Visualization Type	enum	-	required
graphChartConfig	-	GraphChartConfig	-	required
pieChartConfig	-	PieChartConfig	-	required
singleValueConfig	-	SingleValueConfig	-	required

The `AttributeType` object

Property	Label	Type	Description	Required
key	Attribute key	text	Use to reference desired attribute	required
displayName	Display name	text	Leave empty to resolve automatically	optional

The `RelationType` object

Property	Label	Type	Description	Required
entitySelectorTemplate	Entity selector template	text	An entity selector that is used to fetch the selected entities For example for a processes table where you want to show the process group this might look like this: `type(PROCESS_GROUP), toRelationships.isInstanceOf($(entityConditions))` Please mind that the `$(entityConditions)` is a placeholder for the current ME selector	required
displayName	Display name	text	-	required
displayAmount	Display amount	boolean	When true, in the column there will be displayed amount of related entities instead of name of related entity.	optional
fallbackMessage	Fallback Message	text	Display additional message if no entity is found.	optional

The `CustomColumnData` object

Property	Label	Type	Description	Required
key	Key	text	Use to reference desired attribute option key	required
value	Value	text	Provide option value	required

The `CustomType` object

Property	Label	Type	Description	Required
key	Custom column key	text	Use to reference desired custom column	required
displayName	Display name	text	-	required
data	Additional options	set	-	required

The `ColumnDefinition` object

Property	Label	Type	Description	Required
type	Column type	enum	Specifies the type of the column	required
attribute	Attribute options	AttributeType	-	required
relation	Relation options	RelationType	-	required
custom	Custom options	CustomType	-	required
conditions	List of conditions	set	All conditions from the list need to be fulfilled for the column to be visible	required

Settings API - Entities list cards schema table

Entities list cards (builtin:ua.entities-list)

Authentication

Parameters

Request body objects

The SplittingChartConfig object

The EntityFilterDefinition object

The EntityFilterGroupDefinition object

The FilteringType object

The InitialSortingType object

The EmptyStateType object

The Threshold object

The MetricSelector object

The SingleValueConfig object

The ColorOverrides object

The PieChartConfig object

The XAxis object

The YAxis object

The VisualizationOptions object

The MetricVisualizationOptions object

The MetricDefinition object

The GraphChartConfig object

The ChartDefinition object

The AttributeType object

The RelationType object

The CustomColumnData object

The CustomType object

The ColumnDefinition object