Last updated:
Links
Dashboard Links connect two controls so that the value of one control can influence another control’s data or displayed value. A link is configured from the Base Control to a Target Control:
- Base Control: The control you select in the editor. Its data or value is affected by the link.
- Target Control: The linked control that supplies the value used by the Base Control.
Target Control (Customer dropdown, supplies selected customer) │ value changes; link is evaluated ▼Base Control (Orders grid, displays matching orders)For example, to filter an Orders grid using a Customer dropdown, select the Orders grid as the Base Control and link it to the Customer dropdown as the Target Control. The target influences the base, not the other way around.
Links are evaluated when a Target Control changes its value. A separate Refresh Control action can refresh a control with its existing configuration and current values; it does not change the links.
Configuration
Section titled “Configuration”Creating a link
Section titled “Creating a link”- Select the Base Control in the dashboard editor.
- Open the Linking tab, visible when a control is selected.
- Start adding a link and select a Target Control in the dialog.
- Choose the Link Type and configure the parameters shown for that type.
- Save the dashboard.
- Configure any necessary mappings manually, then save and test in the Viewer.
The Target Control selection excludes unusable controls. After choosing a Target Control, the Link Type list includes only compatible types. Types that have reached their allowed limit are also excluded.
Shared parameters
Section titled “Shared parameters”| Setting | Applies to | Description |
|---|---|---|
| Target Control | All links | Control providing the linked value. Fixed after link creation. |
| Link Type | All links | Determines how the value is used. Fixed after link creation. |
| Required | StartDateTime, EndDateTime, Filter, NumericalFilter, Occurrence, Header | When enabled, an unusable linked value resets the Base Control to its initialized state. |
| Header | Filter, NumericalFilter | Selects the Dataclip header to filter. Configurable in the link from version 5.2.0.7. |
| Condition | Filter, NumericalFilter | Comparison operator. Configurable in the link from version 5.2.0.7. |
| Ignore time | StartDateTime, EndDateTime | Expands a selected date to the appropriate start/end-of-day boundary. |
| Offset amount and unit | RelativeDateValue | Positive or negative relative date/time adjustment. |
| Link Name | Custom | Identifies the raw value to the receiving plugin. |
Required and reset behavior: If any required link on a Base Control lacks a usable value, the Base Control resets to the state in which it was initialized. A grid then shows no data; a label or filter returns to the value configured outside mappings. For textual Filter links, null and "" are unusable; for numerical and date values, null is unusable, while numeric 0 remains valid. A valid filter value with no matching records is not, by itself, an unusable linked value.
Link types
Section titled “Link types”| Link type | Compatible Target Control / purpose | Limits and notes |
|---|---|---|
| StartDateTime | DatePicker or TimeRange; filters from a start date/time | Maximum one per Base Control; uses the Dataclip’s unique DateTime header |
| EndDateTime | DatePicker or TimeRange; filters through an end date/time | Maximum one per Base Control; uses the Dataclip’s unique DateTime header |
| Occurrence | Selection controls (Dropdown, Selection Control, Search); selects a Dataclip occurrence | One Occurrence or Header per Base Control, combined |
| Header | Selection controls; selects a Dataclip header | Shares the one-link limit with Occurrence |
| Numeric | Numerical value used by a Pareto/Drilldown Base Control | Maximum one Numeric link per Target Control |
| Filter | Selection or textual input controls; filters a specified Dataclip header | Supports Required and a configurable textual condition |
| NumericalFilter | Numeric control; applies numerical comparisons to a specified header | Supports Required and a configurable numeric condition |
| Value | Calculation Control supplying a result to a Label or Gauge | Maximum one Value link per supported Base Control |
| BaseValue | Calculation Control supplying a base value to a Percentage or Delta Control | Maximum one BaseValue link per supported Base Control |
| TargetValue | Calculation Control supplying a target value to a Percentage or Delta Control | Maximum one TargetValue link per supported Base Control |
| RelativeDateValue | DatePicker supplying a reference date to another DatePicker | Maximum one per Base Control |
| Calendar | — | Currently unsupported |
| Custom | Supplies a raw value to a plugin | Multiple allowed; described last below |
Legacy types: StartDate and EndDate are obsolete and should not be used. The type internally called Numberic is displayed as Numeric.
Date and time links
Section titled “Date and time links”StartDateTime and EndDateTime are intended for filtering a period. The dashboard automatically uses the Dataclip’s single designated DateTime header. A Dataclip cannot have multiple designated DateTime headers. If none is configured, dashboard date filtering is not enabled. Unlike Forms, dashboard date links do not expose a Header ID selector.
The Ignore time setting depends on the value provided by the DatePicker or TimeRange. A DatePicker configured for date-only selection already has no user-selected time component. With Ignore time enabled:
| Link | Local boundary applied | Meaning |
|---|---|---|
| StartDateTime | 00:00:00 |
Include the selected start day from its beginning |
| EndDateTime | 23:59:59... |
Include the selected end day through its end |
The boundaries are interpreted in the user’s client timezone and converted to UTC+00:00 for transmitted values. For example, in the Netherlands on October 20, 2026 (CEST), local midnight is October 19 at 22:00 UTC.
Selection links: Occurrence and Header
Section titled “Selection links: Occurrence and Header”Occurrence links a selected Dataclip occurrence (row) to the Base Control. The selected value is linked directly to the occurrence value of the Dataclip mapped in the Target Control. Mapping can also determine the value shown to the user.
Header selects a Dataclip header (column) to change which measure the Base Control displays for the same occurrence. For example, a machine gauge could switch between Produced Count and To Produce Count. In practice, two side-by-side gauges are often clearer, so Header links are less commonly used.
Occurrence and Header use an Equals comparison. Only one of these two types may exist per Base Control: adding Occurrence excludes Header, and vice versa.
Filter and NumericalFilter
Section titled “Filter and NumericalFilter”Filter is the most common link. It applies a textual value to a selected Dataclip header. For selection controls, the mapping selects a single header and the selection list shows the distinct values in that column. Textual input controls, including Filter and Barcode Filter controls, can supply values from user input or configured variables.
NumericalFilter works similarly but uses a Numeric Target Control and numerical comparison operators.
| Textual Filter condition | Meaning |
|---|---|
| Equals | Exact match |
| Contains | Text contains the provided value |
| EndsWith | Text ends with the provided value |
| StartsWith | Text begins with the provided value |
| NumericalFilter condition | Meaning |
|---|---|
| Equals | = |
| GreaterThan | > |
| GreaterOrEqual | >= |
| LessThan | < |
| LessOrEqual | <= |
Version 5.2.0.7 change: The filtered Header and Condition are configured on the link. Before this version, the header was selected through mapping and the condition was configured on the linked control.
When multiple links filter the same Base Control, the system evaluates how to combine them using both headers and conditions. Examples include:
(Customer = "Customer A" OR Customer = "Customer B")AND Status = "Open"AND Region = "Europe"Amount >= 100 AND Amount <= 500Different headers commonly combine with AND; multiple Equals values on the same header can combine with OR; a numerical range uses AND. Do not assume a universal AND/OR rule for all operator combinations: the system evaluates the combination.
Calculation and numeric links
Section titled “Calculation and numeric links”A Value link passes a Calculation Control result to a Label or Gauge. BaseValue and TargetValue pass Calculation Control results to Percentage and Delta Controls. A Percentage or Delta Control can have both BaseValue and TargetValue links simultaneously, but does not support Value. Each supported link type is limited to one instance per Base Control. One Calculation Control can supply multiple Base Controls.
A Numeric link supplies the number of columns to show at the current level of a Pareto/Drilldown control. For example, a target value of 5 shows five columns at that drilldown level. It has no additional link-specific parameter beyond the supplied value.
RelativeDateValue
Section titled “RelativeDateValue”This links two DatePickers. The Target DatePicker supplies the reference date and the Base DatePicker displays that date plus the configured offset. The offset accepts positive or negative amounts in minutes, hours, days, weeks, months, or years. For example, -2 days displays a date two days before the target value. Only one RelativeDateValue link is allowed per Base Control.
Custom links
Section titled “Custom links”Custom links pass a raw Target Control value to a plugin, which interprets it in its own way. Each link has a Link Name so the plugin can recognize the value. Multiple Custom links are allowed. Names need not be unique, but unique descriptive names (for example SelectedCustomer and SelectedRegion) are recommended to avoid ambiguity inside the plugin.
Example: Filter orders by customer and date range
Section titled “Example: Filter orders by customer and date range”- Configure an Orders grid as the Base Control.
- Add a Filter link to a Customer dropdown, selecting the customer header and comparison condition.
- Add StartDateTime and EndDateTime links to DatePicker or TimeRange controls. Ensure the Orders Dataclip has its unique DateTime header configured.
- Set Required on whichever values must be present before the grid should show data.
- Configure the necessary mappings manually through the Mapping Footer.
- Save the dashboard, open it in the Viewer, and change the linked values to verify that the grid responds.
Initial loading and dependency chains
Section titled “Initial loading and dependency chains”All linked controls start their initial loading process when the dashboard opens. Where a Base Control requires values from a Target Control that itself depends on another control, loading proceeds in layers as required upstream values become available.
Region dropdown (loads regions) → Customer dropdown (loads customers for region) → Orders grid (loads orders for customer)Design dependencies in a clear direction and avoid circular references such as A → B → C → A. Circular dependencies should be prevented during design; automatic cycle detection is not asserted here.
Editing and removing links
Section titled “Editing and removing links”The Linking tab lists existing links and allows individual deletion. Once created, a link’s Target Control and Link Type cannot be changed; delete and recreate the link to change either. Editable parameters include Header, Required, Condition, and Date Offset where applicable. Deleting a linked control automatically cleans up links referencing it. A removed link is no longer considered in link evaluation. Mappings are not automatically removed, and mappings depending on the deleted link may appear broken when the Mapping Footer is opened. Save the dashboard after changes.
Mapping
Section titled “Mapping”Linking is normally followed by mapping. Links define how controls influence one another; mappings connect relevant controls to Dataclip data. Open mapping manually for each relevant control after configuring links. Removing a link does not remove dependent mappings and may leave broken mappings. See Mapping Footer.
- Start with the Base Control: choose the control whose data or displayed value should change.
- Create links first, then manually open the Mapping Footer for each relevant control. Linking does not open or configure mapping automatically.
- Not all links need additional mapping: Value, BaseValue, TargetValue, and RelativeDateValue can function without mapping for the link itself. Filtering links commonly involve mapping; requirements depend on the Base Control’s data configuration.
- Use Required when a Base Control should not display linked data until all mandatory Target Control values are available.
- Reuse one Calculation Control across multiple receiving controls where appropriate.
- Keep dependency chains clear and avoid circular references.
- After changing or deleting links, inspect affected mappings for broken references.
- Save changes and test the actual behavior in the Viewer.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Possible cause | What to check |
|---|---|---|
| Grid shows no data; label or filter returns to its configured value | One or more Required links have unusable values | Check every Required link; a single missing required value resets the Base Control |
| Start/end date filtering unavailable | No designated DateTime header on the Dataclip | Configure the unique DateTime header |
| Unexpected date range or end-day exclusion | Ignore time or client timezone interpretation | Check Ignore time and the local-to-UTC boundary conversion |
| Link type or Target Control not listed | Incompatible control or link limit already reached | Check the selected control and existing links, including the shared Occurrence/Header limit |
| Filter results differ from expectations | Wrong Header or Condition, or multiple filter conditions interact | Inspect link configuration and combined filter behavior |
| Mapping appears broken after deleting a link | Mapping references the removed link | Open Mapping Footer and repair the affected mapping |
| Control does not update as expected | Incorrect Target Control value, configuration, mapping, or unsaved changes | Verify the link, save, and test in Viewer |
| Initial values load in an unexpected order | A control depends on upstream linked values | Review the layered dependency chain and Required settings |