Workflows¶

Workflows are continuous pipelines that automate the process of extracting equipment and labeling points from raw data. A workflow watches for new or changed points in an input layer, applies extraction and pattern-matching rules, and stages the computed changes for review before writing them to the model layer.

Workflows combine the equipment extraction and point labeling steps into a single, manageable unit that can be created, edited, previewed, and re-run as data changes.

Workflow Lifecycle¶

flowchart LR
  create[Create Workflow]
    --> evaluate[Evaluate Points]
    --> stage[Stage Changes]
    --> preview[Preview]
    --> apply[Apply Changes]

1. Create a workflow using the creation wizard or the workflow editor.
2. The workflow immediately evaluates all matching points and computes changes.
3. Changes are staged -- nothing is written to the database yet.
4. Preview the pending changes to verify they are correct.
5. Apply the changes to write them to the model layer.

After applying, the workflow continues to watch for new or changed points and will stage additional changes as needed.

How a point is evaluated¶

Each point passes through a three-step pipeline inside the workflow engine:

flowchart LR
  enrich["Sibling Enrichment\n(copy attrs from siblings)"]
    --> extract["Equipment Extraction\n(derive equipment ID)"]
    --> label["Pattern Matching\n(assign point class)"]

Sibling enrichment runs first so that any attributes it adds are available to both extraction and pattern-matching in the same pass. If no enrichment is configured the first step is a no-op.

Creating a Workflow¶

Workflows are created from the Workflows page in the management console. Click Create to open the creation wizard, which guides you through each step.

Step 1: Task Selection¶

Choose what the workflow will do:

• Label Points -- assign semantic point classes to raw points using pattern-matching rules.
• Map Equipment -- extract equipment identifiers from point attributes to create equipment instances.
• Both -- extract equipment and label points in a single workflow.

Step 2: Define Equipment Type¶

(Only for Map Equipment or Both)

Select an existing equipment type or create a new one. An equipment type defines the kind of equipment being modeled (VAV, AHU, etc.) along with its expected point classes, marker tags, and relationships. See Equipment Extraction for more on equipment types.

Step 3: Select Points¶

Configure filters to select which points the workflow operates on. For example, you might filter by vendor name, device, or object name pattern to select all points belonging to a particular type of equipment. Leaving the filter empty selects all points.

Step 4: Create Identifiers¶

(Only for Map Equipment or Both)

Define extraction rules that derive an equipment identifier from a point attribute. The goal is for all points belonging to the same piece of equipment to produce the same identifier.

For example, points named VAV-101 Zone Temp and VAV-101 Damper Cmd should both produce the identifier VAV-101.

Available extraction operations:

• Split -- split the attribute on a delimiter and keep specific segments. For example, splitting VAV-101 Zone Temp on a space and keeping the first segment produces VAV-101.
• Find and Replace -- apply a regex find-and-replace to transform the attribute value.
• Drop -- remove matching text from the value.
• Contains -- filter to only include points where the attribute contains specific text.
• Convert Case -- convert to uppercase or lowercase.

These operations can be chained together. The extraction preview shows the resulting equipment IDs in real time as rules are configured.

Step 5: Create Patterns¶

(Only for Label Points or Both)

Define pattern-matching rules that assign a point class to each point. Each pattern specifies:

• An input pattern -- a regular expression or exact match against a point attribute (typically the point name).
• A point class -- the semantic label to assign (e.g., zone-temp-sensor, damper-cmd).
• Optional output attributes such as trending period, CoV increment, and site reference.

The Pattern Finder tool can help discover patterns by analyzing the names of the selected points and suggesting groupings.

Naming and Saving¶

After completing the wizard steps, enter a name for the workflow and click Create. The workflow begins evaluating immediately.

The Workflow Editor¶

After creation, workflows can be edited from the Workflows page by clicking Edit on a workflow card.

The workflow editor is divided into two main sections:

Edit Rule¶

The top section configures three aspects of the workflow:

• Equipment Type -- the type of equipment this workflow creates.
• Points -- the filter query that selects which points are processed by this workflow, along with a count of matching points.
• Equipment ID Extraction -- the string extraction rules used to derive equipment identifiers from point attributes.

Click Edit on any of these tiles to modify them.

Point Labels¶

The bottom section contains a spreadsheet-style template grid for defining pattern-matching rules. This grid uses a CSV-like format with input columns and output columns:

• Columns prefixed with $in. are input rules that match against point attributes. A pattern like /Zone.*Temp/ matches any value containing "Zone" followed by "Temp". Exact strings match literally.
• Columns prefixed with $out. are output rules that set attributes on matching points in the model layer.

Output values support string interpolation where values enclosed in braces ({}) are replaced by the matching point's attributes or by named capture groups from input regexes.

You can add rows manually, use the Pattern Finder to discover patterns automatically, or Import Rows from existing points.

Previewing and Applying Changes¶

