Concept and required steps to configure and calculate KPIs

for the monitoring steps in the Payroll Control Center (PCC)

TABLE OF CONTENTS
INTRODUCTION AND RELEVANT ENTITIES ..................................................................................................... 3
Chart-based KPIs .............................................................................................................................................. 3
Numeric KPIs .................................................................................................................................................... 4
CONFIGURATION AND IMPLEMENTATION ...................................................................................................... 4
Introduction ...................................................................................................................................................... 4
KPI Types .......................................................................................................................................................... 5
Configuration ...................................................................................................................................................... 5
Implementation .................................................................................................................................................. 6
Implementation of chart-based KPIs ................................................................................................................ 6
Implementation of Numeric KPIs ...................................................................................................................... 7
Further types of KPIs ......................................................................................................................................... 7
Delivered examples............................................................................................................................................. 8
KPI Classes ........................................................................................................................................................ 8
Assignment of KPI Classes to Payroll Processes ............................................................................................. 8
Instantiation of KPI Types for Payroll Processes ............................................................................................ 8
TRIGGERING CALCULATION OF KPI RESULTS ................................................................................................. 8
Backend calculation ......................................................................................................................................... 9
Integration into Payroll Process ...................................................................................................................... 9
AUTHORIZATIONS ............................................................................................................................................ 9
Payroll Manager................................................................................................................................................ 9
Daemon batch user ......................................................................................................................................... 10
Others .............................................................................................................................................................. 10
1.

This document describes the concept and required steps to configure and calculate KPIs for the monitoring
steps in the Payroll Control Center. This functionality is available from HR Renewal 2.0 FP3 for Processes
with business logic version 002 (FP3).
It is assumed that the reader is familiar with the common concepts of the Payroll Data Source Framework.

Introduction and relevant entities

KPIs in the sense of this document are supposed to provide the payroll manager with key figures that
represent contexts for the consistency check error monitoring of the current Payroll Process Instance.
They can be displayed on the user interface for the monitoring steps. Monitoring steps are those that
use a Step Template with category MONI. The user interfaces look like the following:

The part of the screen showing the KPIs is marked. It allows grouping of KPIs, using the so-called
Analytics Section. In the picture, one Analytics Section is shown, named Gross Payroll. It has two KPI
Instances assigned (Active Employees and Active employees difference), showing the values
calculated for the current Process Instance.
Currently two types of KPIs are supported in standard: Chart-based and Numeric. Both have header and
footer texts, and they have the following capabilities:

Chart-based KPIs

Maximum three lines with text and value.

A value can be a flat number or an amount with currency.
For each line, a color code can be defined. Available color codes are listed in the following. They
are translated to suitable real colors by the UI.
o C (Critical)

o E (Error)
o G (Good)
o N (Neutral). This is the default value.

Numeric KPIs

One value allowed with trend information. The trend can be coded using the following values:
o U (Up)
o D (Down)
o N (Neutral). This is the default value.
The value can be a flat number or an amount with currency.
There are two styles available for displaying the value:
o S (Standard). This is the default value. It ensures that the value is fully displayed
(formatted according to the users frontend settings, currency attributes etc.) and not
abbreviated.
o K (Short). Abbreviations and rounding apply for displaying the value. Example:
12300000 is displayed as 12M.
Also here, a color code can be defined. For the list of available values, see above.

Configuration and Implementation

Introduction
The list of Analytics Sections and the correspondingly assigned KPI Instances can be defined for each
Payroll Process individually. The configuration follows a template concept, allowing reuse and predelivery
of those templates by SAP and partners. In the customer system, the delivered templates can be
directly used and/or copied and adjusted, and the decision has to be made which parts of the templates
are to be used for a given Payroll Process.
The following picture shows the Meta model of the KPI configuration.

KPI Types can be defined in configuration and be assigned to Analytics Sections that are part of KPI
Classes. A KPI Class reflects the maximum list of Analytics Sections and KPI Types that can be used for a
Payroll Process. For a given Payroll Process, maximum one KPI Class can be used. For each assigned KPI
Type it is possible then to instantiate it once for that Payroll Process (or more than once, depending on
the KPI Type Parameter configuration, see below).
The following example shows a KPI Class XYZ with one Analytics Section and three KPI Types. Payroll
Process ABC uses that KPI Class but only has KPI Instances for two of the KPI Types; the third one is not
used by Payroll Process ABC and is therefore not shown on the UI.

KPI Types
Configuration
In the system, KPI Types are reflected by Data Source Types of category KP (Key Performance Indicator).
The following Data Source Type configuration is required in view cluster VC_PYD:
5

 General Attributes
