Widget Builder

Note:

This feature is available only to users licensed for ControlUp for Desktops and ControlUp for Apps.

Widget Builder is a powerful tool for creating widgets from any data in ControlUp for Desktops. It automatically generates the necessary Elasticsearch queries in the background, so you can focus on choosing the data and visualizations you need.

It contains two tabs: Widget Presets and Builder.
The left section of the screen in both tabs is used to configure or show your preferred data, and the right side shows a preview of the widget, with customizable visualization settings of this data.
The preview is based on the data and visualization type that you select.

Data can be displayed in one of six visualization types, each with extensive customization options to fit your use case.

Create a New Widget

When adding widgets to a dashboard, you can choose between using preset widgets containing all relevant data, importing a shared widget, or building a widget from scratch, if you want to use data indexes and metrics that are not included in the Widget Presets list.

1. Click + New Dashboard in the My Dashboards or Shared Dashboard tabs.

2. In the New Dashboard pop-up window, enter a name and description, then click Save Dashboard.
   The Widget Builder automatically opens and you can start creating your widget.
   Note: If you close the Builder, you can reopen it at any time by clicking + Add Widget at the top of the page.

3. Select how to create your widget: use a preset ControlUp widget, import a widget, or create a dashboard from scratch.

Use Preset Widgets

To make it easier to build your first widgets, the Widget Builder includes a Widget Presets with a list of built-in widgets, covering a wide range of use cases.
You can select any preset to instantly view your data with the visualization type you choose.

• If the preset widget suits your needs, click Add to Dashboard.

• To use the preset as a starting point and adjust it to your requirements, click Customize This Widget.
  This opens the Builder tab, where you can configure the widget in detail.

Build a widget from scratch

If you want to create your own custom widget, with data and metrics not included in the preset widgets, open the Builder tab or click Build from scratch at the bottom of the Widget Presets tab. This opens the Widget Builder.

Start building your widget by entering the required information in the widget sections:

• Index - Select a data index from ControlUp for Desktops (custom or built-in).

• Metric - Select a field within an index.
  Note: Metric fields larger then 1024 characters are not supported.

• Aggregations - Apply aggregations (Average. Count, Highest Value, Lowest Value, Percentiles, Total, Unique Count).

• Group metrics - Group using other metrics, top metrics, sort by, order (ascending/descending or Document Count).

• Conditions - Apply AND, OR or Not conditions to data.

• Variables - filter by predefined variables.

• Transformations - transform data with basic math (+, −, ×, ÷)

• Preview - Preview your widget before saving.

• Visualization type - Choose a visualization type (stat, gauge, time series, table, donut, bar).

• Customize visualization settings (colors, units, callouts, orientation, etc.).

• Raw Data - View raw data and the Elasticsearch (ES) query.

• Import the configuration of a widget.

• Enable a JSON editor tab to view or edit widget JSON directly.

  • The Expert JSON editor allows advanced users to add extra aggregations and data indexes directly in code .

Name and Description

At the top of the Builder, enter a name and description for your widget.
If you leave the description blank, ControlUp automatically generates one by translating your selected data options into plain language.
This auto-description not only saves time, but also helps with troubleshooting and data gathering issues.

For example:
If you create a widget from the 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_statusindex, groups by device_name, and for each group calculates the average of cpuload.”

This helps you quickly understand what a widget does and simplifies troubleshooting.

General

In the General section you can select a data index, a metric to measure, or an aggregation type to apply.
Aggregation is a way of combining or summarizing data so that it becomes easier to analyze.
For example, you can count the number of records, calculate an average (AVG), find minimum or maximum values, or show percentiles.
Using aggregations turns raw data into meaningful insights at a glance.
Note: Not all metrics support the same aggregation options. For example, text values don’t use min and max values, but you can use count or unique count on them.

Curated and Other

The Index and Metrics section includes two parts:

• Curated - Metrics that ControlUp picked and pre-configured for you.
  Units are automatically applied, and any required filters (such as ranges) or transformations are created for you.
  This helps you build widgets faster, while ensuring that the results are accurate and consistent.

• Other - non-curated metrics that you can configure manually.

Grouping & Sorting

