GenKPI Class

Generic KPI objects are created in the KPI model to represent a KPI data producing item. Most commonly they are linked to a data producing item in the I/O Model tree through the Process Value property. If using enterprise:inmation, Generic KPI objects and values will be reflected on a Visual KPI web display or dashboard. A value range and various limits can be configured for the object and email notifications can be set up to alert when values exceed the defined limits.

Use Cases

  • To display raw or calculated data from your system namespace on a Visual KPI web dashboard.

  • Receive email notifications when a KPI value exceeds a predefined limit.

Quick Configuration

  1. Select an object in the KPI Model and right-click. Select Admin  New  KPI Data  Generic KPI from the context menu.

    Generic KPIs can be created under most KPI Model objects but cannot be the top level object in the KPI model panel.
  2. In the Create Generic KPI Wizard, give a name to the object.

  3. In the Process Value property, click + and use the object picker to choose the object from the I/O Model that will generate the data that the GenKPI will be representing in the KPI Model. Click Create to create the object in the KPI Model.

  4. Select the object in the KPI model and in the Object Properties panel, find the KPI range and limits property compound and set appropriate range and limit values for the KPI and click Apply.

  5. If using Visual KPI, open a web browser and navigate to the Visual KPI site to find the KPI and see the current value.

For more information regarding the KPI Model Panel, please visit:
- KPI Model

For more information about installation and configuration of Visual KPI, please visit:
- Installing Visual KPI Jump Start

To learn how to do custom data transformations on GenKPI values for display on Visual KPI please visit:
- Data Transformation hands on

Object Properties

Common

Object Name

The user-modifiable object name. This name overrides the name which has been supplied by the external system. It must be unique within the collection of objects of the parent object.

Object Description

This is the user-modifiable object description. This name overrides the description which has been supplied by the external system.

Display Order

Numeric value that overrides the default alphanumeric order of KPIs. KPIs without explicit display order will be sorted alphanumerically and displayed below KPIs with display order values explicitly set.

In Service

Show this KPI as 'in service' in the VisualKPI web displays.

Show

Hide/show KPI. A setting of False will suppress the display of the object to the users in the VisualKPI web display.

Status History Type

Definition determing how to calculate status history.

  • Cache: Only VisualKPI cache.

  • Cache and Raw History: VisualKPI cache and raw history from source.

Status Backfill

The maximum number of days per status history backfill cycle that data will be populated (use a smaller number for fast moving data).

Stale Age

The maximum age in minutes of a KPIs Actual value. When Current Time is greater than (Last Actual value update time plus KPI Stale Age), then KPI status is set to Stale. A value 0 will ignore Staleness for this KPI.

Calculation Type

Override for how non-numeric values in calculations are handled. This is useful when dealing with exception data (i.e., BadValue) returned from calculation-derived data sources.

  • Default: Default.

  • Standard: Standard.

  • Force Numeric: Force Numeric.

Process Value

Dynamic property link.

Aggregate Selection

