---
title: Variables
description: A Variable is a typed, named data point published by a Device or computed from other Variables. Variables back Dashboards, Alarms, and historical analysis.
source: https://documentation.controlcomtech.com/platform/variables
---

# Variables

A Variable is a typed, named data point. It either comes from a Device (a Device Variable) or is calculated from other Variables (a Virtual Variable). Variables back every Dashboard widget, every Alarm condition, and every historical query.

> **Workflow Stage: Collect**

## Overview

A Variable has a data type (`Number`, `String`, or `Boolean`), an optional unit, and a **Store Data** setting that decides whether history is retained. When storage is on, every value the Variable reports is kept as a timestamped point in the time-series store; when it is off, live values still flow through the platform but nothing is saved for later.

You read Variables through [Dashboards](https://documentation.controlcomtech.com/platform/dashboards/overview), [Platform Explorer](https://documentation.controlcomtech.com/platform/explorer), the API, and CSV/JSON export. You write them either by publishing from a Device or by defining a Virtual Variable expression. Variables are also the layer that [Assets](https://documentation.controlcomtech.com/platform/assets) are built from: the [Platform Overview](https://documentation.controlcomtech.com/platform/overview#component-relationships) walks through an example where five variables from one controller combine into a boiler and a pump asset.

## Device Variables

Device Variables belong to a Device and receive the values it publishes on a topic property. They typically hold sensor readings (temperature, voltage, pressure), device state (running or stopped, mode), diagnostic values (signal strength, error counts), or current configuration values.

They live on the **Variables** tab of the device. The table shows each variable's name, current value, topic property and flags. From here, the row menu edits a variable, toggles logging, opens it in Platform Explorer, sends a test value, or deletes it, and variables can be grouped into folders and exported.

![The Variables tab of a device in ControlCom Connect listing named data points with their values and topic properties](https://documentation.controlcomtech.com/images/device-administration/05-device-variables.png)

*The Variables tab of a device: every data point the device publishes, with its current value*

## Creating a Variable

On the device's **Variables** tab, click **New Variable**. The dialog asks for the Variable Name, an optional Description, the Topic Property path the Device publishes on, and the Type (`Number`, `String`, or `Boolean`). Enable the **Store Data** toggle if you want historical values available in the Visualize stage; without it, live data still arrives but is not saved. Click **Add Variable** to finish.

![The New Variable dialog in ControlCom Connect with name, description, topic property path and the Store Data toggle filled in](https://documentation.controlcomtech.com/images/device-administration/06-new-variable.png)

*The New Variable dialog: name, topic property path, type, and the Store Data toggle*

To register many data points at once, use **Import** on the same tab instead of creating them one by one. It opens an import page where you upload a CSV file; the guidelines on the page link a sample file showing the required format, the list of accepted units, and the folder ids for placing imported variables into folders.

![The variables import page in ControlCom Connect with a CSV upload dropzone and import guidelines](https://documentation.controlcomtech.com/images/device-administration/07-import-variables.png)

*Importing variables from a CSV file*

The [Creating a Variable](https://documentation.controlcomtech.com/build/edge-server/creating-a-variable) guide walks through this flow in the context of an Edge Server setup, where the variable's topic property becomes the target a Modbus, BACnet or OPC UA tag writes into.

## Virtual Variables

A Virtual Variable is computed from one or more source Variables using an expression, and behaves like any other Variable afterwards: it can be stored, charted, and alarmed on. Virtual Variables have their own list in the sidebar, separate from any single Device, because their sources can span Devices.

To create one, give it a name, a data type and an optional unit, then write the expression and pick the source Variables it references. The expression language supports:

| Category    | Operators / functions        |
| ----------- | ---------------------------- |
| Arithmetic  | `+`, `-`, `*`, `/`           |
| Math        | `min`, `max`, `avg`, `sum`   |
| Conditional | `if / then / else`           |
| Time-series | `timeShift`, `movingAverage` |
| String      | `concat`, `substring`        |
| Boolean     | `and`, `or`, `not`           |

Common patterns are aggregating across Devices, converting units, deriving thresholds (a Boolean indicator from a numeric reading), and filtering out invalid values. The [Expression Editor](https://documentation.controlcomtech.com/platform/expression-editor) reference covers the language in detail.

## Configuration

| Field          | Applies to       | Notes                                             |
| -------------- | ---------------- | ------------------------------------------------- |
| Name           | both             | Human-readable identifier.                        |
| Description    | both             | Optional.                                         |
| Data Type      | both             | `Number`, `String`, `Boolean`.                    |
| Unit           | numeric          | Optional.                                         |
| Topic Property | Device Variables | Topic path the Device publishes on.               |
| Short ID       | both             | Optional abbreviated identifier.                  |
| Store Data     | both             | If on, history is retained.                       |
| Scaling        | numeric          | Multiplier and offset applied to incoming values. |
| Validation     | numeric          | Accepted range.                                   |
| Filtering      | numeric          | Outlier rejection.                                |
| Deadband       | numeric          | Only log changes exceeding the threshold.         |

Data type and unit are set at configuration time. Changing them later is allowed, but downstream Dashboards and Alarms may need to be re-checked.

## Historical Data

When **Store Data** is on, the platform stores time-series points keyed by timestamp; retention depends on the subscription plan. You can query at two resolutions: **raw**, every individual value as received, or **aggregated**, bucketed by an interval (1 minute, 1 hour, 1 day, and so on) with an aggregation function (`avg`, `min`, `max`, `sum`, `count`, `first`, `last`).

The stored history feeds [Dashboards](https://documentation.controlcomtech.com/platform/dashboards/overview) for visual trends, [Platform Explorer](https://documentation.controlcomtech.com/platform/explorer) for interactive analysis, [Reports](https://documentation.controlcomtech.com/platform/reports) for scheduled or on-demand summaries, and the API and CSV/JSON export for downstream tools.