Configuration Guide: Compensation Integration with SAP On-Premise Payroll

Document ScopeThis document describes SuccessFactors BizX configuration to enable integration between SAP On-Premise Payroll and SuccessFactors BizX Compensation. There are also steps required to set up the SAP On-Premise system, and these steps are documented separately. Consult your SAP Support Representative for the SAP side documentation.

Note: For additional information on the SAP side of the integration, you can also join the JAM group called SAP HCM Exchange. Contact Stephanie.Morgan@sap.com for access to SAP HCM Exchange Jam group. This guide is only meant to supplement the more detailed documentation available on the JAM site. Please see the SAP HCM Exchange JAM group and read through the SAP documentation in addition to this guide.

Integration DescriptionThis integration is designed to handle export of SAP On-Premise Payroll data to SuccessFactors for input to the compensation process, and extract of SuccessFactors compensation planning results for import back to the SAP On-Premise Payroll system.

This integration utilizes SuccessFactors web services for both import of payroll data, and web services for extract of compensation results. There are SAP software add-ons to provide the SAP side capabilities. For details on the SAP software add-on, contact your SAP support representative, or go to http://service.sap.com/rampup > Ramp-Up Programs > SAP Application Components > SuccessFactors-HCM Integration 2.0 (and other links for payroll to comp integration?)

A diagram of this integration appears below.

The integration to SuccessFactors is enabled through the SFAPI – SuccessFactors SOAP Web Services API. The integration process is designed to import employee current salary data at the beginning of the compensation process. Then the compensation planning process is performed in the SuccessFactors BizX solution. At the end of the process, the compensation allocation results are pulled from SuccessFactors through the SFAPI.

The SFAPI provides a database style interface where logical entities can be dealt with through CRUD (Create, Read, Update and Delete) operations. This process uses the following two entities types:

1. EmployeeCompensationStagingFields Entities2. AdHocReport Entities

An overview of these entity types and their purpose is described below.

EmployeeCompensationStagingFields EntitiesThe EmployeeCompensationStagingFields entity type allows you to import employee current salary data to a staging table in the SuccessFactors system. This data can then be propogated to in-process compensation forms which are related to one or more compensation plan templates. For example, in your Compensation Planning Process you may have two compensation plan templates, one for “2012 Employee Compensation Planning” and another for “2012 Executive Stock and Bonus Planning”. Each of these plan templates will have multiple compensation forms generated (typically one per manager with the subjects of their direct reports on the compensation form).

Compensation Group IDCompensation Plan templates have a new attribute called the “Compensation Group ID” which is used by the SFAPI to group one or more plan templates into a single EmployeeCompensationStagingFields API entity.

For example, you could provide a Compensation Group ID of “2012” for both the “2012 Compensation Planning” and the “2012 Executive Stock and Bonus Planning” templates. When this is done, the SFAPI will generate an API Entity named “EmployeeCompensationStagingFields_2012”, and it will expose a union of all the compensation fields that are enabled in both of these entities. This gives us two features:

1. You can easily import staging table data intended for one or more compensation plan templates.

2. You can easily protect imports from one group ID (say year “2012”) from interfering with, or overwriting imports from another group ID (say year “2011”).

Once data is imported to the staging tables, this data can be used to update in process compensation forms. This update will pull data from the staging table for the form template. It will use the compensation group ID to find the correct data. The forms can be updated from the staging table data through one of two mechanisms:

1. Manually: You can trigger update of compensation forms for one or more templates in Admin Tools.

2. Scheduled: Update of compensation forms for one or more templates can be scheduled on a nightly (or other interval) basis.

AdhocReport EntitiesAt the end of the compensation planning process, the results can be exported from SuccessFactors through the Ad Hoc Reporting framework. The SuccessFactors API can be used to pull results for an existing Ad Hoc Report. For API users with appropriate authorization (set details are specified below), each Ad Hoc Report that is available to the user will also be available through the API as a separate API entity.

The AdhocReport entities will appear in the API with a name of “AdhocReport_<report_id>”, where “<report_id>” is an internally generated unique id for each report. Through the API Tools API Data Dictionary tool Admin Tools, you can view the various AdhocReport entities, and find see the report names that were given when the report was created in the Ad Hoc Report Builder. An example of an AdHocReport entity as viewed in the Admin Tools API Tools API Data Dictionary appears below. Note that you must grant a user with permission to view the API Data Dictionary.

TBD: Show and example of an AdhocReport entity from the API Data Dictionary

The AdhocReport entities are built on top of the Ad Hoc Report Builder framework. The reports are defined separately in the user interface of the Ad Hoc Report Builder tool. For a user who has API Login

Permission, any report they can run in the BizX suite is now available to be run through the API. The reports are run asynchronously by submitting an API asyncQuery job, which returns a job id. The job is posted to in internal report server processing queue, which can be polled to see when the job is completed. When the job is finished, the results are retrieved as a CSV file attachment using the getJobResults API.

Full documentation on the SFAPI and AdhocReport entities are documented in Confluence at https://confluence.successfactors.com/display/ENG/SFAPI+AdhocReport+Entity+Functional+Guide

