Creating new dashboards and building widgets
Creating widgets and dashboards requires knowledge of data and metrics. It is recommended to start by customizing dashboards from the Dashboard Gallery to understand how the data and metrics work.
To create your own dashboard, click + New Dashboard in the My Dashboards tab. Enter a name and description, and then click Save Dashboard. After the dashboard is created, click + Add Widget to start creating your first widget. If you close the Widget Builder, you can reopen it at any time by clicking + Add Widget.
Widget Builder
Widget Builder is a tool that lets you create widgets using data from ControlUp for Desktops, ControlUp for VDI, and ControlUp for Apps. It automatically generates the required queries in the background, so you can focus on selecting the data and visualization you need.
Data can be displayed in several visualization types, each with customization options to tailor the widget to your use case.
Name and Description
At the top of the left-hand panel in the Widget Builder, enter a widget name and description.
If you leave the description field blank, ControlUp automatically generates one by translating your selected data options into plain language. This auto-description saves time and helps with troubleshooting data-gathering issues. For example, if you create a widget from the ControlUp for Desktops Device Status index with the metric CPU Load %, and set it to show the top 3 devices, the auto-description reads:
“This widget queries the device_status index, groups by _device_name, and for each group calculates the average of cpuload.”
General
In the General section, select the data provider, source, metric, and aggregation type.
An aggregation combines or summarizes data so that it is easier to analyze. For example, you can count the number of records, calculate an average, find the minimum or maximum value, or show percentiles. Aggregations turn raw data into meaningful insights at a glance.
Not all metrics support the same aggregation options. For example, text values do not support minimum and maximum values, but you can use count or unique count on them.
Limitations
ControlUp for Desktops metrics with more than 1024 characters are not supported. For example, while you may be able to select fields such as event descriptions, values exceeding 1024 characters cannot be counted or filtered. This limitation also applies to the ControlUp for Desktops Query API.
ControlUp for Desktops indexes with overwrite enabled, such as _devices, do not support time-based filtering. A warning is shown in the Widget Builder. These indexes maintain only a single row per device, which is overwritten regularly, meaning no historical data is retained.
Curated and Other
The metrics and sources section is divided into two parts: Curated and Other.
Curated: Metrics that ControlUp has selected and preconfigured. With curated metrics, units are automatically applied, and any required filters or transformations are created for you. This makes it faster and easier to build widgets while ensuring that results are accurate and consistent.
Other: Non-curated metrics that you can configure manually.
Grouping & Sorting
The Grouping & Sorting section lets you organize and order your data.
Group By: Groups results by a field, such as device name, or another metric from the same data source selected in the General section. Grouping is available only for non-numeric fields.
Top value: Limits the number of displayed results, up to 50. For example, you can show the top 50 devices by average CPU usage.
Sort by: Sorts results by the selected metric, document count, or alphabetically.
Order: Displays results in descending order, from high to low, or ascending order, from low to high.
When working with Grouping & Sorting, carefully choose which metric you want to measure and what you want to group by. Mixing these up can lead to errors or meaningless results.
For example, to see how many devices there are per operating system, select the following:
Metric: Devices
Aggregation: Unique Count
Group By: OS Name
This gives you the number of devices running each operating system.
If you instead select OS Name as the metric with a Unique Count aggregation and group by Device, the result is always 1, because each device has only one operating system.
Use this as a guide:
Metric + Aggregation = What you want to measure.
Group By = How you want to break that measurement down.
Filters
With Filters, you can refine the data returned by your query. You can create multiple AND, OR, and NOT filters. All filters are processed at the same time.
This means you cannot build a sequential filter chain, such as AND → OR → AND. Instead, every filter you define is applied in parallel.
For OR filters, at least one condition must match.
There are three types of filters available in the Widget Builder:
Exact Match: Finds values that exactly match your filter. You can leave the value empty to search for empty values, or combine it with a NOT filter to exclude empty values.
Range: Used with numeric metrics. Defines ranges such as greater than, less than, or less than or equal to.
Wildcard: Allows broader searches by using wildcards (*). For example, filtering with
*workgroup*returns entries that contain the word workgroup anywhere in the value.
Transformations
With Transformations, you can perform additional actions on the data returned by your query. Currently, the Widget Builder supports math transformations, which let you add, subtract, multiply, or divide values. This is useful when you want to adjust or normalize metrics before visualizing them.
Widget Preview and Visualization Types
The Widget Preview area displays a live preview of your widget based on the selected data and visualization type.
At the bottom of the preview area, you can choose from the following visualization options:
Stat:
Displays a single summarized value.
Example: Show the average CPU usage across all devices in your environment.
Gauge
Visualizes a value against a scale, making it easy to see if it is within acceptable limits.
Example: Display disk utilization as a percentage with green, yellow, and red zones to highlight thresholds.
Time Series
Shows how values change over time.
Example: Track average logon duration across the past 7 days.
Table
Presents data in a structured, tabular format.
Example: List the top 10 devices with the highest memory consumption, along with their device names.
Grid
Displays raw data without aggregations. A Grid widget can display up to 10,000 results.
Donut
Breaks down a whole into proportional parts, similar to a pie chart.
Example: Show the percentage of devices per operating system version, such as Windows 10 and Windows 11.
Bar
Compares values side by side using bars.
Example: Display the top 5 applications by average CPU consumption.
Each visualization type can be customized with colors, units, labels, and formatting to fit your use case.
Depending on your data, some visualization types may not be compatible and are greyed out.
Grid Widget
You can select the Grid widget directly after choosing a data source. When using the Grid widget, aggregations, grouping, and sorting options are not available.
The metrics selector becomes a multi-select field, allowing you to choose multiple columns. You can also define the column order and select a metric to sort by. In addition, column widths can be adjusted in the Widget Preview.
Unit Family
The Unit Family setting controls how numeric values in your widgets are displayed. By assigning the correct unit family and base value, values are automatically formatted with the right scale and unit label, making your dashboards easier to interpret.
Available unit families include:
None: No unit is applied. Values are shown as plain numbers.
Custom: Define your own unit label to display next to the value.
Time: Display values as time durations, such as seconds, minutes, or hours.
Date: Format values as dates.
Data Size: Display values in storage units such as Bytes, Kilobytes, Megabytes, Gigabytes, or Terabytes.
Percentage: Show values as percentages.
Number: Apply number formatting without additional units.
After you select a unit family, you can further refine the display with a Base Unit. For example, for the Data Size family, you can select bytes as the base unit.
Example:
If you are displaying the amount of memory consumed, you can:
Choose Data Size as the unit family.
Set the base unit to bytes (B).
The widget then automatically shows values like 12.93 GB instead of a raw number like 13,876,345,678.
This ensures your widgets are accurate and user-friendly, reducing the need to manually interpret raw data values.
Variables
With Variables, you can make your dashboards more flexible and interactive. Variables act as dashboard-specific filters that can be applied across multiple widgets within the same dashboard.
You can create variables in edit mode by clicking Variables. Each variable requires a name, a data index, and a metric. After the variable is defined, the Variable Builder automatically retrieves unique values from the chosen metric column and presents them in a dropdown menu at the top of your dashboard.
Each dropdown displays the first 50 results by default, and supports search to display more options.
When you select a value from the variable dropdown, all widgets on the dashboard that use this variable as a filter value update automatically to reflect the filtered data.
You can configure up to eight variables per dashboard.
Variables can also be reflected in widget names by using {{VARIABLE NAME}} in the widget title.
Variables can include filters to narrow down the list of results they return. For example, you can create a variable that lists applications, but filter it on Event ID 1000 from the Event Log index. This creates a list of applications that have experienced crashes.
You can also use variables within other variable filters, allowing you to chain them together. For example, if Variable A contains application names and Variable B contains process paths, you can filter Variable B using application name = Variable A. This ensures that Variable B shows only processes related to the selected application.
Using Variables
Variables are applied within widget filters and must be used with an Exact Match filter or a Wildcard filter. Wildcard filters support using a variable with *.
When variables are available, the filter fields in the Widget Builder display the variable icon. Click the icon to select one of your defined variables.
After a variable is linked, the widget dynamically updates its results based on the value selected from the variable dropdown menu in the dashboard.
Example:
You create a variable called Application from the Application name metric. In the Widget Builder, you add a filter on Application name with an Exact Match condition. Instead of typing a static application name, click the variable icon and select the Application variable.
Now, when you switch the application in the variable dropdown menu at the top of your dashboard, all widgets connected to this variable update automatically to display data for that application.
Enable Variable Click-Through on Bar and Donut Widgets
Bar and Donut widgets include an option called Enable Variable Click-Through. When enabled, you can use a bar or donut slice as a variable value to filter your data.
After this option is enabled, the name of the widget appears as a selectable variable in the filter section.
When you click a bar or slice, it turns blue and displays a blue outline, indicating that it is selected as the value for the variable. You can clear this selection by clicking Clear Filter.
It is also possible to create a filter within the widget itself that uses a selected bar. In this mode, only the selected bar is displayed.
Clickable widgets are not counted toward the limit of eight variables.
Tip: Clickable bars and donuts work well as filters for Grid widgets.
Variable As Widget
In the Variable Builder, you have the option to display a variable as a widget. This removes the variable from the top of the dashboard and turns it into its own widget, which you can resize and position anywhere on the dashboard.
Note: Variable As Widget counts toward the limit of eight variables.
Edit mode
After adding your widget to the dashboard, you can move and resize it as needed. When you are happy with the layout, click Save Changes to save your dashboard and exit edit mode.
To adjust the layout again, click Edit Dashboard to re-enter edit mode and move or resize widgets. Clicking + Add Widget also automatically switches the dashboard to edit mode.