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.

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.

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.