Event Analytics KPI

Overview

Event Analytics KPI summarizes an event-frame search as one or more key performance indicators.

When to use it

Use this symbol when you need to:

• Show an event count, duration, total, average, or other aggregate as a KPI.
• Compare the same event measure across series.

Before you begin

• Prepare an event-frame template and search that returns the intended events.
• Choose a numeric field for aggregations other than event count.

Add and set up the symbol

1. Select the symbol in the PI Vision symbol gallery.
2. Add the required data sources or asset context to the display.
3. Right-click the symbol and open its configuration pane.
4. Configure the minimum data, range, and display settings for a useful result.
5. Confirm that the symbol shows the expected data.

Use the symbol

Review the KPI value and use any enabled click or hover action for additional context.

Configure the symbol

Overview and behavior

The Event Analytics KPI symbol provides a high-level summary of event frame data as aggregated metrics displayed in a responsive grid of cards. Rather than listing individual event rows, it calculates KPIs - totals, averages, counts - and presents them at a glance.

Typical uses:

• Total Duration of all downtime events this week.
• Count of high-severity safety incidents.
• Average Duration of events grouped by Asset or Root Cause, displayed side-by-side.

Use it as a dashboard entry point - a quick read of critical metrics before drilling into charts or tables.

The core concept: values and series

KPI cards are generated from a combination of Values (the calculation) and Series (the grouping).

• Value only (no Series): A single card showing the aggregated total across all search results (e.g., Total Downtime).
• Value + Series: The symbol generates one card per unique category in the Series.
• Example: If your Value is Count, and your Series is [Asset](vscode-file://vscode-app/c:/Program%20Files/Microsoft%20VS%20Code/resources/app/out/vs/code/electron-browser/workbench/workbench.html), you will get a card for "Pump 1 - Count", "Pump 2 - Count", etc.
• Multiple Values: The card count multiplies. Configuring Count and Sum grouped by Asset (Pump 1, Pump 2) produces 4 cards total.

Configuration

1. Values (The Metrics)

Values define the metrics to calculate. Multiple values can be added to the same symbol.

• Name: The Event Frame property or Referenced Element Attribute (e.g., [Duration](vscode-file://vscode-app/c:/Program%20Files/Microsoft%20VS%20Code/resources/app/out/vs/code/electron-browser/workbench/workbench.html), [Severity](vscode-file://vscode-app/c:/Program%20Files/Microsoft%20VS%20Code/resources/app/out/vs/code/electron-browser/workbench/workbench.html), |Temperature) to analyze.
• Summary Type: The calculation method to apply to the numerical data. Options typically include Count, Sum, Average, Minimum, Maximum, CountDistinct, etc. (Note: Time-based properties like Duration will automatically format as readable timespans).
• Caption: By default the card title is the property name plus summary type (e.g., Duration (Average)). Override it with a friendly name such as Average Downtime.

2. Series (The Grouping)

Series slice Values by different categories.

• Name: The property to group by (e.g., Reason, [Asset](vscode-file://vscode-app/c:/Program%20Files/Microsoft%20VS%20Code/resources/app/out/vs/code/electron-browser/workbench/workbench.html), Shift).
• Top / Bottom N: Restrict the view to the most relevant categories when there are many.
• Mode & Count: Set the direction (Top or Bottom) and how many items to show (e.g., Top 3, Bottom 5).
• Value Index: The Value used to rank categories (e.g., Top 5 Assets ranked by Total Duration).
• Show Others: Aggregates remaining categories into a single Others card to preserve the grand total.
• Sort: Arrange cards in Ascending or Descending order based on a selected Value.

Interactive features

Master Filter

When Master Filter is enabled, the KPI symbol acts as a dashboard controller. Clicking a card (e.g., Motor Failure) broadcasts that category to all other Event Analytics symbols on the display - Charts, Pies, Gantts, Pivot Tables - instantly filtering their data to match.

• Highlight: The selected card highlights to indicate the active filter. Click again to clear.
• Ignore External: When enabled, the KPI symbol ignores filters from other symbols, keeping its totals static.

Drilldown

Drilldown changes how multiple Series behave. Without drilldown, adding two Series (e.g., Asset and Reason) creates a card for every combination (e.g., Pump 1 - Motor, Pump 1 - Seal).

If Drilldown is enabled:

1. The symbol initially only shows cards for the first Series (e.g., purely Assets: "Pump 1", "Pump 2").
2. Clicking the Pump 1 card navigates deeper. The cards animate to show the second Series filtered for Pump 1 (e.g., Motor Failure, Seal Leak).
3. A Drill Up (⇧) button appears in the top-right corner to navigate back up the hierarchy.

Layout and styling

Layout Options

The Layout section controls how cards wrap and fill the symbol's bounding box.

• Auto: The symbol automatically determines the optimal row and column count based on its height and width.
• Fixed Rows / Fixed Columns: Forces the grid to a strict row or column count (set by Line Count), wrapping items as needed.
• Spacing: Controls the pixel gap between individual cards.

Card Style

Sets the base appearance for all cards:

• Colors: Set the default Text Color, Background Color, and Border Color.
• Typography: Set the Font Family, configure Font Size independently for the Value and the Title, and choose Text Alignment (Left, Center, Right).
• Border Radius: Add rounded corners to the cards.

Conditional formatting (Multi-state)

KPI cards can change color dynamically based on their calculated value. Right-click the symbol and choose Configure multi-state to set this up. multi-state is configured per Value - select the correct Value from the dropdown in the configuration pane.

1. Enable: Turn on conditional formatting for the selected Value.
2. Limits: Add thresholds using <=. For example: Value ≤ 50 → Green; Value ≤ 100 → Yellow.
3. Property: This defines how the color is applied to the card:

• Text: Only the numerical value changes color.
• Fill: The entire card background changes to the multi-state color. The symbol automatically selects a high-contrast text color (black or white) to keep the text readable.
• Border: Adds a thick, colored accent border to the left side of the card, leaving the standard background alone.

Troubleshooting and limitations

• Check: If a KPI is blank, validate the event search, value field, aggregation, and time range.
• Check: The KPI reflects only events returned by its configured search.