The default aggregate to be used for the web displays.

  • Invalid: Invalid.

  • Interpolative: This aggregate returns the interpolated bounding value for the StartTime of each interval.

  • Average: This aggregate adds up and the values of all good raw data for each interval and divides the sum by the number of good values and returms this average and the starttime of the interval.

  • Time Average: This aggregate calculates the area under a sloped line which connects the interpolative start value, all good raw values and the interpolated bounding value at the and end and divides this area by the length of the processing interval. It returns the time weighted average and the starttime of the interval.

  • Time Average 2: This aggregate calculates the area under a sloped or stepped line (depending on the aggregate option 'use_sloped_extrapolation') which connects the simple bounding start value, all good raw values and the simple bounding value at the end and divides this area by the length of the processing interval. It returns this average and the starttime of the interval.

  • Total: This aggregate is the result of the TimeAverage calculation multiplied by the processing interval in seconds. It returns this total value and the starttime of the interval.

  • Total 2: This aggregate is the result of the TimeAverage2 calculation multiplied by the processing interval of good data in seconds. It returns this total and the starttime of the interval.

  • Minimum: This aggregate finds the minimum value of all good raw values and returns this value with the starttime of the interval. If multiple extremevalues exist the status 'multiple values' is set.

  • Maximum: This aggregate finds the maximum value of all good raw values and returns this value with the starttime of the interval. If multiple extremevalues exist the status 'multiple values' is set.

  • Minimum Actual Time: This aggregate detects the minimum value of all good raw values and returns this value with the timestamp at which that value occurs. If multiple extremevalues exist the oldest one is retrieved and the status 'multiple values' is set.

  • Maximum Actual Time: This aggregate detects the maximum value of all good raw values and returns this value with the timestamp at which that value occurs. If multiple extremevalues exist the oldest one is retrieved and the status 'multiple values' is set.

  • Range: This aggregate calculates the difference between the maximum and the minimum of all good raw values and returns the starttime of the interval. If only one good value exists the range is zero, otherwise it is always positive.

  • Minimum 2: This aggregate includes the simple bounding values to identify the extremevalue and returns this value with the starttime of the interval. If multiple extremevalues exist the status 'multiple values' is set.

  • Maximum 2: This aggregate includes the simple bounding values to identify the extremevalue and returns this value with the starttime of the interval. If multiple extremevalues exist the status 'multiple values' is set.

  • Minimum Actual Time 2: This aggregate includes the simple bounding values to identify the extremevalue and returns this value with the timestamp at which that value occurs. If multiple extremevalues exist the oldest one is retrieved and the status 'multiple values' is set.

  • Maximum Actual Time 2: This aggregate includes the simple bounding values to identify the extremevalue and returns this value with the timestamp at which that value occurs. If multiple extremevalues exist the oldest one is retrieved and the status 'multiple values' is set.

  • Range 2: This aggregate returns the difference between the Maximum2 and the Minimum2 aggregates. If only one good value exists the range is zero, otherwise it is always positive.

  • Count: This aggregate retrieves the count of good raw values.

  • Duration In State Zero: This aggregate returns the time in milliseconds during the good raw values (including the simple bounding values) in the interval are in zero state.

  • Duration In State Non Zero: This aggregate returns the time in milliseconds during the good raw values (including the simple bounding values) in the interval are not in zero state.

  • Number Of Transitions: This aggregate returns the number of good raw value transitions during the interval. The earliest transition must be calculated by comparing the earliest non-bad value in the interval to the previous non-bad value. A transition occurred if no previous non-bad value exists or if the earliest non-bad value is different. The endtime is not included.

  • Start: This aggregate retrieves the earliest raw value within the interval amd returns that value and status with the timestamp at which that value occurs.

  • End: This aggregate retrieves the latest raw value within the interval amd returns that value and status with the timestamp at which that value occurs.

  • Delta: This aggregate retrieves the difference between the earliest and latest good raw values in the interval.

  • Start Bound: This aggregate returns the value and status at the starttime for the interval by calculating the simple bounding value for the interval.

  • End Bound: This aggregate returns the value and status at the endtime for the interval by calculating the simple bounding value for the interval. The timestamp returned is the starttime.

  • Delta Bounds: This aggregate returns the differnece between a good startbound and a good endbound aggregate.

  • Duration Good: This aggregate divides the interval into regions of good and non-good data. Each region starts with a data point in the interval. If that data point is good the region is good. The returned value is the sum of the duration of all good regions expressed in milliseconds. The status of the first region is determined by finding the first data point at or before the start of the interval. If no value exists the first region is bad. The timestamp returned is the starttime.

  • Duration Bad: This aggregate divides the interval into regions of bad and non-bad data. Each region starts with a data point in the interval. If that data point is bad the region is bad. The returned value is the sum of the duration of all bad regions expressed in milliseconds. The status of the first region is determined by finding the first data point at or before the start of the interval. If no value exists the first region is bad. The timestamp returned is the starttime.

  • Percent Good: This aggregate calculates the DurationGood divided by the interval multiplied by 100. (DurationGood / Interval * 100).

  • Percent Bad: This aggregate calculates the DurationBad divided by the interval multiplied by 100. (DurationBad / Interval * 100).

  • Worst Quality: This aggregate returns the worst status of the raw values in the interval. If multiple extremevalues exist the status 'multiple values' is set. The timestamp returned is the starttime.

  • Worst Quality 2: This aggregate returns the worst status of the raw values in the interval including the simple start bound value. If multiple extremevalues exist the status 'multiple values' is set. The timestamp returned is the starttime.

  • Annotation Count: This aggregate returns the number of all annotations in the interval.

  • Standard Deviation Sample: This aggregate calculates the 'standard deviation sample' of the good raw values in the interval. If there is only 1 good raw value 0 is returned. The timestamp returned is the starttime.

  • Variance Sample: This aggregate retrieves the square of the standard deviation sample.

  • Standard Deviation Population: This aggregate calculates the 'standard deviation population' of the good raw values in the interval. If there is only 1 good raw value 0 is returned. The timestamp returned is the starttime.

  • Variance Population: This aggregate retrieves the square of the standard deviation population.

  • Interpolative End: This aggregate returns the interpolated bounding value for the EndTime of each interval.

  • Sample: The Sample aggregate is a combination of the aggregates Maximum / Minimum Actual Time. It is not part of the OPC UA Specification, and optimized for drawing trends.

  • Best Fit: The Bestfit aggregate is a combination of the aggregates Maximum / Minimum Actual Time / Interpolative. If both Max and Min aggregate for an interval returns NoData the interpolative value is used (Non-Stepped trendtype), or the last known good value (Stepped trendtype). It is not part of the OPC UA Specification, and optimized for drawing trends.

  • Raw data: Receive raw data - as stored in the historian database.

