2078121 - Employee History Processor - Variable Pay

• What is the Employee History data file?
• This KB article provides a general overview of Variable Pay employee history.

**Image/data in this KBA is from SAP internal systems, sample data, or demo systems. Any resemblance to real data is purely coincidental.**

SAP SuccessFactors Variable Pay

What is the Employee History Data File?

• This .csv file contains employee data. The Variable Pay module requires this information to determine bonus/goal plan eligibility, employees basis and proration for each employee.
• The data is stored in live profile and can be made available to employee's and managers.
• Each customer can define which fields are important to the bonus calculation and what information should be imported and displayed.
• The file for employee history contains information which is used to generate prorated incentive pay-out calculations for each employee.
• Files are manually imported when dealing with nonEC instances, imported directly from Employee Central or setup for automated FTP Imports. See below for more information.

Note 

Only employees who are eligible for an incentive calculation should be included in the employee history. All employees must also have a record (either active or inactive) in the UDF.

• Each employee record corresponds to a date-effective time period.
• This is used to calculate a prorated pay-out for each bonus plans which employees are eligible for.

Manually Importing

The employee history file can be imported via Plan Setup> Manage Users> Import Employee History:

• When the employee history file is imported, there is an option to delete all existing records prior to importing the new file.
• Only select this option if a full import of all employees is required, else the imported employee records will be appended to the existing ones.
• If new/revised data is imported for a user who already exists a record in the history.

Existing records:
Employee A's records
Employee B's record 1
Employee D's records

Import records:
Employee C's records
Employee B's record 2
Employee D's records (the same as the existing records)

If option "Import file contains employee history records for all employees" is not selected, then only Employee B's record 1 will be deleted when import. The import result will be:
Employee A's records
Employee B's record 2
Employee C's records
Employee D's records

If option "Import file contains employee history records for all employees" is selected, then Employee B's record 1 and Employee A's records will be deleted. The import result will be:
Employee B's record 2
Employee C's records
Employee D's records

Note

It is strongly recommended a FULL file replacement be done each time, so this option should be selected.

Any employee history records which are edited within the UI editor will be deleted when a full file import is initiated.

Automated Import

Auto upload of employee history outlined below.

Official Marketing Name - Auto Upload of Employee History

• This automates the import of employee history records into the system without any manual interaction for upload.
• CS/PS can schedule a job for the customers to automatically pick the employee history file from a pre-defined FTP server, recurring frequency, encryption type etc.
• The job can then process the import file for Employee History records for the selected Variable Pay Program.
• Import success/failure emails are sent to the job owner and any additional recipients that are configured while setting up the job.

Configuration Type - Admin Opt-In

• Does not require any configuration change, and is free of charge
• This helps if you consider employee history records as sensitive information and prefer not to have a copy of that file available for manual edits/imports
• CS/PS can set up job in provisioning> Company> Quart> Job type = Employee History Import

Employee History Editor - Data Handling

Employee history data can be manually edited/changed within employee history editor:

The following steps and rules should be taken into consideration when managing employee data while using the editor.

1. To add a new employee record into the history, you must use the "Add New" option (or import them via the file as outlined in 2.2.1)
2. The history editor may be used to export and update by import the employee data.
   To update by import the employee data, the first column of the .CSV file MUST contain the #Emp History Id (^systemID), User Id (userId) and Delete Record (deleteRecord) columns followed by the columns you wanted to update.
3. When re-importing a record, the history editor is performing an UPDATE only and not a replace or add.
4. Prior to importing any edited data back into Variable Pay, the following columns must first be deleted:
   First Name
   Last Name
   Status
5. As a short cut, it is not required to re-import all columns every time something is being changed.
   The import will always require the #Emp History Id (^systemID) column. However, only additional columns you wish to import need to be included.
6. The "Select Locale" drop-down option defaults to the user's locale and controls the way dates/numbers are formatted within the exported history file.
   This option is not "Sticky" and will therefore need to be selected if needed.
   Data MUST be exported and re-imported using the SAME LOCALE to avoid any formatting issues