o Run time class has to inherit from one of the following:
CL_PYC_KPI_CHART_BASE for chart-based KPI Types.
CL_PYC_KPI_NUMERIC_BASE for numeric KPI Types.
o Category is KP.
Input Parameter Types
o PYP_PROC (Payroll Process ID): fixed, mandatory, key)
o PYP_PROC_INST (Payroll Process Instance ID): not fixed, mandatory, key)
Result Parameter Types
o PYP_KPI_RESULT (Payroll Process KPI Result): no simple error status
Result Details Type PYP_KPI (Payroll Process KPI)
Optionally, an icon from the SAPUI5 icon list can be assigned to the KPI Type. This icon is additionally
displayed then by the user interface for a corresponding KPI Instance.
o To reach that, the technical name of the icon has to be configured for UI Category PYC.UI5.MO, Attribute
ICON, for example sap-icon://employee.
Implementation
The implementation of KPI Types follows the usual pattern to implement Data Source Types using ABAP
interface IF_PYD_TY_RT. For increased development productivity, tailor-made base implementations are
available that take over most of the required common logic using the well-known template method
pattern with hook methods that can be redefined by the concrete KPI Type implementation classes.
KPI Types use the Data Source Result Context CL_PYC_RES_CONTEXT, that is, via the result context it is
possible at run time to derive the current values of the following Parameter Types:

PYP_PROC (Payroll Process ID)

PYP_PROC_INST (Payroll Process Instance ID)
<Instance Selection Parameter Type of the assigned Payroll Process Template>, for instance
ABKRS (Payroll Area)
<Time Selection Parameter Type of the assigned Payroll Process Template>, for instance PERIOD
(Payroll Period)

The framework does not perform any trend analysis, comparison with previous periods etc. on its own.
Such logic has to be specifically implemented by a concrete KPI Type implementation class.
Implementation of chart-based KPIs
The base class for chart-based KPIs is CL_PYC_KPI_CHART_BASE. A concrete KPI Type implementation
class has to inherit from it. The following hook methods are provided for redefinition:
CHART_INFO_CALCULATE: This method is supposed to calculate up to three chart values and their
attributes, based on the selection parameters transported via the result context. The return table can
have up to three lines (others are ignored) and has the following columns:
o INDEX: 1, 2 or 3
o P_TYPE: This one defines whether the calculated value is a 4-byte integer or an amount.
Available values are defined in constant structure CL_PYC_AUX=>GCS_P_TYPE.
o INT4: Contains the chart value if it is an integer.
o MAXBT and WAERS: Contain the chart value if it is an amount with currency.

The expected format of the amount follows the general format used in R/3 Payroll:
Internally all amounts are defined with 2 decimals (usually using data type MAXBT),
independent of the currency. For external formatting, the amount is brought into a
normalized form by the framework and is formatted by the user interface according to
the users frontend settings and the currencys attributes like number of decimals.
o COLOR: Contains the color code, see above. Available values are defined in constant
structure CL_PYC_RT_FACADE=>GCS_KPI_COLOR.
CHART_ITEM_TEXT_GET: This method is supposed to determine the text of a given chart item in the
users logon language. It gets the result context and the index of the item (1, 2 or 3) as input.
FOOTER_GET: This method is supposed to determine the footer text of the KPI. It gets the result
context and available KPI information (output from method CHART_INFO_CALCULATE in a flat
structure) as input. It can define the text in the users logon language and is allowed using one
variable. The variable has to be represented by &1 in the text. The variable content can be
typed to a certain degree in order to allow formatting by the user interface according to the
users frontend settings (and currency attributes, if applicable).
HEADER_GET: This method determines the header text. Capabilities and signature are equal to
method FOOTER_GET.
Implementation of Numeric KPIs
The base class for numeric KPIs is CL_PYC_KPI_NUMERIC_BASE. A concrete KPI Type implementation
class has to inherit from it. The following hook methods are provided for redefinition:
FOOTER_GET: See analogue method for chart-based KPIs. The KPI info comes from
NUMERIC_INFO_CALCULATE instead.
HEADER_GET: See analogue method for chart-based KPIs. The KPI info comes from
NUMERIC_INFO_CALCULATE instead.
NUMERIC_INFO_CALCULATE: This method is supposed to calculate the numeric value and its
attributes, based on the selection parameters transported via the result context. The exported
fields are the following:
o EV_KPI_COLOR: Color code, see above. Available values are defined in constant
structure CL_PYC_RT_FACADE=>GCS_KPI_COLOR.
o EV_KPI_TREND: Trend, see above. Available values are defined in constant structure
CL_PYC_RT_FACADE=>GCS_KPI_TREND.
o EV_KPI_STYLE: Style, see above. Available values are defined in constant structure
CL_PYC_RT_FACADE=>GCS_KPI_NUM_STYLE.
o EV_P_TYPE: This one defines whether the calculated value is a 4-byte integer or an
amount. Available values are defined in constant structure CL_PYC_AUX=>GCS_P_TYPE.
o EV_INT4: Contains the value if it is an integer.
o EV_MAXBT and EV_WAERS: Contain the value if it is an amount with currency.
Concerning the format of the amount, refer to the analogue instructions for chart-based KPIs.
Further types of KPIs
Since the standard user interfaces and highest-level backend APIs (OData, Process Frameworks run time
facade) only allow using chart-based and numeric KPIs, introduction of new types of KPIs currently only
makes sense if the low level Data Source Framework API and Process Framework API are directly used.
Display of the corresponding results would have to be implemented as custom development. In that case,
it is recommended to at least follow the general configuration structure of the standard KPI Types as
described above. The implementation classes should inherit from CL_PYC_KPI_BASE.

