Skip to main content

Data Point Properties Reference

Every data point in Mango has a set of configurable properties that control how values are identified, displayed, logged, charted, and purged. These properties are shared across all data source types, while the point locator settings are specific to each protocol. This page provides a complete reference for all data point properties.

Identity Properties​

Point Name​

The Point name is a required field that serves as the primary visual identifier for the data point throughout the system. It appears in watch lists, charts, event messages, and reports. Choose a descriptive name that makes the point easy to identify, such as "AHU-1 Supply Air Temp" or "Boiler Room Humidity".

Device Name​

The Device name supplements the point name when displayed in lists alongside other points. Together they form the "extended point name" (displayed as "Device Name - Point Name"). The device name defaults to the data source name but can be changed to any value. Using meaningful device names is important when multiple data sources have points with similar names.

Export ID (XID)​

The Export ID (XID) is a required, globally unique text identifier. An XID is auto-generated when the point is created, but you can customize it to be more descriptive (e.g., DP_Bldg1_AHU1_SAT). XIDs are used in:

  • JSON configuration import/export
  • REST API queries and references
  • Cross-system configuration synchronization
  • CSV import/export operations
caution

Changing a point's XID after it has been referenced by event handlers, watch lists, dashboards, or published points will break those references. Plan your XID naming convention before deploying at scale.

Permissions​

Read Permission​

The Read permission determines which user roles can view the point's values in watch lists, charts, the data point details page, and other views. Assign one or more roles to grant read access.

Set Permission​

The Set permission determines which user roles can write values to the point (for settable points). This applies to manual value sets from the UI, REST API write operations, and set point event handlers.

Units and Display​

Unit​

The Unit specifies the engineering unit of the raw value stored by the data point. Type the unit symbol directly (e.g., kg, L, mA, Hz, lb, psi). Mango uses the JScience library for unit handling and supports:

  • SI units with all standard prefixes: W (watt), kW (kilowatt), MW (megawatt), mA (milliamp)
  • Non-SI units: psi, rpm, btu, ppm, ppb, thm
  • Temperature aliases: Celsius or °C, Fahrenheit or °F
  • Compound units: m/s^2 (acceleration), m^2/s (kinematic viscosity), kWh (kilowatt-hours), gpm (gallons per minute)

Displayed Unit​

The Displayed unit specifies which unit the text renderer should convert to when displaying the value. For example, if the raw unit is °C but users prefer Fahrenheit, set the displayed unit to °F and Mango will perform the conversion automatically.

Integral Unit​

The Integral unit specifies the unit used when displaying the integrated total in point statistics. For example, a power point in kW might use kWh as its integral unit. This affects how statistics are displayed on the data point details page.

Chart Color​