Offset

The relative time offset used to retrieve values for this KPI. This allows for KPIs to show values at different times, such as Profit Today, Profit Yesterday, and Profit Last Week. This value uses our standard offset format (e.g., *-1day).

Status

Override of status. Usually determined by actual and limit values.

  • High High High: High High High.

  • High High: High High.

  • High: High.

  • Good: Good.

  • Low: Low.

  • Low Low: Low Low.

  • Low Low Low: Low Low Low.

  • Unknown: Unknown.

  • N/A: N/A.

  • Customstatus1: Customstatus1.

  • Customstatus2: Customstatus2.

  • Customstatus3: Customstatus3.

  • Customstatus4: Customstatus4.

  • Customstatus5: Customstatus5.

  • Customstatus6: Customstatus6.

  • Customstatus7: Customstatus7.

  • Customstatus8: Customstatus8.

  • Customstatus9: Customstatus9.

  • Customstatus10: Customstatus10.

Top Text

The value displayed on the top line of a KPI Block in a Group Map or a KPI Map. If blank, then the default setting of KPI name will be used.

Bottom Text

The value displayed on the bottom line of a KPI Block in a Group Map or a KPI Map — if blank, then the default setting of Actual will be used.

Additional Text

Additional Text.

Links

List of associated links or URLs (semicolon separated, limit 10) for the object.

Link Descriptions

List of associated Link or URL descriptions (semicolon separated, limit 10) for the object. These are used to both shorten and give better meaning to links (e.g., instead of www.xyz.com?x=5&type=2, the user could see SOPs or Shift Report).

Name clickpath

Controls what happens when a user clicks the name of a KPI. The user will either be shown the trend of the KPI (default) or the user will be taken to the first link defined for the KPI (if one exists).

  • Trend: Trend.

  • Url: Url.

Access Group List

List of Active Directory or local groups (semicolon separated) defining access rights to the object. Only applies if object level security is enabled and the site is secured.

Bullet Chart Type

Controls the display type for Bullet Charts. Deviation types require a KPI Target.

  • Actual EU: Actual EU.

  • Deviation EU: Deviation EU.

  • Deviation %: Deviation %.

Group Map Position

The numerical location (left to right, top to bottom) of the KPI in a Group Map. If this is blank, then the KPI will not be shown in the Group Map.

Sparkline Refresh Interval

Update period for the sparkline in seconds. Leave blank for the default value.

KPI ID

The KPI ID which gets assigned by VisualKPI.

VisualKPI Object

The corresponding Visual KPI object class.

Translations

Table for translations of property values to various languages.

KPI Range and Limits

