Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Collapse]eXpressApp Framework
 [Expand]Fundamentals
 [Expand]Getting Started
 [Collapse]Concepts
  [Expand]Application Solution Components
  [Expand]Business Model Design
  [Expand]Application Model
  [Expand]UI Construction
  [Expand]Extend Functionality
  [Expand]Data Manipulation and Business Logic
  [Expand]Security System
  [Expand]Localization
  [Expand]System Module
  [Collapse]Extra Modules
   [Expand]Audit Trail Module Overview
    Business Class Library Customization Module
    Chart Module
    Clone Object Module
   [Expand]Conditional Appearance Module Overview
   [Expand]Dashboards Module
    File Attachments Module Overview
    HTML Property Editor Module
   [Expand]Notifications Module
    KPI Module
   [Expand]Maps Module
   [Expand]Pivot Chart Module
    Pivot Grid Module
   [Expand]Reports V2 Module
   [Expand]Reports Module (Obsolete)
   [Expand]Scheduler Module
    Script Recorder Module
   [Expand]State Machine Module
   [Expand]TreeList Editors Module
   [Expand]Validation Module
    View Variants Module
   [Expand]Workflow Module
  [Expand]Debugging and Error Handling
  [Expand]Filtering
  [Expand]Application Life Cycle
 [Expand]Design-Time Features
 [Expand]Functional Testing
 [Expand]Deployment
 [Expand]Task-Based Help
 [Expand]Frequently Asked Questions
 [Expand]API Reference
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

KPI Module

Key Performance Indicators (KPI) are quantitative measurements of dynamic business processes. For instance, an important performance indicator for a trading company might be daily sales, and for a team of developers it might be the number of active bugs in their product. For better visualization, KPI value ranges can be split into a "green zone" (everything is OK), a "yellow zone" (warning), and a "red zone" (things are problematic). When KPI are based on a time range, it can be useful to compare the values of different periods (for instance, the current month versus the previous month). If a deeper analysis (drilldown) is required, then the objects from which an indicator was calculated can be listed. This topic explains the basics of using the KPI module.

To add the KPI Module (which is platform-agnostic) to the module project, invoke the Module Designer and drag the KpiModule item from the Toolbox to the Required Modules panel. Remember to rebuild your solution after making changes in the Designer.

Note

When using the KpiModule in a WinForms application, you must also add the ChartWindowsFormsModule to the application using the Application Designer. When using the KpiModule in an ASP.NET application, you must add the ChartAspNetModule to the application using the Application Designer.

If you use Entity Framework Code First, perform the following steps to properly register KPI entities in existing project (these steps are not required if you use XPO or if you create a new project in the Solution Wizard).

  1. Add the following code to the constructor of your platform-agnostic module.
  2. Ensure that the DevExpress.Persistent.BaseImpl.EF.v17.1.dll assembly is referenced and then add KPI Entities from the Business Class Library to the ModuleBase.AdditionalExportedTypes list in the module's constructor.
  3. Register these entities (except for the abstract BaseKpiObject) in your DbContext.
Note

Avoid the simultaneous use of DevExpress.Persistent.BaseImpl.EF.Kpi and DevExpress.ExpressApp.Kpi namespaces in the using directives of your code. Otherwise, a class name conflict will occur. Use fully qualified type names instead.

When the KPI module is used in an XAF application, the KPI navigation group with the Definition and Scorecard navigation items is available.

In the Definition tab, a new KPI definition represented by the KpiDefinition persistent object can be created.

The KpiDefinition object properties are described in the table below.

Property Description
Name KPI name.
TargetObjectType

The type of business object the KPI is designed for.

Criteria

Specifies the Criteria Language expression that is used to calculate each measurement item based on the MeasurementFrequency property. The CurrentValue of the entire KPI instance represents the last measurement value.

In the expression, you can use the ?RangeStart and ?RangeEnd parameters that internally get replaced with the actual date range start and end values calculated from the Range property.