The Chart color sets the default line color for the point in multi-point chart images. Values can be HTML hex codes (e.g., #2468AC) or named HTML colors (e.g., red, dodgerblue, forestgreen).

Plot Type​

The Plot type determines how values are visually connected on a chart:

Plot TypeDescription
LineDraws straight lines between consecutive values
SmoothApplies a smoothing algorithm between values for a curved appearance
StepConnects values using only right angles (useful for discrete state changes)
BarDraws a vertical bar for each data value

Text Renderers​

A text renderer converts raw point values into human-readable display text. The available renderer types depend on the point's data type.

Binary Renderers​

RendererDescription
PlainDisplays the raw value as 0 or 1
BinaryMaps the two binary states to custom text labels (e.g., "Off" / "On", "Closed" / "Open") with optional distinctive colors for each state

Numeric Renderers​

RendererDescription
PlainDisplays the raw numeric value without formatting
AnalogFormats the value using a Java number format pattern (e.g., 0.00 for two decimal places) with an optional suffix for units
RangeMaps numeric ranges to text labels with optional colors (e.g., 0-30 = "Cold", 31-70 = "Normal", 71-100 = "Hot"). Supports value interpolation using ${value} in the label text
TimeInterprets the numeric value as a timestamp and formats it using a date/time pattern (e.g., MMM d, yyyy HH:mm:ss). A millisecond conversion exponent adjusts the value to milliseconds

Multistate Renderers​

RendererDescription
PlainDisplays the raw integer value
MultistateMaps integer states to text labels with optional colors (e.g., 0 = "Off", 1 = "Heat", 2 = "Cool"). Undefined states display the raw value

Alphanumeric Renderers​

RendererDescription
PlainDisplays the raw text value with an optional suffix

Logging Settings​

Logging settings control when and how point values are written to the database.

Logging Type​

TypeDescriptionBest For
When point value changesLogs only when the value changes (default). For numeric points, a Tolerance (deadband) can be set so values are logged only if the absolute change exceeds the tolerance.Most use cases -- good balance of data quality and storage efficiency
All dataLogs every value update regardless of whether the value changed.Cases where every update matters (e.g., metering), but generates large amounts of data
Do not logPrevents any value from being stored in the database. Chart renderers will not function.Transient values only needed for real-time display or event detection
IntervalLogs at a fixed interval independent of the data source poll rate. Can log the instantaneous value or a statistic (average, minimum, maximum, etc.) over the interval.High-frequency polling where only periodic snapshots are needed
Interval and point value changeCombines "when point value changes" logic with a guaranteed interval log if no change occurs within the period.Points that change infrequently but where periodic confirmation of the current value is needed
When point timestamp changesSimilar to "when value changes" but compares timestamps instead of values.Points receiving historical or externally timestamped data

Average Interval Logging Window​

When using Interval logging with the Average value type, you can override the default sample window by checking Override interval logging sample window and specifying a Sample window size. This controls how many recent samples are averaged together. The average is timestamped at the midpoint of the window, and no value is computed until the window is full.

Discard Extreme Values​

When Discard extreme values is enabled, values below the Discard low limit or above the Discard high limit are silently dropped and not stored. NaN and Infinity values are also discarded. This is useful for filtering out errant sensor readings.

Rollup Settings​

The Rollup property sets the default statistical aggregation used when a chart or query requests the point's "default" rollup. Available rollup types include: Average, Minimum, Maximum, Sum, Count, First, Last, and others depending on the data type.

The Rollup period and Rollup period type define the time bucket size for the default rollup. For example, a 15-minute average rollup would aggregate values into 15-minute windows and compute the average of each window.

Simplify Algorithm​

Data sets can be processed through a simplification algorithm to reduce the number of values while preserving the overall shape of the data. Two modes are available:

  • Target: Specify the desired number of output values. The algorithm selects the most significant points to keep.
  • Tolerance: Specify a significance threshold. Minor variations below the tolerance are smoothed out.

The Simplify argument provides the target count or tolerance value, depending on the selected mode.

Purge Settings​

Purge settings determine how long historical values are retained in the database. The automatic purge process runs daily at 3:05 AM local time.

By default, a data point inherits the purge settings from its parent data source. To override this, enable Override data source purge settings and specify a custom retention period (e.g., 1 year, 6 months, 30 days).

warning

Setting very long purge periods or disabling purge entirely can lead to significant database growth over time, which may degrade query performance. Monitor your database size and adjust purge settings accordingly.

Default Cache Size​

The Default cache size controls how many recent values are held in memory. Cached values are used for:

  • Real-time display on the data point details page
  • Event detector evaluation
  • Combining with database values when querying recent data

A larger cache can improve performance for frequently accessed points but consumes more heap memory. For most points, the default value is appropriate. Extremely high cache sizes across many points can lead to out-of-memory conditions.

Prevent Extreme Sets​

The Prevent extreme sets option restricts the range of values that can be written to a settable point. When enabled, any attempt to set a value below the Low set limit or above the High set limit is rejected. This provides a safety net against operator errors or misconfigured automation that could send dangerous values to field devices.