7. The "Character Encoding" drop-down option defaults to "Western European (Windows/ISO)".
   If you have characters which are not exporting correctly, use UTF8 or any appropriate Asian character set.

Note

Although in case of searching active users by first name/last name/username there will be recommendations, for inactive users the system will not display any suggestions. It is desgined as such to avoid inactive users popping up every time. Only when a full name is entered, than an inactive user can be searched. This is similar to how many applications handle inactive users.

Employee History Data Import File Format

Failing to ensure the employee history meets all the following criteria can cause a failure in employee import, cause update issue as well as causing data inconsistencies.

• Must prefix the header row with a ^.
• The first column within the file must be ^UserId.
• The startDate, endDate and varPayProgramName fields must be the first three fields within the background element and file. Otherwise calculations will not render correctly.

• The second column must contain the section type. This would be the name of the background element being used for the history.
• There should be NO currency symbols in front of ANY amount s in this file.
• No commas are allowed within amounts either.
• Ensure your eligibility file (Plan Setup> Manage Plan Details> Import/Export Legacy Eligibility Rules) match what is defined in your employee history. These fields are case sensitive.
• The import file for Employee History MUST match the column sequence which you have defined in the data-model.
• If you wish to hide a field within the history then this can be achieved within the data-model by updating the hidden="false" tag to hidden="true".

• Dates must be imported in US format MM/DD/YYYY for Variable Pay history. Therefore, to avoid issues set the locale of the Admin doing imports to US.
  Dates on reports WILL show in the format of the company locale. This can be defined within Provisioning> Company Settings.
• Ensure the "basis" field within the history file has no commas or currency symbols. Should there be commas etc then bonuses will not calculate. 

Assumptions About Record Sets

• The customer will only include one record per effective date range (startDate & endDate). For PeopleSoft customers this usually is identified by the greatest "effseq" number.
• The customer can generate true "end date" data for every record to reflect and communicate any assignment gaps.
• The customer will only include eligible records who are eligible for bonus pay-out.
• The customer will import a complete record-set per employee to remove the risk of overlaps/overwrites.
• The basis (eligible salary for bonus) must be labelled as "basis".
• All percentages should be imported in decimal format. For example, 10% = .10.

Additional Information

• The field list for employee history data is defined specifically for each customer within their data-model.
• Each customer will track their own specific historic fields which impacts an employee's overall bonus.
• The customer is responsible for identifying and maintaining these fields in the instance.
• SuccessFactors professional services or your implementation partners are responsible for configuring the data-model to match this data set.
• There are six fields for every record: UserID, varPayEmpHistData, startDate, endDate, varPayProgramName, basis.
• Variable Pay history information does NOT take EC effective date at summary level into consideration, just the program start/end date(s) to know which rows to pull in. below is an example.

Employee A had the following information within EC compInfo and through the history we are pulling in the field CMP Plan.

17/04/2019 shows "Yes" and from 21/09/2019 shows "No".

The dates we have defined in Plan Setup> Settings> Settings for the bonus start/end dates are as follows.

Within Employee Central Settings, we have the following.

Importing the history for this employee shows the CMP Plan field coming in as "Yes" which goes against the EC effective dates.

Changing the bonus end date to be 18/09/2019 will give you two records with two data sets with "Yes" and "No".

This is the designed behaviour of the product as 21/11/2019 to 16/04/2019 shows correctly as value "Yes" and then "No" starting 17/04/2019 to the bonus end date.

Data Changes After a Form Launch

It is possible to update employee history data while forms have been created. However, the following points should be taken into consideration.

• If a new employee history file is imported and the old history record is deleted. For example, a full file refresh.

1. All forms currently launched for this employee would need to be launched again.
2. The calculation of bonus pay-out needs to be re-run.

• If a new employee history file is imported with new data APPENDED to the existing data, forms already launched are not affected.
  However, a new form needs to be created for newly added employee's or added to existing forms.
• If a change is made to any of the following fields within the employee history, the bonus calculation will need to be re-run to update the already launched forms.