This property compound lets you define the range, the target and the limits for this KPI definition.

Range Max

Highest valid value for the KPI. Values above this value will result in an unknown status.

Range Max Path

Highest valid value for the KPI (dynamic). Values above this value will result in an unknown status.

High High High Limit

Limit value for the KPI which is used in KPI status calculations.

High High High Limit Path

Dynamic limit value for the KPI which is used in KPI status calculations.

High High Limit

Limit value for the KPI which is used in KPI status calculations.

High High Limit Path

Dynamic limit value for the KPI which is used in KPI status calculations.

High Limit

Limit value for the KPI which is used in KPI status calculations.

High Limit Path

Dynamic limit value for the KPI which is used in KPI status calculations.

Target Value

The KPI’s desired target value.

Target Value Path

The KPI’s dynamic target value.

Low Limit

Limit value for the KPI which is used in KPI status calculations.

Low Limit Path

Dynamic limit value for the KPI which is used in KPI status calculations.

Low Low Limit

Limit value for the KPI which is used in KPI status calculations.

Low Low Limit Path

Dynamic limit value for the KPI which is used in KPI status calculations.

Low Low Low Limit

Limit value for the KPI which is used in KPI status calculations.

Low Low Low Limit Path

Dynamic limit value for the KPI which is used in KPI status calculations.

Range Min

Lowest valid value for the KPI. Values below this value will result in an unknown status.

Range Min Path

Lowest valid value for the KPI (dynamic). Values below this value will result in an unknown status.

Display Format

Compound holding the specific display settings for the KPI visualization.

Numeric Format

Optional numeric formatting code (.NET) used to modify how numbers are displayed in VKPI.

Display Format

Select if and how the displays shall visually arrange the value and its engineering unit.

  • Number only: For actual value visualization, only the number part will be used.

  • Number, followed by Engineering Unit: For actual value visualization, the number will be displayed followed by the engineering unit.

  • Engineering Unit, followed by Number: For actual value visualization, the number will be displayed following the engineering unit.

Geo Label Format

Overrides what is displayed for an object on a geo Map.

  • Default: Default.

  • Actual: Actual.

  • Name: Name.

  • Name: Actual: Name: Actual.

Data Transformation

Compound for user-defined scripts to overwrite the actual VisualKPI value.

ReadValue

User-defined script for reading the actual value.

ReadHistory

User-defined script for reading history values.

ReadHistoryAtTime

User-defined script for reading a single history value at a given time.

ISO22400-KPI Options

Compound that controls the ISO22400-KPI handling.

ISO22400-KPI

This enables specific KPI-handling according to ISO224400.

Lua Script Body

Script editor to enter an advanced Lua script.

SPC Type

Statistical process control (SPC) is a method of quality control which uses statistical methods. SPC is applied in order to monitor and control a process. Monitoring and controlling the process ensures that it operates at its full potential.

Location

The location of the object.

Strategy

Definition of the location strategy.

  • No location: This object is not interpreted in a location context.

  • Static (or manually changed) location: You may set the location data manually, by Engineering Script or by selecting the location visually using the Location Finder feature.

  • Inherited location: The object inherits the location from the owning object in the system hierarchy.

  • Dynamic location: The object location is supplied by other I/O Items. You may drop other I/O items into the location fields of this object.

  • Location properties: The endpoint server has distinct properties for I/O item location data. Please note, that this option works only for I/O items .

Name

The optional name of a location.

Latitude

The north-south position of a point on the Earth’s surface.

Longitude

The east-west position of a point on the Earth’s surface.

Altitude

The height above sea level of the location.

Track Location

Enables historization of Location data.

Notification Settings

This property compound lets you define the notification settings for this KPI definition.

Notification Type

The means of notification this KPI will use in case of alerts.

  • None (No Notifications): No Notifications will be sent out for this KPI.

  • E-Mail Notifications: KPI Notifictaions will be sent out by E-Mail.

Alert Silence

KPI alert silencing switch.

KPI Alert Silence Duration

The numerical override for the alert silence duration (overrides alert template setting). Only valid if the alert silence is True.

Primary Contact

Main contact for KPI notifications.

Secondary Contact 1