Workflows stage all computed changes before writing them. This lets you verify the results before anything is modified in the database.

From the Workflows page, each workflow card shows:

• The workflow state (Ready, Restarting, or Applying).
• The number of pending changes.

Click Preview on a workflow card (or Preview Changes in the editor) to open the pending changes panel. This shows each change that will be made, grouped by equipment and point. Review the changes and click Apply to write them to the model layer, or close the panel to leave them staged.

Sibling Enrichment¶

Building automation systems often store useful metadata on a single "description" or "program" point rather than on every individual sensor and command point. For example, a BACnet controller might expose one OBJECT_PROGRAM point that carries the floor number, zone label, or system identifier for all the I/O points on that controller. The extraction and labeling rules need those values, but the individual points don't have them.

Sibling enrichment solves this. Before extraction and labeling run, the workflow looks up "sibling" points -- other points that share a common identifier -- and copies selected attributes from them onto each matched point. The point class rules then see the enriched attributes as if they were native to the point.

A concrete example¶

Suppose you have these points:

You want to copy description from the Program point onto the two I/O points so that the workflow can use it for labeling.

With sibling enrichment configured as:

• Key extractor: split name on . and keep segment 0 → produces FCU-12
• Copy attrs: description → description

the engine groups all three points under the key FCU-12, takes the description value from whichever group member has it, and injects it onto the other two points before their extraction rules run.

How grouping works¶

flowchart TB
  subgraph "Points matching the workflow query"
    A["FCU-12.ZoneTemp"]
    B["FCU-12.FanSpd"]
    C["FCU-12.Program\n(description=Floor 3 East Wing)"]
    D["FCU-11.ZoneTemp"]
    E["FCU-11.Program\n(description=Floor 2 West Wing)"]
  end

  subgraph "After key extraction (split on '.')"
    G12["Group: FCU-12\nreduced → {description: Floor 3 East Wing}"]
    G11["Group: FCU-11\nreduced → {description: Floor 2 West Wing}"]
  end

  A -->|key = FCU-12| G12
  B -->|key = FCU-12| G12
  C -->|key = FCU-12| G12
  D -->|key = FCU-11| G11
  E -->|key = FCU-11| G11

  G12 -->|"copy description →\nonto FCU-12.ZoneTemp\nonto FCU-12.FanSpd"| result["Points now carry\ndescription for extraction"]
  G11 -->|"copy description →\nonto FCU-11.ZoneTemp"| result

Each point in the group contributes its source attributes to a shared pool. By default the first non-empty value wins across the group (so the Program point's value fills in the blanks on the I/O points).

Configuring enrichment¶

Enrichment is optional. In the workflow editor, scroll to the Enrichment section and click Configure enrichment to open the configuration panel.

Key extractor¶

The key extractor derives the group key from each point's attributes. All points that produce the same key become siblings of one another.

Use the same extraction function editor as the equipment ID step:

• Attribute-based (most common) -- select one or more attributes and optionally apply split/replace/drop rules. For example, select name and split on . keeping segment 0 to extract the controller prefix from FCU-12.ZoneTemp.
• JavaScript function -- write an arbitrary JS expression for cases where simple splits aren't sufficient.

If you leave the key extractor empty, each point is treated as its own group ("map mode") -- useful when you simply want to rename or promote an attribute that already exists on the point itself.

Copy attrs¶

Copy attrs define which attributes to take from the group and how to name them on the target points.

• Source attr -- the attribute name as it exists on the sibling point (selected from a dropdown populated by the workflow's matched points).
• Target attr -- the name the attribute will have on each enriched point. Defaults to the same name as the source if left blank.

At least one copy-attr pair is required to save the enrichment rule.

Reduce function (advanced)¶

When multiple points in a group all carry the source attribute, the reduce function decides how to merge them. By default the first non-empty value wins -- fine for the common case where only one point per group has the data.

For more control, expand Reduce function and write a JavaScript function with this signature:

(attrs, prev) => {
  // attrs: source attributes from the current group member
  // prev:  accumulated result from previous members (starts as {})
  // return the updated accumulated object
  if (attrs.description) prev.description = attrs.description;
  return prev;
}

The function is called once per group member in arbitrary order, and its final return value is what gets copied onto each point in the group.

Where enriched attributes appear¶

Attributes added by sibling enrichment are written to the point as pending changes, just like any other workflow output. They appear in the Preview panel alongside equipment ID and point class changes, and are committed to the model layer when you click Apply.

If a point already has the target attribute, the existing value is replaced by the enriched value -- the old and new values are shown in the diff view so you can verify the result before applying.

Managing Workflows¶

The Workflows page lists all workflows with their current state and pending change counts. From here you can:

• Search workflows by name.
• Edit a workflow to modify its rules.
• Preview pending changes and selectively apply them.
• Delete a workflow. Deleting a workflow removes its configuration but does not undo changes that have already been applied.