Delivered examples
For illustration purposes the following entities are delivered in standard. Their implementation should
not directly be taken over into productively used KPIs.
Chart-based KPI Type PYP_KPI_EX_AMT_CHART that can be used for calculating the total amount
for a given wage type for the current and the last payroll period.
o This KPI Type has an additional mandatory input parameter type LGART (Wage Type)
and allows creating multiple KPI Instances for the same Payroll Process but with different
wage types. As a result, this leads to multiple KPIs displayed in the user interface.
Numeric KPI Type PYP_KPI_EX_EE_NUM that can be used for calculating the number of
employees in a payroll process for the current period.
KPI Class PYP_KPI_EX containing two Folders/Analytics Sections (Employees and Amounts)
that have the example KPI Types assigned.

KPI Classes
Configuration of a KPI Class is done in view cluster VC_PYD_CLASSN: A KPI Class is a Data Source Class
with category PY_PROC_KPI (Payroll Process KPI Structure). The Analytics Sections are reflected by the
Folders of that Class, and each Folder can get KPI Types assigned. As always, the display sequence can be
influenced using the various sort fields.

Assignment of KPI Classes to Payroll Processes

The attribute view for Payroll Processes (V_PYC_D_PYP) has a field KPI Class that allows assigning a KPI
Class.

Instantiation of KPI Types for Payroll Processes

As described above, it has to be fixed in configuration which KPI Types of the corresponding KPI Class are
supposed to be used for a given Payroll Process. For that, corresponding KPI Instances have to be created
for each of those KPI Types.
This is done in the common view cluster for configuring Data Source Instances (VC_PYD_INST). Each KPI
Instance (= Data Source Instance) needs to fix at least Parameter Type PYP_PROC of the underlying KPI
Type (=Data Source Type) to the ID of the given Payroll Process.
The Parameter Type PYP_PROC_INST must never be fixed in configuration but is always automatically
determined by the framework in order to create the Data Source Result that reflects the values of the
KPI Instance for a given Time Selection Parameter Value (for instance, PERIOD = 201501).
In case further Input Parameter Types have to be fixed for the KPI Type (for instance, when using the
delivered example KPI Type PYP_KPI_EX_AMT_CHART), they have to be added to the KPI Instance
configuration, too.
If a KPI Class is assigned to a Payroll Process and at least one corresponding KPI Instance exists, the user
interface shows the KPI information in the monitoring steps. An Analytics Section is shown if there is at
least one existing KPI Instance assigned to it via its KPI Type otherwise display of that Analytics Section
is omitted.

Triggering Calculation of KPI Results

The KPI calculation is not done on the fly but there is a list of possibilities to asynchronously perform this
calculation:

Backend calculation
The fundamental report for calculation of the KPI values (to be more accurate: for creation/refresh of the
Data Source Result that reflects KPI Instance values for a given Payroll Process Instance) is
PYC_EXECUTE_POLICIES.
That report allows specifying a Payroll Process Instance (+ restriction to a list of KPI Instances) and has to
be started with option KPI Calculation.
Apart from the normal Payroll Process Instance configuration, the KPI configuration (KPI Types, KPI Class,
KPI Instances for Payroll Process, assignment of KPI Class to Payroll Process) has to be completed as
precondition for starting the report.
The report can be started manually (in particular for testing), planned for regular execution as batch job
or integrated into the Payroll Process handling. The latter is the recommended approach for productive
use:

Integration into Payroll Process