Alternate contact 1 for KPI notifications.

Secondary Contact 2

Alternate contact 2 for KPI notifications.

Alert template

The template that controls alert behavior for this KPI.

Time in State

The numerical override for the time in state (overrides alert template setting). This is the delay, in minutes, before status is used to determine if notifications are sent. This helps to prevent nuisance notifications for rapidly-changing KPIs.

Info Settings

Info settings.

Info

Additional relevant information (can be hyperlinked).

Info Description

If the Info field is a hyperlinked value, then this will be the tooltip or mouseover text for the link. If only a URL is used, then this will be the text displayed in Info.

Info Display Format

Info display format.

  • Number only: For actual value visualization, only the number part will be used.

  • Number, followed by Engineering Unit: For actual value visualization, the number will be displayed followed by the engineering unit.

  • Engineering Unit, followed by Number: For actual value visualization, the number will be displayed following the engineering unit.

Info Numeric Format

The numeric formatting code (.NET) used to modify how numbers are displayed.

Info Eng. Unit

Unit of measure for the info value (applicable if value is numeric).

Info URL

URL link for the Info field (creates a hyperlink in the Info field).

Trend Settings

Trend settings.

Actual Trend Type

The trend line type for the actual pen on a KPI trend.

  • Interpolated: Interpolated.

  • Step: Step.

  • Symbol: Symbol.

  • Interpolated + Symbol: Interpolated + Symbol.

  • Step + Symbol: Step + Symbol.

Target Trend Type

The trend line type for the target pen on a KPI trend.

  • Interpolated: Interpolated.

  • Step: Step.

  • Symbol: Symbol.

  • Interpolated + Symbol: Interpolated + Symbol.

  • Step + Symbol: Step + Symbol.

Limit Trend Type

Limit trend type.

  • Interpolated: Interpolated.

  • Step: Step.

  • Symbol: Symbol.

  • Interpolated + Symbol: Interpolated + Symbol.

  • Step + Symbol: Step + Symbol.

Trend Start

Overrides the default start time for the KPI trend (Note: The start time must be < the end time and the value can be an actual or relative date [e.g., 6/12/2015 or *-7Days]).

Trend End

Overrides the default end time for the KPI trend (Note: The end time must be > the start time and the value can be an actual or relative date [e.g., 6/12/2015 or *-7Days]).

Show Trend Target

The default setting to show or hide the target pen on a KPI trend. Users can still show the target pen by clicking on the legend.

Trend Limits

The default setting to show or hide the limit pens on a KPI trend. Users can still show pens by clicking in the legend.

Trend Y-Axis

The trend y-axis scale type for the KPI or trend.

  • Auto-Scale: Auto-Scale.

  • KPI Min and Max: KPI Min and Max.

  • Min and Max Y Axis: Min and Max Y Axis.

Trend scale

The trend scale type for the KPI or trend.

  • Single Scale: Single Scale.

  • Multi-Scale: Multi-Scale.

Min Y-Axis

Override for minimum of chart scale on the y-axis.

Max Y-Axis

Override for maximum of chart scale on the y-axis.

Show Average Trendline

A boolean value used to set visibility of a line depicting the average of the actual trend data within the trend timeframe.

Show Status Background

The default setting to show or hide status bar in the background of a KPI trend.

Lookup Text Length

The numerical override for the maximum length of lookup text displayed on chart cursors.

Show Calcs in Chart cursor

A boolean override that controls whether or not calculations (equations) are displayed in chart cursors.

Custom Options

Compound to hold various structures to customize the object and to be read and written to by Lua-Script code or external interfaces.

Custom String

A generic string buffer to be used programmatically for custom purposes.

Custom Properties

This is an extensible set of named strings which can be used programmatically for custom purposes.

Property Name

A custom property name which can be used programmatically.

Property Value

The value of the custom property which can be read and written programmatically.

Custom Tables

This is an extensible set of named tables which can be used programmatically for custom purposes.

Table Name

A custom table name which can be used programmatically.

Table Data

Handles an entire table organized in columns and rows. The data can easily (cut, copy and paste) be exchanged with table-oriented data of other software products, e.g. MS Excel.