Two of the most popular Business Add-Ins (BAdIs) in SAP Human Capital Management (HCM) Performance Management (PM) are HRHAP00_VAL_DET, which calculates default values for fields, and HRHAP00_DOC_BC, which allows you to perform check routines and generate messages to avoid common mistakes by users. For each of the BAdIs, we’ll:

• Show the specific design and situations in which you can use them
• Demonstrate how to include implementations in a performance template
• Show SAP out-of-the-box implementations
• Provide a coding example
• Discuss some issues and surprises

Calculate Field Values

BAdI HRHAP00_VAL_DET allows you to determine the value of a field in the template based on any rules that you define and include in the ABAP coding. Here are a few suggestions to use this BAdI:

• Set target values for objectives that have the same constant value for all staff or a defined group of staff


• Set target values that you can calculate from other data in the system, such as a custom table that holds targets per department or custom fields in Organizational Management that hold objectives


• Calculate upper and lower limits for target corridors based on the 100% target and a given percentage


• Apply weighting to results


• Calculate aggregated values over several lines of the form to fill the top line


• Determine a bonus amount and show it in the form if you aren’t using SAP Enterprise Compensation Management for this purpose

As discussed in our last article, you must create an implementation (referred to as an enhancement in the performance template) to use a BAdI. Each implementation uses one or several of the methods that a BAdI provides. Methods are various program functions with a predefined interface for incoming and outgoing data and are elements of object- oriented (OO) programming (e.g., ABAP OO). The methods contained in BAdI HRHAP00_VAL_DET are provided in Figure 1.

Figure 1

Available methods in BAdI HRHAP00_VAL_DET

Most of the SAP HCM PM BAdIs have one central method for performing their core functions. In this case, method VALUE_DETERMINATION is responsible for calculating the value and assign ing it to a chosen field. This method delivers the core functionality (determining a value), so using BAdI HRHAP00_ VAL_DET without this particular method doesn’t make sense in most circumstances. However, we have seen many implementations without any of the other methods, which serve secondary purposes that are not always necessary. Before focusing on the core method in more detail, here is a brief overview of the other methods:

GET_INFORMATION: This method allows you to provide a description or documentation of the BAdI implementation so that the configuration expert can easily determine a BAdI’s intended function. He or she can access this information by clicking on an i icon that appears after you select the respective enhancement, as shown in Figure 2.

Figure 2

Info icon for documentation of the implementation

CHECK_EXECUTABILITY: Use this method if the BAdI implementation should only be effective in certain circumstances (e.g., in a particular status)

CHECK_UI_DEPENDENCY: This method has a similar purpose to the last one, but specifically employs the user interface. In special cases, you might want the system to perform one thing if the user accesses it via SAPGUI for Windows and behave differently if the user accesses it via a Web browser. This method distinguishes such cases and is a part of many BAdIs.

CUST_COLUMN_RESTRICTION and CUST_CHECK_EXECUTABILITY: Neither method influences the system behavior in the application. They only influence customizing in the template configuration transaction PHAP_CATALOG _PA. Here you can implement checks (e.g., allowing only a certain enhancement to be used for particular columns). While this surely helps the configuration expert, implementing these methods only pays off if you have a huge variety of templates and BAdI implementations. In general, you should assume the configuration expert knows what the BAdIs are supposed to achieve. We don’t recommend you invest a lot of effort just for a little bit of convenience in configuration through additional check routines. Your effort is better invested in improving efficiency and usability for end users, who are more numerous than configuration experts.

VALUE_DETERMINATION: This is the core method that we mentioned earlier. It is important to examine the parameters available so you know your options for calculating new values. These parameters are the data upon which you must build your calculations. Of course you can include other data from anywhere in the system, but the parameters in this method are the starting point to select the right data. For example, if you want to use a person’s period of service, you need the personnel number to obtain the necessary data. Figure 3 shows the parameters of the method VALUE_DETERMINATION.

Figure 3

Parameters available for the method VALUE_DETERMINATION

As you can see from all the Importing lines in the Type column, a wealth of data is available to use in your calculations, especially because most of the parameters are not single values, but are tables or structures. For example, the personnel number coupled with further personal data is available in the parameter T_HEADER_APPRAISEE. Generally, the system already provides all data in the form for calculations. You need to write the final value that should appear in the field by filling parameter T_BODY_CELLS. You must set the parameter NEW_VALUE_DETERMINED to X to indicate that a change has occurred.

In some cases, you should only fill the field if it doesn’t already contain a value (e.g., to set a default value). Conversely, you might want to overwrite the value already in the field to achieve your business purpose. Be sure to take such cases into consideration for your design.

