KPI Card+

Overview

When to use it

Use KPI Card+ when you need to:

• Put one important value, such as a temperature or a production rate, in large type.
• Show a summary of a period, such as the maximum or average, instead of the live value.
• Compare the value with a fixed target, the value an hour ago, or a recent average.
• Add a short history without a trend symbol.
• Color the card by limits, or show how far the value has moved through them.

Choose Value+ when operators need its floating trend more than a dashboard card.

Before you begin

• Use one PI Point or AF attribute per card. For several KPIs, add several cards.
• Use a numeric data source for summaries, targets, sparklines, and progress styles. Text, Boolean, enumeration, and timestamp values can be shown, but nothing is calculated from them.
• Make sure PI Web API can read the data source's history when you plan to use a summary, a calculated target, or a sparkline.

Add and set up the symbol

1. Select KPI Card+ in the PI Vision symbol gallery.
2. Drag one PI Point or AF attribute onto the display. The card shows the current value, its unit, and its label.
3. Right-click the card and select Configure KPI Card+....
4. Under Value, keep Source set to Current.
5. Under Sparkline, set Enabled to ON.
6. Close the configuration pane. The card shows a line of recent history behind the value.

Common tasks

Show a value with a sparkline

Use this when readers need to see whether a value is rising or falling, without opening a trend.

1. Right-click the card and select Configure KPI Card+....
2. Under Sparkline, set Enabled to ON (1).
3. Select Line or Bars for Type (2).
4. Select Overlay to draw the sparkline behind the text, or Bottom to reserve its own strip (3).
5. Under Start- and Endtimes (4), select Duration and offset, and enter a Duration (5), for example 4 hours.

The card draws the history of the chosen period and prints its length, such as 4h, in the lower-left corner. A dot marks the latest point of the line.

Compare the value with a target

Use this when readers need to know how far the value is from a goal.

1. Under Target, set Enabled to ON (1).
2. Set Show to ON (2) to print the target value after the comparison.
3. Select Fixed for Source (3).
4. Enter the target in Value (4), for example 50.
5. Select Value or Percent for Difference (5).
6. Select Higher is better or Lower is better for Direction (6).

A badge under the label shows the difference from the target, for example -38.0% vs. Target · 50 °C. The arrow shows whether the value is above or below the target. The badge turns green when that direction is favorable and red when it is not.

To compare with the value at an earlier time or with a recent average, select Calculated for Source and see Target. To treat small deviations as on target, use the Tolerance settings in the same group.

Color the card by limits

Use this when the whole card must show whether the value is normal, high, or low.

1. Right-click the card and select Add Multi-State.... When the card already has one, the command reads Configure Multi-State....
2. Under Property, select a style (1), for example Soft Fill.
3. Read the states list (2). If the data source has limits in AF, they appear here with their colors.
4. For a data source without limits, type a limit value in the box under States and select Add. The second image shows the box (1), Add (2), and the list of existing limits (3).

The card takes the color of the state that holds the current value. Progress, Progress and Value, Fill Level, and Radial Progress place the value between the lowest and highest limit instead of coloring the card. These examples show Soft Fill, Solid Fill, Border, Progress, Fill Level, and Radial Progress:

Show a summary instead of the live value

Use this when the KPI is a result for a period, such as the highest temperature of a shift.

1. Under Value, select Calculated for Source (1).
2. Select a Summary Type (2), for example Maximum.
3. Select the Basis (3): Time Weighted counts how long each value lasted, Event Weighted counts every recorded event once.
4. Under Start- and Endtimes (4), select Duration and offset, and enter a Duration (5), for example 8 hours.
5. Under Content, enter a Label that names the period, for example Max temperature, last 8 h.

The card shows the maximum of the last eight hours before the display end time. Nothing on the card says that the value is a summary, so name the period in the label.

Show the value in another unit

Use this when readers expect a different unit than the one stored in AF, such as degrees Fahrenheit instead of Celsius.

1. Under Value, open Display unit (1).
2. Select a unit from the list, for example degree Fahrenheit (°F).

The value, its unit, the sparkline, and the target comparison switch to the new unit. The list offers units of the same kind as the attribute. Default follows the unit set in AF. If a converted value loses detail, choose more decimals under Format (2).

Important: A Fixed target, an Absolute tolerance, and typed multi-state limits are read in the displayed unit and are not converted. Enter them again after you change Display unit.

Change what the card shows and how it looks

Use this to make cards match your display or to fit a small space.

1. Under Style, select a Theme tile (1).
2. Select Flat or Gradient for Surface (2).
3. Select a Container Style tile (3).
4. Select a size for the Value under Font Size (4).
5. Select Left, Center, or Right for Alignment (5).

The card changes immediately. To hide the unit, label, or value, or to add a timestamp, use the Content settings under Value.

Use the symbol

• Arrow and color: An up arrow means the value is above the benchmark and a down arrow means below. Green means the direction is favorable, red unfavorable. A value inside the tolerance has no arrow and a neutral color.
• Display time: A Current value shows the value at the display end time, so it follows playback and historical display times. Summaries and sparklines follow the range they are set to.
• Limit colors: A multi-state style colors or fills the whole card. A small dot in the corner marks the Status Dot style.
• No Data: The card shows the PI state, for example No Data, with a gray dot. Hover over a dot to read its meaning.
• Bad, questionable, or substituted values: A small colored dot appears in the corner. Hover over it for the reason.
• Stale: When Stale warning is on and a live value is older than the threshold, an amber indicator appears. The threshold is 2 hours by default.
• Hide No Data: The card content is hidden. In edit mode, a dashed box labeled Hidden: No Data keeps the card selectable.
• Links: When you add a navigation link with Add Navigation Link..., select the card to follow it.
• The symbol only displays data. It does not write to the PI System or change other symbols.

Configure the symbol

Right-click the card and select Configure KPI Card+.... The groups are Value, Style, Sparkline, Target, and Data Quality. Web API, License Status, Help, and About are shared by all Vision Library+ symbols. Limit colors are set in the multi-state pane (see Multi-state pane).

Value

A total over time is not converted by Display unit. It stays in the attribute's own unit and is labeled with it. Count and Percent Good are not converted either. Range and standard deviations change by the unit's scale only.

Style

Used in Change what the card shows and how it looks.

Sparkline

Used in Show a value with a sparkline. A sparkline needs numeric history. When it is unavailable, only the sparkline is hidden and the value stays.

Target

Used in Compare the value with a target.

Data Quality

See Data Quality for the shared rules and the administrator override.

Multi-state pane

Right-click the card and select Add Multi-State... or Configure Multi-State.... This is the PI Vision multi-state pane. Used in Color the card by limits.

Troubleshooting and limitations

Limitation: KPI Card+ supports one data source and one target per card.

Limitation: Target ranges and bands are shown through multi-state limits, not through a separate target-range setting.