In principle it is possible to plan the execution of that report in context of a custom Payroll Process Step,
using for instance the Payroll Control Centers Batch Processing Framework (copy template:
PYP_V2_ASYNC_BATCH_BASE).
For convenience, the execution of the report has been integrated into the delivered standard Process
Step Template PYP_V2_INIT_POLICIES (Initialize Policies), which is supposed to be executed directly
before the monitoring steps: When the used Payroll Process Template contains that Step Template, the
calculation of the current KPI values is automatically done.
The standard approach does not refresh the KPI values during the execution of a monitoring Step
Instance. That means if the KPIs are calculated in a way that their results can dynamically change and
that those changes are supposed to be reflected during the execution of the monitoring, the refresh of
the values has to be incorporated into the monitoring step. This can be achieved for instance by copying
the standard monitoring Step Template (PYP_V2_MONITORING) to a custom one, to inherit from its
implementation class and to add the start and stop of a regular batch job running the KPI calculation
report via redefinition of the corresponding methods.

Authorizations
There are different user roles accessing KPIs, requiring the following authorization configuration:

Payroll Manager
The general authorization concept for the Payroll Manager works on the level of the Payroll Process. For
the KPIs this has not changed. Therefore a Payroll Manager is allowed to see the KPI results of a
monitoring step of a given Payroll Process if he/she has the authorization to read data for the Payroll
Process (authorization object P_PYD_INST).
To simplify authorization configuration, there are no additional authorization checks for the individual
KPI instances. This follows the existing overall authorization concept of the Payroll Control Center.
9

Technically these authorization checks are performed by the highest level Payroll Process Framework
APIs (OData and run time facade).

Daemon batch user

The calculation of KPI results is asynchronously performed by the Daemon batch user that had been
configured in the Payroll Control Centers administration transaction. Usually that user has full
authorization for the Payroll Control Center. Nevertheless the KPI calculation report
(PYC_EXECUTE_POLICIES) performs the following authorization checks:
1. User has to have general report start authorization for technical reports of the Data Source
Framework (P_PYD_AAUT)
2. For each connected KPI Instance, the user needs to have authorization to refresh it (P_PYD_INST).
The direct authorization for accessing the Payroll Process (as done for the Payroll Manager) is not
additionally checked, as the already performed authorizations according to item 2 are closely connected
with the Payroll Process: All KPI Instances are specific for the Payroll Process; therefore checking
authorization for them is surely sufficient.

Others
Any other user who starts PYC_EXECUTE_POLICIES directly in the backend needs to have the
authorizations as described above.
For accessing the KPI Classes and KPI Instances (refresh or reading results) via the common highest level
Data Source Framework APIs (OData, Data Source Framework run time facade) the common
authorization checks apply (P_PYD_CLS and P_PYD_INST). But even if that is a valid way to access Data
Source Results, that use of the common APIs it very unlikely to happen, as the straight-forward use will
only allow looking at the KPI Class and KPI Instance attributes. Retrieval of KPI results would require
setting a user (session) variant first for the requested Payroll Process Instance, which is possible in
principle but using the Process Framework APIs is much easier (and would require less but more suitable
authorizations).

10

www.sap.com

2015 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form
or for any purpose without the express permission of SAP SE or an SAP
affiliate company.
SAP and other SAP products and services mentioned herein as well as their
respective logos are trademarks or registered trademarks of SAP SE (or an
SAP affiliate company) in Germany and other countries. Please see
http://www.sap.com/corporate-en/legal/copyright/index.epx#trademark for
additional trademark information and notices. Some software products
marketed by SAP SE and its distributors contain proprietary software
components of other software vendors.
National product specifications may vary.
These materials are provided by SAP SE or an SAP affiliate company for
informational purposes only, without representation or warranty of any kind,
and SAP SE or its affiliated companies shall not be liable for errors or
omissions with respect to the materials. The only warranties for SAP SE or
SAP affiliate company products and services are those that are set forth in
the express warranty statements accompanying such products and services,
if any. Nothing herein should be construed as constituting an additional
warranty.
In particular, SAP SE or its affiliated companies have no obligation to pursue
any course of business outlined in this document or any related presentation,
or to develop or release any functionality mentioned therein. This document,
or any related presentation, and SAP SEs or its affiliated companies
strategy and possible future developments, products, and/or platform
directions and functionality are all subject to change and may be changed by
SAP SE or its affiliated companies at any time for any reason without notice.
The information in this document is not a commitment, promise, or legal
obligation to deliver any material, code, or functionality. All forward-looking
statements are subject to various risks and uncertainties that could cause
actual results to differ materially from expectations. Readers are cautioned
not to place undue reliance on these forward-looking statements, which
speak only as of their dates, and they should not be relied upon in making
purchasing decisions.