Here are some best-practice steps to follow when developing custom coding in such a complex BAdI (see part 1 of this series for technical details):

1. Decide on the parameters that you need

2. Build an implementation that is only a breakpoint in the coding

3. Assign the implementation to a form

4. Use the form in a test run. The system will stop at your breakpoint and then you can see whether the parameters hold the data you thought they would and in which format they do so. In quite a few cases, the table has the fields for the data you need, but they are not populated when you perform the BAdI implementation. It is wasted effort to write a lot of coding based on assumptions only to find out later that the data fields you used in your coding are empty.

5. Develop your coding based on the insights from the fourth step. You might even need to change your design if the parameters don’t hold the expected data.

Figure 4 is a straightforward coding example that illustrates how you can implement the value determination method. This implementation calculates the value of a custom column payment date (for a bonus related to one objective) based on the custom column event date, which contains the date of the event to which the objective refers.

method IF_EX_HRHAP00_VAL_DET~VALUE_DETERMINATION.
 data: gt_cells  type HAP_S_BODY_CELLS,
       gt_cells2 type HAP_S_BODY_CELLS.
 data: lv_monat(2)  TYPE c,
       lv_jahr(4)   TYPE c.
*** Loop on all relevant fields – read date
  loop at T_BODY_CELLS into gt_cells where CELL_VALUE_EXIT = ‘Y_PAYMENT_DATE’.
*** Get and write payment date
    loop at T_BODY_CELLS into gt_cells2 where row_iid = gt_cells-row_iid
                                          and column_iid = 13.
      clear: lv_jahr, lv_monat.
*** Event date initial: May next year
      if gt_cells-value_NNV IS INITIAL.
      lv_jahr  = s_header_dates-ap_start_date(4).
      lv_monat = s_header_dates-ap_start_date+4(2).
*** Set year and month
      ELSE.
      lv_jahr  = gt_cells-value_NNV(4).
      lv_monat = gt_cells-value_NNV+4(2).
      ENDIF.
*** Calculate date depending on event date
       lv_jahr = lv_jahr + 1.
       Concatenate ‘31.05.’  lv_jahr into gt_cells2-value_txt.
       Concatenate lv_jahr ‘0531’ into gt_cells2-value_NNV.
       clear gt_cells2-no_value.
       modify t_body_cells from gt_cells2.
    ENDLOOP.
  ENDLOOP.
endmethod.

To better understand the example, here are a couple remarks:

• The table T_BODY_CELLS contains the cell values. This is where you retrieve data from other cells to calculate your result and store the result for the field that you want to change.


• The T_BODY_CELLS-CELL_VALUE_EXIT includes the enhancement that you use to assign the BAdI implementation to a field in the template. In your coding, you can use this to discover which cell you actually need to change. This is the function of the where condition in the first loop of our coding example.

In part 1 of this article series, we demonstrated the general procedure to include a BAdI implementation into a template. Now we’ll show you the final step in the template catalog (via transaction PHAP_CATALOG_PA, which assigns the enhancement to a field in the template), as it pertains to this BAdI.

First, choose the template and the line to which you want to assign the enhancement. Figure 5 demonstrates this process, assuming that you want to assign the enhancement to the top line.

Figure 5

Select the line to which you want to assign the enhancement

In the screen that appears, choose the Columns tab in the middle of the screen (Figure 6). Find the Value Determination field and enter the name of the enhancement (in our example, TOTAL) for the field you want to fill (in our example, Final Appraisal).

Figure 6

Assign the enhancement to a field in the template

Now, you have properly assigned the enhancement to a field in the template. However, before you build your own enhancement, look at what is available out of the box. Figure 7 shows 16 available enhancements. We will not describe them any further because they are documented in the system.

Figure 7

Out-of-the-box implementations for HRHAP00_VAL_DET

The main question for this BAdI is when the system actually triggers it. By default, the BAdI isn’t triggered when assigned to a display-only field. The column access configuration in the template catalog (via transaction PHAP_CATALOG_PA, as shown in Figure 8) assigns one of the values shown in Figure 9 to each column, depending on whether or not the user is the column owner. The Column Owner in Figure 8 determines access rights in the other columns, and it is suggested that this is the person responsible for the column’s content, although you don’t need to configure it that way. Similar options are available for rows in the Column Access configuration and for individual fields in the Columns tab as shown in Figure 6.

Figure 8

Out-of-the-box implementations for HRHAP00_VAL_DET