SuccessFactors Configuration ProcessThe configuration process in SuccessFactors starts with definition of the compensation planning templates. The templates must be created before an integration import can occur, as the SFAPI entities for import (the EmployeeCompensationStagingFields entity types) are dependent on the compensation planning templates.

The setup process is as follows.

Compensation Import Setup

Compensation Template Configuration1. Define the compensation planning templates.2. Assign a Compensation Group ID to each compensation template that you want import through

the same API data feed. You can share a single group ID among multiple compensation templates. One strategy is to group templates by yearly process, where you would designated “2012” as a group id for all the 2012 compensation planning forms. The decision on which templates to group together is an integration choice, and should be driven by how many templates you want to import in a single data feed.

API Configuration

Provisioning ConfigurationEnable the following “SFAPI” and “SFAPI Adhoc Feature” under Web Services settings in Provisioning Company Details

Admin Tools ConfigurationThe above steps will make a new API entity appear called “EmployeeCompensationStagingFields_<group_id>” for each unique Compensation Group ID you have given to your Compensation templates. You can view this entity in Admin Tools API Tools API Data Dictionary as seen below. (Note that must grant a user with permission to access the API Data Dictionary).

TBD: Show a screen shot of API Data Dictionary for an EmployeeCompensationStagingFields entity.

Now that the entity is available in the API, you must give permission to an API user to access this entity. The following permissions must be granted to your desired API user:

1. Decide with user you will use to access the API. It is common to create a special user account for the purpose of API integration.

2. Grant the API user with “API Login Permission”. a. For the legacy permissions framework, this is available in Admin Tools Manage User

Security API Login Permissionb. For RBP, this is available in permission settings under “General User Permission API

User Login”.3. Grant the user with “Employee Import” permission.

a. For the legacy permissions framework, this is granted in the following ways:i. New Admin Tools: Admin Tools Set User Permissions Administrative

Privileges Manage Users Employee Importii. Old Admin Tools: Admin Tools Manage Security Administrative Privileges

Manager Users Employee Importb. For Role Based Permissions, this is granted in the following ways:

i. New Admin Tools: Admin Tools Set User Permissions Manage Employee Import.

ii. Old Admin Tools: Admin Tools Manage Security Manage Employee Import.

Compensation Export Setup

Provisioning SetupThe Compensation Export API depends on the Ad Hoc Report Builder feature and the Compensation Planning Sub Domain Schemas. These must be enabled in provisioning.

Ad Hoc Report DefinitionA summary of the steps here are:

1. Login as a user who has permission to build Ad Hoc reports.2. Build the desired report.3. Run the report to verify the results.4. Share the report with the API User.

We expect that in normal operation, we will not grant the API User permission to define a report. Instead we expect that you will log in as a privileged user with report builder permission who will define the report, and share the report with the API user.

Therefore, login as a user who has permission to create an Ad Hoc Report. Design the desired Compensation report by selecting the desired Compensation Template in the “Data Sets” tab. Note that a report can be based on only one Compensation Template. This is different than the import API which can group multiple templates into a single API import.

In Ad Hoc Reports you can select the desired columns for output on the report. You can also select columns for filtering, and specify whether users can modify the filter values in the report definition. Any filter field that is specified as user-prompted can be used as a filter through the API when querying. Full details of how Ad Hoc Reports work in the API are documented in Confluence at https://confluence.successfactors.com/display/ENG/SFAPI+AdhocReport+Entity+Functional+Guide.

The following fields are absolutely required in the Ad Hoc report fied definition. Additional fields can be added per client requirements.

When the report definition is finished, verify the report results are as expected by running the report in the BizX user interface. The API will receive the same results, so if the report definition is not correct to begin with, the API will suffer the same errors.

When the report results have been verified, you must share it with the desired API user.

Note: If the API User has been granted with permission to define the report, and has created the report, then there is no need to share the report with theirself, as the Ad Hoc framework automatically allows the report designer to run any report they have created.

API User ConfigurationThere is no further API Configuration necessary, assuming the report has been shared with the API User. The report will now be available to the API User who can run it through asyncQuery method.

The report entity will appear to the user in the API as an entity with the name of “AdhocReport_<report_id>” where <report_id> is a unique internal id associated with the report. To find the <report_id> for the report you generated, you can view all the AdhocReport entities in the API Data Dictionary in Admin Tools API Tools API Data Dictionary. (In the New Admin Tools, the location is Admin Tools Company Settings API Data Dictionary). Note that you must grant users with permission to access the API Data Dictionary.

The API Data Dictionary will show the Report Name for each AdhocReport entity. Search for the report name you created above. Expand each AdhocReport entity to view the report name. When you find the

desired report entity, review the fields in the API entity to see they are as expected. Consult the documentation on the Ad Hoc Report API for further details and questions.

Frequently Asked Questions:

1) Where can I go to get more information? Please see the JAM page called SAP HCM Exchange. You need to be invited to this group. Please contact Stephanie.Morgan@sap.com to be invited to this group.

