Dictionaries

A dictionary is a named, in-memory key-value store that can be referenced from instance attribute expressions and pipeline stages. Each entry maps a string key to a JSON value. Dictionary values are stored in memory and enable quick access for data purposes. Depending on the source type, a dictionary is either fixed at configuration time or refreshed periodically by a backing pipeline.

Configuration Settings

These settings apply to every dictionary regardless of source type.

Setting Description
Name Unique identifier used to reference the dictionary in expressions and stage configuration.
Description Free-text description displayed in the UI.
Group Logical grouping label for organising dictionaries in the list view.
Tags One or more tags for filtering.
Source Type Determines how the dictionary is populated. Either Dynamic or Static.

Source Types

Dynamic

A dynamic dictionary is populated by executing a backing pipeline. The dictionary is populated on first access and can be refreshed on a schedule via the expiration interval.

Setting Description
Backing Pipeline The pipeline responsible for populating the dictionary. Must return a complex object whose properties become the dictionary entries.
Expiration Interval How long cached entries remain valid before the next access triggers a refresh. Set to 0 (zero) to populate once and never refresh. Supports milliseconds, seconds, minutes, hours, and days.

Populating Dynamic Dictionary

When a dictionary is being fetched for the first time or the dictionary has expired due to the expiration interval, the Backing Pipeline will be called to refresh the dictionary. Any parameters configured on the backing pipeline reference will be passed to the pipeline call.

The pipeline must return a complex object (JSON object). Each property of the returned object becomes a dictionary entry: the property name is the key and the property value is the stored value.

Static

A static dictionary is defined entirely in configuration. Entries are loaded once on first access and never refreshed.

Setting Description
Definition A JSON object whose top-level properties become the dictionary entries. Must be a valid JSON object with at least one key-value pair.

Example definition:

{
  "zone_a": { "label": "Zone A", "threshold": 95 },
  "zone_b": { "label": "Zone B", "threshold": 80 }
}

Referencing Dictionaries

Instance Attribute Expressions

Dictionaries can be referenced in instance attribute expressions using the Dictionary reference type. The reference resolves to the full dictionary object, and dot-notation paths can be used to reach a specific entry or nested field.

Reference the entire dictionary as an object:

{{Dictionary.MyDictionary}}

Reference a specific entry by key:

{{Dictionary.MyDictionary.zone_a}}

{{Dictionary.MyDictionary}}["zone_a"]

Reference a nested field within an entry:

{{Dictionary.MyDictionary.zone_a.threshold}}

{{Dictionary.MyDictionary}}["zone_a"]["threshold"]

Pipeline Merge Read Stage

The Merge Read stage reads values from one or more sources and merges them into a single output object. This makes it straightforward to populate pipeline events with lookup data. This data can later be used for dynamically looking up values in the lookup data. For example, joining a device reading with a static zone configuration or a dynamically refreshed calibration table.

Viewing Current Values

The Values tab on a dictionary’s detail page shows the current in-memory entries as a searchable key-value table. Both keys and values are searchable. Values are displayed as formatted JSON. A refresh button re-fetches the current state from the runtime.

Constraints and Limitations

  • A dynamic dictionary’s backing pipeline cannot reference any dictionary.
    • This avoids recursive loops when trying to populate dictionaries.
  • Dictionary values are stored in memory only; there is no persistence across restarts. On startup, a dynamic dictionary will be re-populated on its first access.