Figure 9

Options available in the Column Access tab

While default values are usually set for input fields, you can assign a calculated value to a field without the user having the ability to change it. In this case, the system cannot trigger your BAdI implementation and no calculation occurs. Therefore, we decided to include all of our background calculations in one single implementation that we’ve attached to one input field so the system always triggers this BAdI implementation. You then use the assignment of the other enhancements in the template only to identify the respective fields in the coding through the value T_BODY_CELLS-CELL_VALUE_EXIT, as demonstrated in the coding example in Figure 4. These other enhancements don’t have any coding behind them. They are dummies that the system uses only to identify the fields in the coding. It’s similar to adding a sign in the field, such as, “Do X calculation when finding X field.”

There are certainly other ways to deal with a BAdI implementation that is not triggered when assigned to an output-only field. However, this way is straightforward and has the additional advantage of having all calculations in one place so that you can control the sequence in which the system performs them.

Perform Checks and Generate Message

The BAdI HRHAP00_DOC_BC allows you to perform check routines and generate messages for the user. Users who fill in the forms have many rules to observe because policies around objective setting and appraisal can be complex. These rules are usually unique to each organization’s performance management system and often require custom coding. Here are a few examples of common rules:

• Define upper and lower limits for weighting individual objectives
  
  
• Require a certain sum of weightings over a group of objectives (e.g., objectives for personal development must add up to an aggregate weighting of exactly 25% or sales objectives must be at least 50% for members of the sales force)


• Make sure that the sum of all weightings is 100 when you finalize the form, but allow the user to save the form with less than 100 if work is in progress. Nobody is happy if the system doesn’t allow you to save half an hour’s work only because you haven’t managed to enter the last objective before you go to a meeting. As a rule, it should always be possible to save the form in an intermediate state, allowing for a break. Remember that your portal probably performs an automatic log off when there is no user action registered for a couple of minutes.
• Require the system to generate a note if a criterion is rated lower than a certain limit
• Specify that the bonus assigned on any sales target cannot be more than 5% of the target volume

You’ll find many such rules in your organization and those users who fill in the form value support as much as those who have to deal with forms incorrectly filled in at the end of the process.

Looking at the methods of this BAdI, you can see that it looks much less complex than the first BAdI (Figure 10). There’s only the GET_INFORMATION method, which is similar to HRHAP00_VAL_DET, and the core method DO_ BUSINESS_CHECK (where the coding for the check routines belongs). Unlike HRHAP00_VAL_DET, you can only use one implementation of HRHAP00_DOC_BC in any one template. This is due to the way the system assigns the enhancements to the template (based on these implementations), which we’ll describe later in the article. Therefore, all your checks must be in one piece of coding, but this isn’t a problem. You just need to give your coding a proper structure so that it doesn’t become confusing.

Figure 10

Methods of BAdI HRHAP00_DOC_BC

Figure 11 shows the set of data available to use in your coding within the method DO_BUSINESS_CHECK. Typically, everything you need to check resides in this screen, such as data on the appraiser and appraisee and the status of the template (old and new, depending upon whether the user tries to perform a status change). The status is usually important. Some rules that you don’t enforce when the form is still “in process,” you must enforce when the status is about to be changed to “completed.” When problems arise in the “in process” status, they appear in an information message, and when the system detects problems in the “completed” status, an error message prevents the user from proceeding.

Figure 11

Parameters of the method DO_BUSINESS_CHECK

One parameter can be rather confusing — ERROR_PROCESS_MODE. It suggests that if the parameter has the value X, you can display several messages at once. However, the system always shows only the first message and ignores any others until you eliminate the reason for the first message. This prevents you from telling the user everything about the mistakes so that he or she can choose in which sequence to work on them. In some cases, this workaround can help — for sets of problems that occur together, you can design one combined message and show this instead of several messages. This advice is not always practical but we did use it occasionally for weighting issues.

For the output of your custom coding, you have to insert your messages into table T_RETURN, as demonstrated in the coding example in Figure 12. This piece of coding checks whether a user has attempted a status change from “in planning” to any other status. Only in this case, an error message is generated (message type set to “error” accordingly) in the second part of the coding. This ensures that you can save the template, even if it is incomplete. It is a common practice to check for a status change at the beginning of this BAdI and then to do the business logic check.

method IF_EX_HRHAP00_DOC_BC~DO_BUSINESS_CHECK.
*-- Includes
  INCLUDE:
            incl_hap_columns,
            incl_hap_doc_status,
            incl_hap_elements,
            incl_hap_notes,
            incl_hap_screen,
            incl_hap_messages,
            incl_hap_pa_global.