You can see the example in the KPI section of the Feature Center demo, which is shipped with XAF. By default, the Feature Center demo is installed in %PUBLIC%\Documents\DevExpress Demos 17.1\Components\eXpressApp Framework\FeatureCenter. The ASP.NET version of this demo is available online at http://demos.devexpress.com/XAF/FeatureCenter/.

Direction

The Direction { LowIsBetter, HighIsBetter } enumeration value specifies how to treat deviation from a previous measurement result.

Expression

An expression that is used to evaluate KPI - Sum, Count, Avg, etc. In WinForms applications, you can use the PopupExpressionPropertyEditor Property Editor to simplify the creation of an expression of any complexity with the help of the Expression Editor dialog. To achieve this, invoke the Model Editor and set the PropertyEditor property of the BOModel | KpiDefinition | OwnMembers | Expression node to DevExpress.ExpresssApp.Win.Editors.PopupExpressionPropertyEditor.

You can use ?RangeStart and ?RangeEnd parameters to create free joins:

Expression = "Iif(Count() = 0, 0, Count() * 100 / [<Order>][[Order Date] >= '?RangeStart' And [Order Date] <= '?RangeEnd'].Count())"

The expression above evaluates the percentage ratio of the Orders amount in the RangeStart/RangeEnd period and the total amount of orders.

Range

The period to analyze.

Compare

The Boolean flag that indicates if current KPI values should be compared to previous values calculated using the RangeToCompare period.

RangeToCompare

The past period to be compared with the Range.

MeasurementFrequency

The Range is split into intervals, and the MeasurementFrequency specifies the size of each interval. For each interval, a KPI value is calculated.

GreenZone, RedZone

Specify the KPI value’s "green" and "red" ranges, which can be used for visualization. You can define Conditional Appearance rules that take these values into account.

SuppressedSeries

Specifies the range whose sparkline is suppressed in the Dashboard. The SuppressedSeries editor is invisible by default. More details on this property are provided below.

In a Preview tab, the current KPI value and the collection of objects used to calculate KPI are available.

Note

Do not set the IModelListView.DataAccessMode option to Server for the nested List View displayed in the Preview tab - the KPI Module does not support this. The Objects collection displayed in this List View is not associated with the KpiDefinition object. It is created and filtered by the Objects property getter. A Criteria applied to this collection will be ignored in Server mode.

To view and analyze the collection of KPI, the Scorecard object can be used. Scorecard is an object that has linked KPI. Under the Scorecard navigation item, Scorecards with linked KPI can be created.

The changes for the current period are visualized in the Sparkline column by default. To display current and previous periods, set the KpiDefinition object's Suppressed Series property to an empty string (its value is "Previous" by default). This property is invisible in the KPIDefinition object's Detail View layout by default. To allow end-users to change the Suppressed Series value at run-time, modify the Detail View layout to make the Supressed Series editor visible (see Add an Editor to a Detail View and Customize the View Items Layout for details). The image below illustrates the Sparkline column, displaying both previous and current value changes.

A drill-down list view can be invoked by double-clicking the KPI. The result is a list of objects that were used to calculate the KPI. This list view can be analyzed by grouping and sorting data.

To visualize KPI on the scorecard or dashboard, the KpiInstance objects are used. The KpiInstance is separated from the KpiDefinition. The KpiInstance object holds and manages KPI measurement history, retrieves Current and Previous values from the KPI history cache, creates a data source for sparkline and chart editors, and is responsible for cleaning outdated values from the cache. A KpiInstance object is created by a KpiDefinition object in its AfterConstruction method. The ShowChart Action provides the capability to view KPI results as a chart.

The chart is customizable in the Chart Designer, and can be printed just like charts created with the Pivot Chart Module.

Note

To see how the KPI values are calculated internally, check the actual SQL queries using one of the following approaches:

Although only the WinForms application screenshots were illustrated, the same functionality is available in an ASP.NET application.

An example of KPI module usage is provided in the Feature Center demo that ships with XAF. This demo is located in the %PUBLIC%\Documents\DevExpress Demos 17.1\Components\eXpressApp Framework\FeatureCenter folder by default.

How would you rate this topic?​​​​​​​