You can group your data results by field, number of results displayed, sort metrics and display order.

• Group By - Allows you to group results, for example by Device Name or another metric from the same data index that you selected in the General section.
  Note: Grouping is only possible on non-numeric fields.

• Top value - Enables you to limit the number of displayed results (up to 50). For example, show the top 50 devices by average CPU usage.

• Sort by - Lets you sort by metric value, document count, or alphabetically.

• Order - displays results in ascending (low to high) or descending (high to low) order.

When working with Grouping & Sorting, choose your metrics and grouping carefully - mismatched combinations can lead to errors or meaningless results.

Example:
To count the number of devices running on each operating system, select the following:

• Metric: Devices

• Aggregation: Unique Count

• Group By: OS Name

If, instead, you reverse that and select OS Name for the metric, with a Unique Count aggregation and Device for Group by, the result will always be 1, because each device has only one OS.

Filters

Filters enable you refine the results returned by your query. You can create multiple AND, OR and NOT filters, which will all be processed at the same time.
This means you can’t build a sequential filter chain (for example, AND → OR → AND). Instead, every filter you define is applied in parallel.

For OR filters, it is always required that at least one condition must match.

There are three types of filters available in the Widget Builder, that you select in the first dropdown list:

• Exact Match: Returns only values that exactly match your filter. You can leave it blank to find empty values, or combine it with a NOT filter to exclude empty values.

• Range: Used with numeric metrics. Defines ‘greater than’, ‘less than’, or ‘equal to’.

• Wildcard: Allows broader searches for partial matches by using wildcards (*).
  For example, filtering *workgroup* using a wildcard returns all entries containing 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 visualization.

Select a visualization type

At the bottom of the Builder preview, you can select one of six visualization options:

• Stat
  Displays a single summarized value.
  Example: Show the average CPU usage across all devices.

• Gauge
  Shows a value against a scale, making it easy to see if it’s within acceptable limits.
  Example: Display disk utilization as a percentage with color-coded zones (green, yellow, and red) to highlight thresholds.

• Time Series
  Displays trends over time.
  Example: Track average logon duration over the past 7 days.

• Table
  Presents data in a structured, tabular format.
  Example: List the top 10 devices with the highest memory consumption.

• Donut
  Breaks down a whole into proportional parts, similar to a pie chart.
  Example: Show the percentage of devices per operating system version (Windows 10, Windows 11, and so on).

• Bar

  Compares multiple values side by side using bars.
  Example: Display the top 5 applications by average CPU consumption.

Note:

• Some visualization types might not be available, depending on your data. In such a case, they are greyed out.

• Each visualization type can be further customized with colors, units, labels, and formatting, to best suit your use case.

Unit Family

The Unit Family setting allows you to control how numeric values in your widget are displayed. By assigning the correct unit family, values are automatically formatted with the right scale and unit label, making your dashboards easier to interpret.

The available unit families are:

• 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 (for example, seconds, minutes, 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.

You can further refine the display by selecting a Base Unit (for example, bytes from the Data Size family).

Example: If you are measuring the amount of memory consumed, choose Data Size as the unit family, and 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 both accurate and user-friendly, helping interpret raw data values.

Configured Variables

The Variable Builder now automatically retrieves all unique values from the chosen metric column and displays them in a dropdown menu at the top of your dashboard.

Selecting a value from the variable dropdown list filters all the widgets that use this variable.
You can also insert variables in widget names by using {{VARIABLE NAME}} in their title.

How to use variables

Variables are applied within widget filters, and must be used with an Exact Match filter.
When variables are available, the Widget Builder displays a variable icon next to compatible fields.
Clicking this icon allows you to select one of your configured variables.

To link a variable:

1. In your widget filter, select Exact Match.

2. Click the variable icon and choose one of your configured variables.

The widget now updates automatically when a new variable value is selected from the dashboard dropdown.

Example:
You create a variable called Device from the Device Name metric.
In the Widget Builder, add a filter for Device Name with an Exact Match condition.
Instead of typing a device name, click the icon and select the Device variable.
Now, when you select the device in the variable dropdown list at the top of your dashboard, all widgets connected to this variable automatically update and show data for that device.

For more information on variables, see Variables and Add Variables.