2) Can the client use the API integration to load some data into the form, but use FTP or manual import to load other data? No, this is not possible. Once the integration is enabled by putting a group ID in the compensation template, all user data fields must come from the SAP integration. You cannot have some data pull from SAP and other data imported manually. It is all or nothing.

3) Can the integration handle custom compensation fields? (Not the ~40 standard fields referred to on the Live Expert PPT)

Yes, it can. The field mapping capabilities we have in the configuration of the SAP back-end allow that customers can put all kinds of fields they want and send it over to SFSF. E.g. the fill SFSF standard fields like for example BONUS_ELIGIBLE with a custom own logic in SAP. Or they create a completely new custom field in SFSF and fill it with a custom-logic in SAP…..The field mapping definitely allows this extensibility – we explicitly designed for this purpose. The only point to mention is: The customer also needs to extend the field mapping on the PI content accordingly.

4) Can the integration calculate fields based on 2 or more data pieces in SAP? For example, many clients store Bonus Target % and Annual Salary in SAP. Can the client create a calculation on the SAP side to multiply the Bonus Target % * Annual Salary in order to find the Bonus Target $ Amount?

Yes, that should be possible, but it has to be done via a custom logic in the extraction in SAP to fill the BONUS TARGET AMOUNT field from SFSF. So in other words: Somebody with ABAP Programming Skills has to put in this logic into our standard extraction program. See also my answer above: the whole interface is designed for it. It just needs some custom-programming pieces that are inserted into our logic.

5) I see in the Live Expert PPT, slide 12 that the SFSF field IDs are different than the standard field IDs in SuccessFactors. For example, we typically use SALARY but the PPT says CUR_SALARY. We use COMPENSATION_SAL_RATE_UNITS, but the PPT says UNITS_PER_YEAR. Can you please explain why the field names are different? How should the client set it up?

The reason why the field names are different is because the API format of the fields is different from the ones known through the file format. We came across the same question like you when we did our design. The customer needs to use the field names in the API formatting; otherwise the transfer of the fields will not work.

6) What if the client wants to use the SECOND_MANAGER hierarchy? At the moment, the second manager field is not included in the compensation connector. However, it is included in the standard BizX data connector. The client has 2 options:

(1) They can load the SECOND_MANAGER column manually (2) They can include SECOND_MANAGER on the standard connector.

7) Can you give a little more detail about the custom SFSF field EMPLOYMENT_PERCENTAGE? The compensation module cannot handle Part Time employees, so want to check that this percentage is only for calculating the correct salary on the SAP side to send to SFSF. I think this is going to be very confusing and frustrating for the client, since including these field indicates that we can handle part time salaries, when we cannot.

BW: The Comp-Module can, today, only handle part timers via a custom-field and custom calculation in SFSF. That is why it is documented, that the field EMPLOYMENT_PERCENTAGE needs to be a custom field in SFSF. If the customer wants to purely use the standard capabilities from SFSF without any custom calculation for part-timers, the recommendation is to use the BADI-Implementation for the data extraction in SAP(Badi-Implementation: HRSFI_COMP_ALT_SALARY_ANNPCT): This data extraction method does the following:

“Salary fields with annual salary reflecting a theoretical 100% employment percentage” => Filter value in customizing: SAP_ANNUAL_100PCT_SALARY)”This scenario means, that SAP calculates an annual salary (based on wage types in IT 0008) representing a 100% working time (also for part-timers) and sends this over to SFSF, so that the comp planning process can be done on an annual salary basis reflecting a 100% employment percentage for all employees (also for part-timers). In addition, SAP sends also the REAL employment percentage via the field “EMPLOYMENT_PERCENTAGE”. In return, SAP gets back the annual increase amount representing a 100% employment percentage and SAP divides this value by frequency and real employment percentage to calculate the individual increase amount per employee.

Still, the custom field EMPLOYMENT_PERCENTAGE needs to be created, but no further calculation needed in SFSF. We absolutely needed to send this information to SFSF for the following reason: When we get back the salary increase from SFSF, we need to know on which basis it was calculated on to be able to make the right calculation in SAP to adjust it to the correct frequency and employment percentage. In other words: In SAP`s payroll infotypes, we can only put the value for salary increase in that reflects the REAL pay-out frequency and the REAL employment percentage. When we receive an annual salary increase that represents a theoretical 100% employment percentage from SFSF, we need to convert it into a monthly / biweekly, etc…. amount that represents the real employment percentage before we can activate the salary increase value in SAP.

We know it is a workaround, but there was no other solution that we can offer from a standard procedure. This topic is being considered by product and a possible enhancement could fix the part-time salaried issue in late 2013.

8) What fields are required on the Ad Hoc report to bring data out of SFSF into SAP? The following fields are absolutely mandatory for the import/activation process:

With the above fields included, the annual salary will be updated to the new salary. The client can add additional fields as needed. What is important is that you define in the field mapping, how these fields are handling during import and activation, meaning:

- If the field comes from SFSF - If the field is dynamically calculated in a Badi method - If the field is entered during activation (UI of activation program Report

RH_SFI_ACTIVATE_COMP_DATA) – for example “effective date”.