1. Proration date fields: Bonus Start Date, Bonus End Date
2. Eligibility fields: Business Goal or Bonus Plan Codes
3. Basis fields: Annual Target Amount or Currency

• If a change is made to other fields within the UI using the editor, already launched forms will be updated automatically with new data and no action is required.

The following is an example of a typical import. Attached to this KBA is an example history file.

Additional/Advanced Information

When is Variable Pay data reloaded? Why is planning information refreshed and reset to default values?

Assignment Level Editable information

• Within Variable Pay, there are two main types of data which is used.

1. Entry Level Data - This is information which is stored at entry or summary level of the worksheet. This will include data such as final pay-out and any additional custom fields you have created at entry level.
2. Assignment Level Data - All other information sorted for an employee which contributes to the entry/summary level information.
   This can include information regarding individual assignments, Business/Team/Individual Section information and down to the individual goal level detail.

• Entry level information is stored directly at data-base level and associated to the users while assignment level information is stored within the employee history.
• The expected behaviour is if there is an update to any employee history records, the underlying assignment level data will also be reloaded. This will in turn remove any associating planning data at assignment level.
• Therefore, for a program where there are no editable fields except at entry level, there will be no loss of planning data. However, if data is entered at assignment level and employee history is reloaded, then any
  manually entered data will be removed and reset back to default values. These would go back to the initial values viewed at form launch.

When Will Data Be Deleted/Reset to Default Values?

1. Entry Level Data - Planning information will be deleted if forms are deleted
2. Assignment Level Data - Planning information will be deleted if the employee's variable pay history is updated or reloaded.

Common scenarios

There are two common scenarios where data is entered at assignment level.

1. Planning information for assignment-based rating (ABR) programs.
2. Editable assignment level custom fields.

Reloading data and the employee history processor

For Employee Central integrated instances, companies can manually initiate an update to employee history data or schedule a job to run on a periodic basis. This can be run with a full or partial import.

1. Full refresh - All assignment level planning information will be removed.
2. Import changes records only - Only records of employees whose information has changed will be reloaded. Any employee with history records reloaded will have planning information removed.

Please note the process of comparison when using the history processor is as follows.

• If the import of employee history job is marked to "Import only changed records" the following behaviour is followed.
• The overall population is obtained by looking at all the users whose employee central data has been changed since the last successful processor job. This would be on the following areas.

1. jobInformation
2. compInformation
3. employmentInformation
4. jobRelation
5. personInfo

• After the list of employees is obtained, the processor will create a new history record (the specified named and mapped fields) according to the employee central history data in memory and compare to the existing record.
• If new data is the same as the existing data, no action is taken. However, is there is a difference all data for the employee record is reloaded.
• If other data does not affect the history, rows will NOT be updated.
• The job will provide the results of any affected users.

Summary

• For programs which only have a manual entries at entry level, there should be no impact if the employee history record is reloaded.
• For programs which have a manual entry at assignment level, administrators should be very careful of when the variable pay history is reloaded as it will REMOVE all existing planning data.

Check List

If you find the history processor is failing please check the following

• There are no duplicated vfld, ffld fields within the templates assigned backround element
• Ensure business rules are correctly setup within Plan Setup> Settings> Employee Central Settings. For example a rule setup pointing to NULL of a column value.
• Make sure all reserved fields are not being used for other custom columns within the background element. Please see 2730558 - Compensation & Variable Pay - Manage Business Configuration (BCUI)
• All reserved fields (KBA 2730558) are in the background element. These are mantory fields, especially record type for importing data.
• The selected background element is enabled. If this is not enabled and was disabled you may recieve a 900-001-6 error in "Edit Employee History". See 2739969 - Variable Pay - 900-001-6 Error while accessing " Edit Employee History"

sf, success factors, VRP, CMP, history, import, ECT, entry, values, assignment, level, fields, reset, default, bonus, start, end, date , KBA , sf varpay manage data , sf varpay employee history , LOD-SF-VRP , Variable Pay Programs , LOD-SF-VRP-HIS , History Data, History Processor , How To