KPI Wizard - Definition

In the "Definition" panel you can:

  • specify KPI definitions.

  • enter new parameters for the KPI definition

  • enter a calculation formula for the KPI calculation

The different parts of the Definition panel as well as how to use the Definition panel are described in more detail in the following.

Figure 1. Definition Panel

The panel consists of the following parts: KPI Definition, KPI Parameter Definition and KPI Calculation Formula

KPI Definition

KPI Definition allows you to specify a KPI definition, delete a KPI definition and create calculation formulas.

Create/Delete a KPI Definition

Via entering a KPI definition and clicking the plus sign in the bottom bar of the panel, you can create a KPI definition. You can also press Enter after typing a name in order to create a KPI:

The name of the KPI definition must correspond to the WinCC OA DP name guidelines! See chapter Rename Data points for information on the name guidelines.

To delete a KPI definition, select the KPI definition and click on the X button in the bottom bar of the panel. Confirm the dialog with "Yes".

Figure 2. Delete a KPI Definition

If KPI instances exist for a KPI definition, the KPI definition cannot be deleted! Only definitions for which there are no KPI instances available, can be deleted!

KPI Parameter Definition

Enter new parameter

KPI Parameter Definition allows you to specify new parameters for the function formula. Enter the parameters into the "Enter new parameter" text field and press Enter.

Figure 3. Enter new Parameter

The parameters are added to the table below:

Figure 4. Created Parameters

All special characters except for underline are forbidden. If you enter forbidden characters, an error message is shown:

Figure 5. Forbidden characters

KPI Calculation Formula

Create a formula or use a predefined function from the wincc_oa_path/SmartSCADA_3.19/scripts/libs/SmartSCADA/kpi/kpiFunctions.ctl library. To create a formula, drag a parameter from the table to the Formula table or type the parameter name into the formula table. Use the buttons with the functions (see figure below) to create a formula or type the mathematical operation into the formula table.

Figure 6. Drag and Drop a parameter to the calculation

You can check whether your formula contains errors by clicking on the "Check syntax" button. If the formula is error free, a message is shown:

Figure 7. Syntax Check - correct syntax

Predefined formulas

  • ssc_kpi_histSum: Calculates a historical sum. The formula can be used for a KPI. By using the formula, you can use a time value in a function. This time value is dynamic. You can, for example, calculate a sum for the duration of 5 minutes in the past (history) every 5 seconds. For how to use the function, see chapter KPI Wizard - Associate.

  • ssc_predictCondition: calculates the state of the WinCC OA system on the basis of a trained random forest model and the current data point values. Clusters specify which states are assigned to which data point values in a WinCC OA system. In the KPI wizard the current values are assigned to these clusters. The ssc_predictCondition function calculates and displays the state of the system. See chapter Discrete Values for an example of the ssc_predictCondition function.

User-specific formulas

You can create user-specific formulas in the wincc_oa_path/SmartSCADA_3.19/scripts/libs/SmartSCADA/kpi/kpiFunctions.ctl library.

  • Implement a function in the wincc_oa_path/SmartSCADA_3.19/scripts/libs/SmartSCADA/kpi/kpiFunctions.ctl library.

    If you create own functions in the wincc_oa_path/SmartSCADA_3.19/scripts/libs/SmartSCADA/kpi/kpiFunctions.ctl library, note that if the result of your function is incorrect, the function must return the function ssc_getNaN(). Thus, an incorrect KPI instance is deactivated. See example below:

if(!dpExists(dpe) || startTime < 0)
{
  throwError(makeError("ssc_errors", PRIO_SEVERE, ERR_PARAM, 32));
  value = ssc_getNaN();
}
else
{
  dpGetPeriod(start, end, 0, dpe, values, valueTimes);
  value = dynSum(values);
}
return value;
}
  • Add the function (formula) to the formula table by editing the data point _SSC_KPI_Configuration:

Figure 8. Add a new formula
  • The function is then shown in the KPI Calculation Formula table in the Definition panel.

Figure 9. New formula in the formula table

Buttons

The button "Save", "Reset" and "Close" are available in all panels of the KPI wizard.

Save

Saves the current settings of a panel.

Reset

Resets a value to the current original value or resets a setting to the current original setting. In order to reset a value to the original value, answer the question "Do you want to save the changes" with "No".

Close

Closes the wizard.