*-- Workarea definition * standard
  DATA:
        lw_body_element   TYPE hap_s_body_elements,
        lw_body_column    TYPE hap_s_body_columns,
        lw_body_cell      TYPE hap_s_body_cells,
        lw_return         TYPE bal_s_msg.
*-- Data definition * standard
  DATA:
        l_min_value       TYPE hap_value_num,
        l_msgty           TYPE symsgty.
*** Field-Symbols
 FIELD-SYMBOLS:  TYPE hap_s_body_cells.
  IF s_doc_processing-mode EQ c_mode_display.
*-- Check only performed during completion -> Exit, if display only
    EXIT.
  ENDIF.
**********************************************************************
*** When to perform the checks? 
*** When to use error or info messages?
**********************************************************************
  IF s_status_new-ap_status EQ c_status_completed.
  ELSEIF s_status_old-ap_status EQ c_status_in_planning
  AND    s_status_new-ap_status <> s_status_old-ap_status.
* Old status: in planning and status change attempted.
    l_msgty = c_message_type_e.
  ELSE.
* all other statuses: do nothing
    EXIT.
  ENDIF.
**********************************************************************
*** Find relevant fields 
*** Generate message, if necessary
**********************************************************************
*** Find column for final result
  READ TABLE t_body_columns WITH KEY
                              column_id = c_column_fapp
                            INTO lw_body_column.
  IF sy-subrc NE 0.
*-- FAPP not available -> Exit
    EXIT.
  ENDIF.
*** Find relevant rows (the happen to have the value enhancement ‘Y_COMP’
LOOP AT T_BODY_CELLS into lw_body_cell
                     where cell_value_exit = ‘Y_COMP’.
*** Perform check in this row
LOOP AT T_BODY_CELLS ASSIGNING 
                     where row_iid    = lw_body_cell-row_iid
                     AND   column_iid = lw_body_column-column_iid.
 if NOT -no_value IS INITIAL. “field empty
        lw_return-msgty = l_msgty.
        lw_return-msgno = ‘000’.
        lw_return-msgid = ‘Z_HRHAP00_DOC_PA’.”Message text
        APPEND lw_return TO t_return. “fill output parameter table
        CLEAR: lw_return.
 ENDIF.
ENDLOOP.
ENDLOOP.
ENDMETHOD

The business logic check is also quite simple. First, the system identifies the fields that you need to check — in our example, the system assigns rows to Value Determination and you can easily recognize them. Then the coding checks whether a column in these rows is empty. If it is, the coding generates an error message. You’ll be able to follow the logic when studying the coding example in Figure 12. At first sight, this has the same effect as just declaring the respective fields as mandatory. However, it also provides flexibility because you can allow the user to save it in spite of the empty fields, as long as he or she didn’t attempt a status change.

Once you complete the code and create the enhancement, as described in part 1 of this series, you can assign the enhancement via the Processing tab in the template configuration. Figure 13 shows this step using an example called Mandatory Note for Low Valuation. In this example, the note box text is mandatory if the rating for a certain criterion falls below a particular level. This is the only out-of-the-box, standard SAP implementation provided in this BAdI.

Figure 13

Assign a business check enhancement

We’ve already mentioned that you can generate only one message at a time. The second issue with this BAdI is that it cannot generate warning messages on the Business Server Page (BSP) technology that people use for the Web- based user interface, although it appears as if it should at first sight. Therefore, you have to use info messages instead of a warning, which can be slightly inconsistent with how the system usually responds to some situations.

In part 1 of this series, we noted that most SAP HCM PM implementations use BAdIs. We believe this statement also remains true for these two BAdIs. It is therefore worthwhile to make yourself familiar with them and the various out-of-the-box implementations that are provided.

Jens Richter

Jens Richter is consultant for SAP HCM at iProCon where he has worked on several projects in Performance Management for clients in various industries.

You may contact the author at j.richter@iprocon.de.

If you have comments about this article or publication, or would like to submit an article idea, please contact the editor.

Sven Ringling

Sven Ringling is executive director at iProCon (www.iprocon.de) and iProCon Human Capital Management (www.iproconhcm.co.uk). He started working as an SAP HCM consultant in 1996 and also works in strategic HR and change management. He is one of the authors of the books Mastering HR Management with SAP and HR Personnel Planning and Development Using SAP.

You may contact the author at s.ringling@iproconhcm.co.uk.

If you have comments about this article or publication, or would like to submit an article idea, please contact the editor.