Using The Employee Delta Export Add-In For Microsoft Excel: User Guide - PUBLIC Document Version: 2H 2021 - 2022-04-28
Using The Employee Delta Export Add-In For Microsoft Excel: User Guide - PUBLIC Document Version: 2H 2021 - 2022-04-28
Using The Employee Delta Export Add-In For Microsoft Excel: User Guide - PUBLIC Document Version: 2H 2021 - 2022-04-28
Learn about changes to the documentation for Employee Delta Export Add-In for Microsoft Excel in recent releases.
2H 2021
Changed We updated the topic with more informa Adding New Columns from the Database
tion on full:// path notation. [page 59]
Changed We removed the Adding Sortable Col Result Sheets [page 29]
umns in the Result Sheets topic.
1H 2021
Added We added the limitation related to the Behaviors Caused by the Client Applica
country/region-specific segments. tion [page 11]
Changed We removed the user and password infor Systems Sheet [page 41]
mation from the worksheets. It is now
added in a popup.
What you need to know before you start using the Employee Delta Export Add-In for Microsoft Excel.
The application described in this document isn’t subject to your license agreement or any other agreement with
SAP SuccessFactors.
SAP SuccessFactors has no obligation to pursue any course of business outlined in this document or to develop or
release any functionality mentioned in this document. This document and SAP SuccessFactors' strategy and
possible future developments are subject to change and may be changed by SAP SuccessFactors at any time for
any reason without notice. This document is provided without a warranty of any kind, either express or implied,
including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or
noninfringement. SAP SuccessFactors assumes no responsibility for errors or omissions in this document.
Note
The Employee Delta Export Add-In for Microsoft Excel is on maintenance mode only. No development of new
features is planned.
Employee Delta Export for Microsoft Excel is an Excel-based application that retrieves employee master data from
Employee Central, which can then be used for payroll runs in a subsequent system.
The Employee Delta Export provides new employee master data and employee master data that was changed
compared to the end time and date of the previous run from Employee Central. The export minimizes the effort of
transferring the changed employee data to the payroll system. It considers changes on all time slices of effective-
dated employee data. In other words, it considers future-dated and retroactive changes of employee data. It
indicates data deletions in certain cases, for example, if a pay component was deleted.
The Employee Delta Export application consists of an add-in for Microsoft Excel and two workbooks. The
workbooks provide the layout of the data being retrieved and some configuration data. The configuration data
allows for consultants and administrators to configure the data retrieval process without actually having to
program.
Note
If you want to use Employee Delta Export for Microsoft Excel, you need advanced knowledge of working with
Microsoft Excel and XML.
Feature Overview of the Employee Delta Export for Microsoft Excel [page 6]
Take a look at the main functions of Employee Delta Export for Microsoft Excel.
Related Information
Take a look at the main functions of Employee Delta Export for Microsoft Excel.
The most important features provided by the Employee Delta Export Add-In for Microsoft Excel are:
● Filter employees who have been changed, hired, or re-hired since the begin of the evaluation period
● Show before image and current image of changed data
This document is intended for consultants, partners, and customers who would like to learn more about the
Employee Delta Export for Microsoft Excel, its technical background, and how to use it.
What needs to be set up before you can start using the Employee Delta Export Add-In for Microsoft Excel to extract
changes made to employee master data inEmployee Central.
Technical Prerequisites for Using the Employee Delta Export for Microsoft Excel [page 8]
Your system landscape needs to fulfill some prerequisites if you want to use Employee Delta Export for
Microsoft Excel.
Special Handling for the Employee Delta Export for Microsoft Excel [page 9]
Employee Delta Export for Microsoft Excel has some specific behaviors that are caused either by the
Compound Employee API or by the client application.
Security and Session Management in the Employee Delta Export for Microsoft Excel [page 12]
The Employee Delta Export for Microsoft Excel requires logon, logout, session management, and role-
based-permissions.
Application Components of the Employee Delta Export for Microsoft Excel [page 14]
The Employee Delta Export for Microsoft Excel consists of an Excel add-in and one or more reporting
workbooks.
Installing the Employee Delta Export Add-In for Microsoft Excel [page 15]
Install the Employee Delta Export Add-In for Microsoft Excel on your local computer.
Uninstalling the Employee Delta Export Add-In for Microsoft Excel [page 16]
Uninstall the Employee Delta Export Add-In for Microsoft Excel from your local computer if you no longer
need it.
Your system landscape needs to fulfill some prerequisites if you want to use Employee Delta Export for Microsoft
Excel.
Related Information
Employee Delta Export for Microsoft Excel has some specific behaviors that are caused either by the Compound
Employee API or by the client application.
Consider these behaviors if you use the Employee Delta Export for Microsoft Excel.
● Role-based permissions aren’t supported. This means you need to grant the permission Employee Central
HRIS SOAP API to the user who uses the Employee Delta Export. This allows the user to retrieve all kinds of
data that is accessible using SOAP APIs.
● The Employee Delta Export can only handle the following entities:
○ Person
○ Personal Information
○ Personal Information Global
○ Address Information
○ Employment Information
○ Job Information
○ Compensation Information
○ Pay Compensation Recurring
○ Pay Compensation Non-Recurring
○ PaymentInformationV3
○ National ID Card
○ Email
○ Phone
○ Person Relation
○ Job Relation
○ Global Assignment Information
The following segments aren’t included in the standard query. You can request to have these segments
included as result sheets.
○ Deduction Recurring
○ One Time Deduction
○ Alternative Cost Distribution
○ Personal Documents Information
● The Employee Delta Export doesn't consider an employee changed when other entities than the above have
changed (for example, foundation objects used for lookup purposes)
● By default, the workbook shows all future time slices of an entity that have been changed, meaning changes
that become effective after the payroll period can't be excluded. However, if you use Period-based Delta, you
can determine the start and end date of the validity period for which you want time slices to be considered.
● Since the Employee Delta Export is primarily based on the CompoundEmployee API, it inherits most of the
limitations of the CompoundEmployee API that are:
○ Event and event reason on Compensation Information isn’t supported
○ Only filter parameters supported by the CompoundEmployee API are passed on to the API server. Other
filters are applied locally in Microsoft Excel. This may lead to unexpected high data volumes being retrieved
from the API server.
○ Picklists and Foundation Objects assigned to fields returned by the API need to have external codes.
Otherwise, no value is returned for those fields.
○ Severe data inconsistencies (for example time slice mismatches) may prevent employees from being
shown. They appear on the Errors sheet instead.
When using the Employee Delta Export Add-In for Microsoft Excel, consider these behaviors caused by the client
system.
● For performance reasons, the Employee Delta Export shouldn’t be used to process more than 1000 employees.
Depending on the data volume of the processed employees, the maximum number of processed employees
can be substantially smaller. In such cases, the data needs to be broken down into smaller parts that can be
handled by Microsoft Excel.
● Initial load scenarios that extract the whole change history for every employee of a target population aren’t
supported. A delta extraction must have a report start date.
● It's not possible to specify country/region-specific segments to be extracted using the Employee Delta Export
Add-In.
● No localization is provided for:
○ Workbook static content (text, messages)
○ Employee data (descriptions)
○ Foundation data (for example, pay component names)
○ Picklist entries (for example, married, single, divorced)
● When you plan to divide your overall employee population into different pieces processed by different
processors using different filter criteria, this needs to be planned thoroughly to prevent loss of information
when employees transfer from one subpopulation to another.
● You can’t use lists of values for filter parameters in arbitrary combinations.
● Don't hide any rows. Data in hidden rows might interfere with new data being written to the Microsoft Excel
sheets.
● Sorting must be done locally in Microsoft Excel.
● Single sign-on isn’t supported.
● The Employee Delta Export makes it possible to manually extract data from a system. Even though it’s possible
to have an automated process read data from the processed workbook, the Employee Delta Export doesn't
provide a functionality to automatically start the export.
● Contingent Worker employments aren’t supported by Employee Delta Export. Since an employee that is a
contingent worker has only a contingent worker employment, that employee isn’t considered by the Employee
Delta Export as a whole.
The Employee Delta Export for Microsoft Excel requires logon, logout, session management, and role-based-
permissions.
The Employee Delta Export for Microsoft Excel calls the CompoundEmployee API to extract data from the system.
When you trigger the extraction, a logon dialog pops up asking for user and password for the selected system.
Authentication is established through the logon operation using user and password.
A successful logon returns a session ID as an HTTP cookie. This cookie is passed back to all subsequent HTTP
requests that invoke API operations in order to authenticate.
When all required API calls have been executed, a logout operation is sent, which closes the session. The session
will also time out after 10 minutes of inactivity, for example, in case of an error that isn’t properly handled.
Note
Restricting User Account for API Calls to Certain IP Addresses [page 12]
Restrict a user account used for API access – including the API access used by Employee Delta Export for
Microsoft Excel – to certain IP addresses.
Setting Role-Based Permissions for the Employee Delta Export Add-In for Microsoft Excel [page 13]
Set the role-based permissions required to use Employee Delta Export for Microsoft Excel.
Restrict a user account used for API access – including the API access used by Employee Delta Export for Microsoft
Excel – to certain IP addresses.
Procedure
1. Go to the Admin Center and choose the Password & Login Policy Settings admin tool
2. Choose the link Set API login exceptions....
3. Choose Add.
4. Enter the following data:
○ Username: The user account used for API access
○ Maximum password age (days): 0
○ IP address restrictions: Your IP addresses
Set the role-based permissions required to use Employee Delta Export for Microsoft Excel.
Context
Grant your users of Employee Delta Export for Microsoft Excel the permissions required for using the
CompoundEmployee API and for accessing the Employee Delta Export UI.
Procedure
1. Set the permissions required to extract data from the system using the CompoundEmployee API.
Category Permission
Under User Permissions, select the General User Permission Select the SFAPI User Login permission.
category.
Under Administrator Permissions, select the Employee Select the following permissions:
Central API category. ○ Employee Central HRIS SOAP API
○ Employee Central Foundation OData API (read-only)
Under Administrator Permissions, select the Manage Select the Allow Admin to Access OData API through Basic
Integration Tools category. Authentication permission.
Under Administrator Permissions, select the Metadata Select the Admin Access to MDF OData API permission.
Framework category.
Under User Permissions, select the Miscellaneous Search for the Object Picklist and select View Current.
Permissions category.
Note
This is optional and is only needed in cases where the
MDF Object Picklist is set to Secured in the object defini-
tion.
2. Set the permission required to access the Employee Delta Export UI.
Category Permission
Under Administrator Permissions, select either the Manage Select the Manage Employee Delta Export Templates permis
Dashboards / Reports or the Manage User category. sion.
If the user logs out and then logs in again, they can now find
Employee Delta Export link in Admin Center, using the Admin
Tools search field.
The Employee Delta Export for Microsoft Excel consists of an Excel add-in and one or more reporting workbooks.
The Excel add-in contains the logic to retrieve the data from the backend and perform delta calculation. The add-in
adds functions to the Excel ribbon that allow you to fill one of the reporting workbooks with data fetched from the
backend.
You can have an arbitrary number of reporting workbooks. The workbook provides the layout for the data to be
shown plus configuration information used by the add-in.
On the Employee Delta Export UI you can find the Microsoft Excel add-in installer, the sample workbooks, and this
user guide for download.
Find the Employee Delta Export UI in the Admin Tools, under Employee Files or Reporting.
Note
You need the Manage Employee Delta Export Templates permission to access the Employee Delta Export UI.
The Employee Delta Export UI has a list of files you can download:
● Microsoft Excel Add-In Installer (CompEmpDeltaAddIn.xlsm): Use this to install the add-in.
● Multi-Sheet Workbook (CompEmpDelta_multiSheet.xlsx): Contains separate worksheets for all Employee
Central entities.
● Single-Sheet Workbook (CompEmpDelta_singleSheet.xlsx): A sample workbook showing all Employee Central
entities on one single worksheet.
● User Guide (Employee Delta Excel.pdf): The current Employee Central Compound Employee API - Employee
Delta Export Add-in for Microsoft Excel guide.
Each file has its own version consisting of three numbers. The first number indicates the SAP SuccessFactors build
for which the file is provided. Only the files relevant to your SAP SuccessFactors release are listed. The second
number represents the patch version of the file. The add-in performs a version check each time you retrieve data
from the Microsoft Excel and give a warning if the add-in or a workbook is outdated. The third number indicates the
revision of the file and represents minor changes. You are not forced to update files that have an outdated revision
number.
The Employee Delta Export UI ensures that you are using the newest version of the Employee Delta Export Add-In
for Microsoft Excel.
Whenever you execute a query request by selecting Get Data, a version check is performed. If there is a version of
the add-in with a higher release number or patch version than the file you have installed, you will get this warning:
Your version is outdated and may cause problems. We strongly recommend you download the latest version of the
Employee Delta Export Add-in from Admin Tools..
If only the revision number of your installed add-in differs from that of the newest version available, you get a
different warning: A new version of the Employee Delta Export Add-in is available. Please download it from Admin
Tools to benefit from the latest features. You can continue working in the older version and download a new version
later, if desired.
If you select the Do not show this message again checkbox, the warning won't show up again as long as the revision
number of the add-in file in the Employee Delta Export UI isn't changed. Revision changes are minor changes that
won't influence existing features. Therefore, updating is optional.
Install the Employee Delta Export Add-In for Microsoft Excel on your local computer.
Procedure
1. Go to the Admin Center and choose the Employee Delta Export admin tool.
2. Download Excel Add-In Installer (CompEmpDeltaAddIn.xlsm).
3. After downloading the installer, open it and follow the instructions shown in the pop-up.
To avoid security issues, ensure that macro execution is enabled in Microsoft Excel and that the workbook is
made a trusted document. The software is digitally signed by SAP to ensure corporate compliance.
Uninstall the Employee Delta Export Add-In for Microsoft Excel from your local computer if you no longer need it.
Procedure
How to use the Employee Delta Export Add-In for Microsoft Excel.
First Steps to Using the Employee Delta Export for Microsoft Excel [page 17]
Take the first steps to start retrieving data using the Employee Delta Export.
Architecture Concept of the Employee Delta Export for Microsoft Excel [page 19]
More about the architecture of the Employee Delta Export Add-In for Microsoft Excel.
Workbooks for Employee Delta Export for Microsoft Excel [page 28]
The Employee Delta Export requires specific Microsoft Excel workbooks to fill in the data, which you can
download from the Employee Delta Export UI.
Take the first steps to start retrieving data using the Employee Delta Export.
Procedure
8. Go to the SuccessFactors tab on the Excel ribbon and choose Get Data. This calls the CompoundEmployee API
in the SAP SuccessFactors system to return all changes that happened between 01.01.2014 and the current
time.
9. Once the data is read, the view switches to the Summary sheet showing you the selection parameters and the
number of records found.
Find the API endpoint to be used in the Employee Delta Export for Microsoft Excel. It depends on where your SAP
SuccessFactors instance is located.
The API endpoint can be in one of several data centers. The endpoints by data center are listed below. For the
Employee Delta Export Add-In for Microsoft Excel, use the base URL part from the SFAPI endpoint URL. For
example: https://api2.successfactors.eu
Carry out a first test run of the Employee Delta Export for Microsoft Excel.
Procedure
1. Check the data sheets in the Employee Delta Export workbook for new content.
2. In the Employee Central system, change the address of an employee (for example, change the house number).
3. Go back to the Employee Delta Export workbook. On the SuccessFactors tab, select Get Data.
4. Check the data sheet for changes and you will see exactly the one address change you added before.
More about the architecture of the Employee Delta Export Add-In for Microsoft Excel.
Multiple components are involved in employee delta reporting using the Employee Delta Export Add-In for
Microsoft Excel.
Data is extracted by the Employee Delta Export Add-in for Microsoft Excel from Employee Central in three main
steps.
Note
The Employee Delta Export is based on the Compound Employee API, which is a SOAP API. This means that
the result returned by the API is in XML format. This is the reason why many configurations in the reporting
workbooks are based on XPath syntax, since XPath is the perfect language to access elements in an XML
document.
1. The Employee Delta Export application calls the CompoundEmployee API in delta mode to retrieve all
creations, changes, and deletions of entities that happened since the start of the evaluation period that is
typically the time of the previous extraction.
Additional selection parameters going into the WHERE clause of the API call can be specified on the Selection
worksheet. In case the first call in delta mode didn’t retrieve all records matching the selection criteria,
subsequent queryMore calls are issued to retrieve the remaining data.
Depending on the version of the Employee Delta Export, subsequent calls to the CompoundEmployee API are
performed. For the persons returned by the call in delta mode the API is called again in the so-called snapshot
mode. This mode returns the status of all entities for these persons at the time of the previous extraction. After
that, a third API call in full transmission mode is performed returning the current status of the persons in
question.
The raw data returned by all API calls is stored in the workbook on hidden sheets.
2. The client-side filters defined on the Config sheet are applied to the result XML returned from the system in
order to exclude more employees from the result. Both filters are applied to the full data of each employee
retrieved from the system including all time slices (filters aren’t applied to the delta result).
3. The add-in post-processes the data and calculates the changes compared to the previous extraction on field
level. Only changed fields are shown on the result sheets of the workbook unless it’s enforced to show the
current field values.
You can see the results the Employee Delta Export returns in more detail to set up business processes to post-
process the retrieved content.
The Employee Delta Export returns all changes that have been updated in the system or modified by APIs during
the evaluation period of the report. The start of the evaluation period is as you specify in the fields New Report Start
Date [UTC] and New Report Start Time [UTC] on the Selection sheet. The end of the evaluation period is the point in
time when the report is executed. The report returns all changes within this period no matter when they become
effective.
First of all, you need to distinguish between data that is effective dated and data that isn’t effective dated in
Employee Central. Both types of data appear in the Microsoft Excel reporting workbooks. For example, personal
information and job information are effective dated, whereas national ID card information and spot bonus
information aren't.
This type of information is easy to understand. Creations, changes, and deletions of such data can't be scheduled
and become effective immediately for the whole time bar. Spot bonus (pay component non-recurring) is somewhat
of an exception, because this is information that applies for one particular date only.
Effective-Dated Information
For effective-dated information, you need to distinguish between the point in time when a change is made in the
system and the point in time when this change becomes effective. Both points in time are independent of each
other. A change made today can become effective today, in the future, or in the past. Changes that become
effective in the past are called retroactive changes. If a change becomes effective in the past, it may no longer be
effective today since the period of effectiveness could also end in the past. The time period during which a set of
data is effective is called a time slice. The date when a change becomes effective is called the start date (the
beginning of the time slice). The date when it ends being effective is called the end date (the end of the time slice).
The Employee Delta Export returns data that has been changed during the evaluation period of the report no
matter when these changes become effective. This is important to know because in some cases you get
information that you're not interested in at the point in time you get it. For example, if the promotion of an employee
is made today, but becomes effective at the start of next year, you’ll see this change in the next Microsoft Excel
report run after the change was made. You need to take up this issue organizationally, for example, by shelving this
change.
Retroactive Change
From a business perspective, changes shown in the report can result from the following actions performed in the
system:
● Hire of an employee
● Insertion of a new record for non effective-dated data
● Change of data of a non effective-dated entity
● Change of the key of an entity
● Insertion of a new time slice for effective-dated data
● Change of data in the history of effective-dated data using Make Correction
● Change of start date of effective-dated data in the history using Make Correction
● Deletion of a non effective-dated record (for example, personal information)
● Deletion of a record in the history
● Deletion of a record starting from a particular date (for example, home address)
● Deletion of a record in the course of changing the superordinate record
Related Information
Here is more information about how delta calculation in the Employee Delta Export Add-In works when a new
employee is hired.
A hire can be a new hire or a rehire. Both are shown in the same way so that the complete data of all entities and all
time slices are shown in the report. In this case, the status columns have the value New. The [Old] columns stay
empty.
Note
The highlighting shown in the example can differ from the highlighting in the version of the add-in you've
installed.
Here is more information about how delta calculation in the Employee Delta Export Add-In works for data that's not
effective-dated.
New records of non-effective-dated data (for example, national ID card) are shown as new rows in the Microsoft
Excel report with value NewSeg in the status column. The [Old] columns stay empty.
A simple change of non-effective-dated data is shown as new rows in the Microsoft Excel report with the value
Changed in the status column. The [New] columns show the latest values whereas the [Old] columns show the
values valid before the change happened.
When you delete a non-effective-dated record in the system, this is shown in the Microsoft Excel report as new rows
with the value Deleted in the status column. The [Old] columns don't change. The [New] columns contain the
pseudo value deleted. Row 8 in the following example shows such a case.
Note
The highlighting shown in the examples can differ from the highlighting in the version of the add-in you've
installed.
Here is more information about how delta calculation in the Employee Delta Export Add-In works for data that's
effective-dated.
If you insert a new time slice in the system using the Insert Record function, this is shown in the Microsoft Excel
report as a separate row with the value Changed in the status column. The [Old] columns show the values that were
valid for the validity period before the new time slice was inserted.
This kind of change is shown in the Microsoft Excel report just like the insertion of a new time slice. The [Old]
columns show the values that were valid before the correction was performed. Row 6 of the example shows such a
case.
This is the most complex scenario. If the start date of a time slice is shifted to the future or the past, this is shown in
the Microsoft Excel report as a separate row. The row shows the differences between the old and the new values for
the period that is affected by the shift.
In the graphics, the start date of time slice 2 is changed from January 8, 2014 to January 7, 2014. As a result, the
Microsoft Excel report shows a new row with the start date January 7, 2014 and the end date July 31, 2014 (denoted
as Delta in the figure). This row shows the values of time slice 2 in the [New] columns and the values of time slice 1
in the [Old] columns.
In cases where the start date of the first time slice is moved to the future, the Microsoft Excel report shows a row
denoting a deletion of the delta period.
When you delete an effective-dated record in the system, this is shown in the Microsoft Excel report as new rows
with the value Deleted in the status column. The [Old] columns don't change. The [New] columns contain the
pseudo value deleted.
Assume that you choose Edit in the Address entity and delete, for example, the vacation address after entering the
effective start date. In the Microsoft Excel report, this is shown as a new address row with value Deleted in the
status column. The [Old] columns show the values just before the deletion. The [New] columns contain the pseudo
value deleted.
A typical example is that you create a new compensation time slice with the start date X. In the course of that, you
delete a pay component from the list. In the Microsoft Excel report, this is shown as a pay component row with
value Deleted in the status column. The [Old] columns show the values just before the deletion. The [New] columns
contain the pseudo value deleted. Row 9 in the example shows such a deleted pay component.
Note
The highlighting shown in the examples can differ from the highlighting in the version of the add-in you've
installed.
Here is more information about how delta calculation in the Employee Delta Export Add-In works if the key of an
entity is changed.
If a key field of a non-effective-dated entity or effective-dated entity is changed in the system (for example, the
country/region of a national ID card), the old record with the old key is deleted and a new record with the new key is
created. The Microsoft Excel report shows a row with status Deleted for the first action and a row with status
NewSeg for the second action. Rows 7 and 8 of the example show such a case.
Note
The highlighting shown in the example can differ from the highlighting in the version of the add-in you've
installed.
The Employee Delta Export requires specific Microsoft Excel workbooks to fill in the data, which you can download
from the Employee Delta Export UI.
An Employee Delta Export workbook has a specific structure and contains configuration information that controls
the behavior of the add-in. We provide two different workbook templates you can use as a starting point for
customization:
● CompEmpDelta_multiSheet.xlsx
Contains one sheet for each entity that is supported by the application. Each sheet shows new and changed
data in combination.
● CompEmpDelta_singleSheet.xlsx
Contains three data sheets:
○ New employees (hired, rehired, or transferred employees)
○ Changed employee data
○ Leaving employees
Employee Delta Export for Microsoft Excel comes with multiple worksheets, such as result, selection, or summary
sheets.
Personal Info Sheet with Changes and New Data of Multiple Employees
The result sheets of Employee Delta Export for Microsoft Excel are populated by the data retrieved from the
backend by the Compound Employee API.
Employee Delta Export for Microsoft Excel provides two sample reporting workbooks,
CompEmpDelta_singleSheet.xlsx and CompEmpDelta_multiSheet.xlsx, which have different sets of result sheets. In
both cases the result sheets have a common layout in the first 4 columns:
Column 1: Status reflecting the reason why the row appears in the workbook
The result sheets have two columns for data fields that may change. The column with suffix [New] contains the
current value and the columns with suffix [Old] contains the value the field had at the start of the evaluation period.
Note, however, that if the data field belongs to an effective-dated entity the [Old] value is subject to the start and
end date in the same row.
This CompEmpDelta_singleSheet.xlsx workbook has different result sheets for hires, changes, and leavers. On
each of the result sheets you find the data of all Employee Central entities supported by the Employee Delta Export.
Sheet Description
Hires The Hires sheet always shows the complete set of data for the
hired or rehired employee. All time slices are shown, including
time slices in the future.
Changes The Changes sheet shows employees whose data have been
changed in the system during the evaluation period. Only time
slices that have been changed are shown in this case.
● Changed
● NewSeg
Indicates that the entity record was created during the evalua
tion period. For example, a new national ID card entry was
added or a new pay compensation entry was added. NewSeg is
not used, however, if a new time slice was added to an existing
entry, like personal information. This case is portrayed as a
change instead.
● Deleted
Leavers The Leavers sheet shows only those employees for whom a ter
mination event has been added during the evaluation period.
Only limited data is shown for these employees.
Each worksheet contains the data of all Employee Central entities related to the employee. Each entity is shown in a
separate row. For effective-dated entities, each time slice is shown in a separate row. Rows belonging to the same
employee are grouped by color. The column Start Date in the column section for a particular effective-dated entity
shows the start date of the time slice.
The CompEmpDelta_multiSheet.xlsx workbook contains separate result worksheets for all Employee Central
entities supported by the Employee Delta Export.
The Employee Delta Export for Microsoft Excel supports the following entities:
● Personal Information
● National ID Information
● Address Information
● Employment Details
● Job Information
● Pay Compensation Recurring
● Pay Compensation Non-Recurring (Spot Bonus)
● Payment Information
● Deduction Recurring
● One Time Deduction
● Alternative Cost Distribution
● Personal Documents Information
Each sheet contains data for hires, rehires, changes, and leaves. For effective-dated entities each time slice is
shown in a separate row. Rows belonging to the same employee are grouped by color.
The different events are distinguished by the status column. The status column contains one of the values below:
NewSeg A new entity record was created during the evaluation period.
For example, a new national ID card entry was added or a new
pay compensation entry was added. NewSeg is not used, how
ever, if a new time slice was added to an existing entry like for
example personal information. This case is denoted as a
change instead.
Deleted The time slice was deleted during the evaluation period
Transfer The employee has entered the population specified by the se
lection criteria during the evaluation period. This means that
the employee didn’t fulfill the selection criteria at the start of
the evaluation period. In this case, the full set of data including
all time slices is.
The Employee Delta Export Add-In for Microsoft Excel uses highlighting in the result sheet to make it easier for you
to see what has changed.
If changes on the result sheets populated by Employee Delta Export are on the field level, one or more single cells
are highlighted. If changes affect the whole record on a result sheet, the status cell is highlighted.
In this example, the whole national ID record was deleted, which you can see here because the status cell is
highlighted. In order to identify the deleted record, the business key stays unchanged and fields that don't belong
to the business key are shown as ***deleted***.
The following example shows another deletion, however, this time, only one value of the record was deleted. The
changed value is highlighted.
Employee Delta Export for Microsoft Excel has a Selection sheet, which contains parameters used to filter data.
Related Information
The Selection sheet of Employee Delta Export for Microsoft Excel contains parameters you can use to filter data.
New Report Start Date/Time [UTC] The start date/time of the evaluation period. All creations,
changes, and deletions of entities applied in the backend since
this point in time will go into the result sheets. Once the data
has been retrieved from the backend completely, these two
fields are automatically updated with the server time when you
started the recent extraction. Unless you change these, this
date/time is used for the next extraction run.
Last Report Start Date/Time [UTC] This is the start date/time of the previous extraction run. It is
automatically updated after the extraction is performed.
Last Report End Date/Time [UTC] This is the end date/time of the previous extraction. It is in fact
the date/time when you pressed the Get Data button the last
time (in UTC time zone). It is typically identical with the New
Report Start Date/Time mentioned above.
Period Start Date Marks the start of the validity period for which data is consid
ered.
Period End Date Marks the end of the validity period for which data is consid
ered.
First Run in Period Indicates whether this is the first report run in that respective
period.
Example:
Division ABC
Division ABC
Department BCD
Here's an overview of how the filter parameters work that are provided on the Selection sheet of the Employee
Delta Export for Microsoft Excel.
● Filter parameters that are passed through to the CompoundEmployee API call.
● Filter parameters that are applied during post-processing in Microsoft Excel locally.
To understand the result of the report, you need to understand how the filtering works for both cases.
There is a limited set of filter parameters provided by the CompoundEmployee API. These are:
● BUSINESS_UNIT
● COMPANY_TERRITORY_CODE
● COMPANY
● DEPARTMENT
● DIVISION
● EMPLOYEE_CLASS
● LOCATION
● JOB_CODE
● PAY_GROUP
● PERSON_ID
● PERSON_ID_EXTERNAL
● 43c88e
For these parameters you can either specify a single value or a comma-separated list of values on the Selection
sheet. A single values results in the WHERE <field> = '<value>' condition passed to the API. A list results in a
WHERE <field> IN ('value1', 'value2', …) to be passed to the API.
If you specify values for multiple parameters on the Selection sheet, the filter conditions are logically ANDed in the
API call.
Note
Selection in the CompoundEmployee API works as follows: An employee counts as selected if each sub-
condition is met by at least one of the segments. This may be unexpected since the sub-conditions don't need
to be matched in the same segment.
Example
● Department: abc
● Division: xyz
Both fields are contained in the Job Information segment. These conditions are met by an employee who has a
single job info time slice that matches both conditions but also by an employee who has two job time slices
where one meets the department condition and the other meets the division condition.
Filter parameters belonging to this category have an Microsoft Excel name along this pattern EC_Filter_<parameter
name>, for example: EC_Filter_Company.
Filter parameters belonging to this category have an Microsoft Excel name matching the pattern
EC_FilterAtClient_<parameter name>, for example, EC_FilterAtClient_CostCenter.
Filter expressions in section Additional Filters (ORed) are applied to the employee who passed the previous checks.
An employee meets the set of conditions in this section if any of the conditions are met.
The filter expressions in both Additional Filter sections may be complex XPath expressions containing multiple filter
parameters. This allows for filters that check complex conditions on the same segment and so overcome the
restriction mentioned above.
Note
There is a limitation for this category of filter parameters: you can use a comma-separated value list only with
one parameter of a complex condition due to complexity reasons. An error will be raised if you ignore this
limitation.
Example 1
You specify the following filter values:
● Department: abc
● Cost Center: xyz
This filters employees who have department abc in one job segment and cost center xyz in the same or a different
job segment.
Example 2
You specify the following filter values:
● Department: abc
● Cost Center: xyz, uvw
This filters employees who have department abc in one job segment and cost center xyz or uvw in the same or a
different job segment.
Example 3
You specify the following filter values:
● Department: abc,def
● Cost Center: xyz, uvw
This filters employees who have department abc or def in one job segment and cost center xyz or uvw in the same
or a different job segment.
Example 4
You specify the following filter values, where Region is a custom_string1 of job info and the Microsoft Excel name for
the filter parameter in the Selection sheet is EC_FilterAtClient_Region.
● Region: abc
● Cost Center: xyz, uvw
● Additional filter (ANDed)://job_information[cost_center='%EC_FilterAtClient_CostCenter%']
This filters employees who have region abc in one job segment and cost center xyz or uvw in the same or a different
job segment.
Example 5
You specify the following filter values where Region is a custom_string1 of job information and the Microsoft Excel
name for the filter parameter in the Selection sheet is EC_FilterAtClient_Region.
● Region: abc
● Cost Center: xyz, uvw
● Additional filter (ANDed)://job_information[cost_center='%EC_FilterAtClient_CostCenter%' AND
custom_string1='%EC_FilterAtClient_Region%']
This filters employees who have region abc in one job segment and cost center xyz or uvw in the job segment.
Example 6
You specify the following filter values, where Region is a custom_string1 of job information and the Microsoft Excel
name for the filter parameter in the Selection sheet is EC_FilterAtClient_Region.
● Region: abc,def
● Cost Center: xyz,uvw
● Additional filter (ANDed)://job_information[cost_center='%EC_FilterAtClient_CostCenter%' AND
custom_string1='%EC_FilterAtClient_Region%']
This combination of filter and filter values is invalid since both parameters in the filter expression are multi-valued.
Example 7
You specify the following filter values, where Region is a custom_string1 of job info and the Microsoft Excel name for
the filter parameter in the Selection sheet is EC_FilterAtClient_Region.
● Region: abc
● Cost Center: xyz
● Additional filter (ORed): //job_information[cost_center='%EC_FilterAtClient_CostCenter%']
● Additional filter (ORed): //job_information[custom_string1='%EC_FilterAtClient_Region%']
This filters employees who have a job info segment with region abc or a job segment with cost center xyz or both.
Related Information
You can use period-based delta on the Selection and Summary sheets to restrict reporting to those changes to data
that are relevant for a given evaluation period, such as the time period to be considered in a payroll run.
Period-based delta within the Employee Delta Export for Microsoft Excel considers the following kinds of changes:
● Changes to effective-dated entities that are valid in the past, or whose validity overlaps with the given period
and happened after last synchronization.
● Changes on /creation of effective-dated entities in the past and where the start date falls into the given period.
● Changes on non-effective-dated entities happened after last synchronization.
The following fields show period-based delta information on the Selection and Summary sheets:
Note
Leave all three fields empty to run the Employee Delta Export without period-based delta.
A typical use case for period-based delta is when you are using the Employee Delta Export to prepare employee
data for an upcoming payroll run, in which case you would use Period Start Date and Period End Date to mark the
relevant start and end dates of the payroll run in question.
The payroll run is scheduled for June 25 and the data to be considered for this run is all data effective between June
1 and June 30.
On June 20, take a snap shot of the data in the Employee Central system that you want to update in the payroll
system. In this example, the last snapshot was taken on May 20 at 9:30:40 UTC. Enter the following data on the
Selection sheet:
You execute this run on June 20, 2015 at 09:40:50 UTC and you want to perform a run for a second update of data
in the payroll system for the same period. Enter the following data on the Selection sheet:
You can use filter parameters on the Selection sheet to define effective period selection, thus selecting employees
that fulfill certain conditions in a specific time frame.
The parameters you define on the Selection sheet of the Employee Delta Export for Microsoft Excel must apply to
Job Information or Compensation Information. The time frame is specified by the data entered in the selection
fields Select From Date and Select To Date on the Selection sheet. By using both selection fields, you specify a
period in time with a beginning and an ending. If you only use one selection field, you specify an open time period
with either a fixed start date or a fixed end date.
Example
Without effective period selection, you can only select employees that have been changed since the given New
Report Start Date and that have worked, are currently working, or will be working at Company A.
Note
For the sake of simplicity, this example assumes that all employees have been changed since the New Report
Start Date.
Using effective period selection, you can limit the employees returned in the response by their jobs.
Query Response
Select all employees who worked at Company A in 2015 No employees are returned
Select all employees who worked at Company A in 2016 All employees are returned
Select all employees who worked at Company A between Feb Returns Employee 1 and Employee 2
ruary 1 and April 1, 2016
Select all employees who have worked at Company A since Returns Employee 2 and Employee 3
June 1, 2016
The Summary sheets of Employee Delta Export for Microsoft Excel give a summary of the last extraction run.
The Employee Delta Export for Microsoft Excel has a Systems sheet, which contains all the systems to which you
can connect.
The Employee Delta Export Add-In for Microsoft Excel connects to an SAP SuccessFactors system using HTTPS
and retrieves data by calling the Compound Employee API and other APIs. You may connect to different systems,
for example, a test system and production system by choosing the desired system in the Choose System field on
the Selection sheet.
The systems in the dropdown list are specified on the Systems sheet, which is typically hidden. Store your favorite
systems on this sheet. The columns Name, URL, and Company are mandatory. Enter your user and password in a
pop-up once you have selected Get Data.
The Config sheet of the Employee Delta Export for Microsoft Excel contains configuration parameters that control
how the extraction is performed and how the results are displayed.
Some sections of the Config worksheet are locked to prevent unintended changes. If you want to change these
sections anyway, you must unlock the sheet on the Review tab.
Some of the parameters are Microsoft Excel tables. Extending the tables must be done carefully. Make sure you
don't enter data outside the table range. Otherwise, data may not be considered during processing.
Here's a list of the configuration parameters and information about how you use them.
Configuration Parameters
Parameter Description
Hire/Rehire Conditions This field contains an XPath expression that is applied to the
result of the Compound Employee API call in order to figure
out whether an employee is rehired. This condition typically
checks whether the event has changed in a certain way. If an
employee is recognized as rehired, the full set of data is shown
for this employee - not just the changed data.
File Name Pattern This cell contains a formula that calculates the file name under
which the workbook is saved when you use the Save Copy but
ton on the SuccessFactors tab on the Microsoft Excel ribbon.
You may include any of the selection parameters in the file
name. In addition, the placeholders %path% and %date% may
be used. %path% is replaced by the folder in which the active
workbook resides. %date% is replaced by the current date/
time in the format YYYY-MM-DD_HH-MM-SS.
Parameter Validation This cell contains a formula that checks whether the parame
ters in the Selection sheet are consistent. The report will not
start unless this formula returns blank. In the case of inconsis
tencies, the formula will return an error message that is pre
sented to the user when extraction is started. For example, the
sample workbook contain the formula shown in the graphic be
low, which checks if the Records per Request parameter is fil-
led. If not, the message 'Records per Request' must be speci
fied is brought up and the report is aborted.
Update New Report Start Date This parameter controls whether the New Report Start Date/
Time fields on the Selection sheet are updated automatically
after an extraction run. The standard setting for this parameter
is Yes. This ensures that the user running the report doesn't
need to worry about manually updating the extraction start
date/time. The user simply needs to choose the Get Data but
ton to get the changes that have taken place in the system
since the last extraction run.
However, there are cases where it makes sense to set the pa
rameter to No. For example, when you want to test the extrac
tion with the same base date/time over and over again.
Records per request The number of records to be retrieved with one API call. If there
are more records that meet the selection parameter, subse
quent queryMore requests are sent to retrieve more records.
The greater this parameter is, the less overhead is caused,
however, the longer it takes to process one chunk of data.
Recommendation
Use PaymentInformationV3 Set this parameter to Yes to enable Payment InformationV3 for
the single-sheet workbook instead of Direct Deposit.
Build Dynamic Request Set this parameter to Yes to use the Requested Segments table
as the source of the query call.
Table Format The area labeled Table Format specifies the formatting which is
used for the result sheets. Note that this part includes named
cells that should not be deleted. Otherwise the rendering code
will no longer run.
Format for Changed Fields The cell right to the label provides the formatting that is ap
plied to changed fields in the result sheets. Only the values in
the New columns will be formatted like that.
Additional Filters (ANDed) This table defines filter expressions (XPaths) that are applied
locally in Microsoft Excel to the response XML of the
Compound Employee API to check whether an employee is
included. An employee is in if they match all XPath expression
in the list. For more information, refer to the Filter Logic sec
tion.
Additional Filters (ORed) This table defines filter expressions (XPaths) that are applied
in Microsoft Excel locally to the response XML of the
Compound Employee API to check whether an employee is
included. An employee is in if they match all conditions of the
Additional Filters (ANDed) table and they match any of the
XPath expression in this list. For more information, refer to the
Filter Logic section.
Keep Intermediate Results This parameter controls whether intermediate results are kept
in the Microsoft Excel workbook beyond the end of the extrac
tion run. The intermediate results (kept on hidden sheets of
the workbook) are required for calculating the delta informa
tion and contain more data than are shown on visible sheets.
Therefore, for security reasons, this option should be set to No
in productive environments. This ensures that intermediate re
sults are deleted once the visible sheets are filled.
You have to set this to Yes when you want to send the filled re
port to SAP for troubleshooting purposes.
Test Mode This parameter controls whether data is fetched from the sys
tem or whether the intermediate results contained in the work
book are used. This mode is typically used for troubleshooting
when the person debugging the code has no access to the sys
tem. A prerequisite is that the intermediate results have been
kept in the workbook by retrieving with Keep Intermediate
Results = Yes before.
Change Sheets This table contains the names of the sheets that are intended
to receive changed data in contrast to the table receiving new
data for hire and rehires. If you don't need one of these sheets
to be filled, you may hide or delete it and remove the corre
sponding entry from this list. In case you introduce a new sheet
containing changes, you have to add the sheet name to this ta
ble. Otherwise it won't be filled with data. The multi-sheet
workbook contains a Payment Info sheet that is not a part of
this table. For more information refer to Using Payment Infor
mation in the Result Sheets [page 67].
Hire Sheet This field contains the name of the sheet to receive new data
for hired or rehired employees. You do not necessarily need
such a sheet. For example, the workbook template CompEmp
Delta_multiSheet.xlsx has no Hire Sheet because new data
goes into the entity sheets.
Requested Segments This table contains the technical segment names used to
query data from the system using the Compound
Employee API. All segments included in this table are sup
ported by the Compound Employee API. Remove the seg
ments from this table that you don't want to use for data proc
essing in the Delta Export workbook.
Related Information
Employee Delta Export for Microsoft Excel has an Errors sheet, which shows all employees who could not be
replicated for whatever reason.
Employees shown on the Errors worksheet will not appear on any of the results sheets. You need to take this very
seriously and handle these employees manually.
The reasons are typically severe inconsistencies in the time slices of effective-dated entities for this employee. For
example, if a compensation time slice starts at a time for which no job information time slices exists.
Employees shown on the Warnings worksheet also show up on the result sheets as usual. However, the fields
indicated in the warning remain empty.
"custom-string1" can’t be returned. Please make sure that the external code for picklist "currency" with option ID
"12722" is valid.
This means that the field custom-string1 on the entity that is shown with the warning cannot be filled for the
employee in question since the data model has a picklist "currency" configured for this field which is not properly
configured. The Compound Employee API, and as a result also the Microsoft Excel application, require the external
code to be filled for all picklist options. Otherwise such a warning appears.
Another reason could be that the picklist assignment was changed in the data model, so that a picklist was
assigned to a formed free-text field or the picklist assignment was changed to a different picklist. In this case, the
valued assigned to employees based on the formed picklist is no longer valid for the new picklist.
To make internal worksheets visible, use the Show Internal Sheets function on the Developer tab. You shouldn't
change or remove these sheets.
Lookup
This sheet contains a couple of tables with foundation data that are used to show the user-friendly descriptions of
fields on the result sheets that are based on foundation objects. For example, to show the description of a pay
component. This is sometimes desired because the Compound Employee API only returns the external codes of
these fields. For more information on how to make use of the foundation data on this sheet, refer to the Extending
Employee Delta Export section.
The data on this sheet is refreshed from the system automatically when an unresolved reference to lookup data is
detected after filling the result sheets.
LookupPerson
This sheet contains additional data for persons who are referred to on the result sheets. This is useful for cases
where the Compound Employee API only provides the user ID of these persons. The job information, for example,
Picklists
This sheet contains all picklist entries for all picklists found in the system. This is useful when you want to show the
user-friendly description of a field on the result sheets, which is based on a picklist. In the sample workbook
CompEmpDelta_multiSheet.xlsx, the Address Type field on the Address sheet is such a case. This is sometimes
desired since the Compound Employee API only returns the external codes of these fields. For more information
on how to make use of the foundation data on this sheet, refer to the Extending Employee Delta Export section.
These sheets are used for internal processing. During a report run, they receive the raw data returned by the API
calls to the system. As a default, the content of the sheets is deleted at the end of a report run. For troubleshooting
purposes, however, it makes sense to keep the data on these sheets. This can be controlled by the configuration
parameter Keep Intermediate Results.
Scrambling
This sheet contains a table of XPath expressions that are used by the Scramble Data function on the Developer tab.
These XPaths specify the fields that will be affected by the scrambling algorithm.
Related Information
The Employee Delta Export Add-In for Microsoft Excel creates a SuccessFactors tab and adds a SuccessFactors
group to the Developer tab in the Microsoft Excel ribbon.
Once you've installed the Employee Delta Export Add-In for Microsoft Excel, the SuccessFactors tab will appear in
the ribbon.
The SuccessFactors tab is for the end users of the Employee Delta Export for Microsoft Excel.
SuccessFactors Tab
● Get Data: Starts the extraction of data from the system and subsequent post-processing.
● Save Copy: Saves a copy of the Microsoft Excel that is intended to be sent out to other people in or outside your
organization. This copy doesn't contain any internal sheets or hidden business data.
● About: Gives you the version information for the installed add-in.
The Employee Delta Export Add-In for Microsoft Excel adds a SuccessFactors group to the Developer tab.
The functions in the SuccessFactors group are useful especially for an admin who needs to customize the sample
workbooks.
Note
The Developer tab is only visible if you have enabled it in Microsoft Excel.
The consistency check on the Developer tab of Employee Delta Export for Microsoft Excel verifies that the
configuration is consistent.
Caution
Performing a consistency check will delete the data on the result sheets.
Use the consistency check after you've changed the configuration part of a workbook. In particular the following
checks are performed:
● Are the XPaths contained in rows 1 and 2 of the Result sheets correct?
If the rows contain only simple segment and field XPaths these are cross-checked against the signature of the
Compound Employee API in the backend. If the XPath contains logical or other operators it is only checked if
the XPaths are syntactically correct.
● Are the New / Old column pairs considered in the formula of the column named EC_RelevantChanges?
This is essential because otherwise changes in these columns are not considered during delta calculation.
● Are segment XPaths maintained for columns that have correct lookup formulas?
The Employee Delta Export for Microsoft Excel provides tools for making personal data anonymous, for showing or
hiding internal sheets or configuration rows and columns, and for upgrading the workbook.
The following tools are available on the Developer tab of the Employee Delta Export for Microsoft Excel:
● Scramble Data
● Show/Hide Internal Sheets
● Show and Hide Configuration Rows/Columns
● Upgrade Workbook
Scramble Data
The Scramble Data tool makes the personal data on the result and internal sheets anonymous. Use this before
sending a spreadsheet filled with sensitive data to unauthorized persons.
The rules for this scrambling are on the hidden Scrambling sheet. The sample workbooks deliver a set of XPaths
appropriate for the standard Employee Central data models. If a customer's data model introduces additional
personal data in custom fields, it's up to the customer to add rules for these fields as well.
Note
Data on the hidden sheets Delta Result, Snapshot Result, and Full Result may contain data that is not shown on
the visible result sheets. Rules will cover this data as well.
Hides or unhides all sheets used for internal purposes. Show these for troubleshooting in case unexpected results
are shown on the result sheets.
Shows and hides all rows and columns with configuration information, these are the rows one, two, and three of the
result sheets
Use this function rather than manually hiding the configuration rows and columns to ensure that all such rows and
columns are affected.
Upgrade Workbook
Use Upgrade Workbook to upgrade your customer's workbook with new features delivered by SAP SuccessFactors.
The result is a workbook with customer-specific enhancements as well as new features, such as new result sheets,
new selection parameters on the Selection and Summary sheets, or new configuration parameters on the Config
sheet. The result sheets containing business data are typically not affected by upgrades.
1. Download the most recent version of the workbook provided by SAP SuccessFactors from the Employee Delta
Export UI.
2. Open the customer-specific workbook. This workbook can be of version 1502 or higher.
3. Choose the Upgrade Workbook tool from under Tools on the Developer tab.
Note
When moving rows to another position of the sheet, make sure to copy the named ranges to the new location as
well. Otherwise, the workbook might not work correctly.
Using the Design function on the Developer tab, you can add columns to or remove columns from the Employee
Delta Export for Microsoft Excel.
Add Columns
The Add Columns function starts a wizard that enables you to add one or more columns based on fields that are
available for a specific segment in the Compound Employee API signature. The selection table has the following
columns:
● The column Field Name displays the technical name of the field in the Compound Employee API and a
checkbox that allows the selection of multiple fields in one segment.
● The Column Heading column contains the field label found in the data model. If no field label has been
maintained in the data model, the value is derived from the technical name.
● The columns New/Old Columns and Always Show Value display how the generated column will be configured.
When a row in the field list is selected, the Column Properties are shown below the list.
In the Column Properties, you can change the column heading and the generation properties. Selecting the
Generate New/Old Columns option creates a new/old column pair for the selected fields that displays the current
value and the value before the change. Furthermore, these columns are considered in the formula in the
EC_Relevant Changes column. If this option isn’t selected, only a single column is created that shows the current
value (if that particular field has changed since the last extraction). By selecting the Always Show Value in Column
option, you generate a column that always shows the current value of a field, even if the value hasn't changed since
last extraction. If neither Always Show Value in Column nor Generate New/Old Columns are selected, the new
column only displays the values that have changed since the last extraction. For fields that are picklist-based,
lookup columns are generated that show the picklist labels. The columns that contain picklist values are generated
and then hidden.
If you have enabled Payment Information and configured the workbook to use it, the Add Columns wizard displays
all available fields for the payment_information segment and its subsegments. The payment_information
segment has a hierarchical structure:
● PaymentInformationV3
○ PaymentInformationDetailV3
○ PaymentInformationDetailV3USA
○ ....
○ PaymentInformationDetailV3GER
Most of the relevant Payment Information fields are on the PaymentInformationV3Detail segment node.
Therefore, the wizard uses this node as the base node. The parent node is the PaymentInformationV3, fields on
the root node begin with ../ for example ../createdBy. Fields that start with segment names are the country/region-
specific child nodes of the Detail node. For example, PaymentInformationDetailV3JPN/createdBy. Even if a field on
such a country/region-specific segment has the same name as a field on another country/region segment, they’re
generated as separate columns on the Result sheet.
Note
It’s possible to create custom associations on the payment_information segment and its subnodes.
However, the associations won’t be considered by the Add Columns wizard. Only fields on standard segments
of payment_information are included on the field list.
In the Add Columns wizard, hierarchical MDF-based segments that have a header segment with items underneath,
like for example Alternative Cost Distribution or Recurring Deductions, are handled the same way as Payment
Information. The item level is then used as segment XPath. Fields of the header segment are addressed with ../ in
the same way as is done for Payment Information. Custom associations aren’t reflected in the Add Columns wizard.
The Add Columns wizard uses an internal cache to display all fields that are available for the supported segments.
With the help of the cache, only one login is needed to call a describeEx and retrieve the field list, which is then
displayed. In cases where changes have been made to the company's data model that aren’t yet reflected in the
Add Columns field list, you can trigger a refresh using this option. However, this requires another login to call the
describeEx.
Use the wizard provided by the Employee Delta Export for Microsoft Excel to add columns.
Context
The Add Columns function starts a wizard that enables you to add one or more columns based on fields that are
available for a specific segment in the Compound Employee API signature.
Remember
Procedure
Segment Selection
4. Select Add Columns to add the selected columns to the currently selected sheet.
Note
If you use the Add Columns function on the Hire sheet of a single-sheet type workbook, the options
Generate New/Old Columns and Always Show Value in Column are not available.
Use the wizard provided by the Employee Delta Export for Microsoft Excel to remove columns.
Context
The Delete Column function starts a wizard that enables you to delete a selected column from a result sheet. The
difference to the standard Microsoft Excel delete function is that this function preserves the consistency of the
workbook from an SAP SuccessFactors perspective. You can only delete single columns at a time.
Procedure
Delete Column
2. If the column to be deleted is used in the change formula of the active sheet, the formula is adjusted
automatically.
3. If the column you have selected for deletion is the last column referenced in the EC_RelevantChanges formula,
the deletion is not executed and an error message is displayed. This ensures the functional correctness of the
EC_RelevantChanges formula.
You can use the default reporting workbooks provided by the Employee Delta Export as a starting point, but you
need to customize them to fulfill the requirements of a productive use case.
The Employee Delta Export comes with two different variants of reporting workbooks. Customizing can just be
changing the configuration data that is included in the reporting templates. No programming is required for this.
Some XML knowledge is beneficial, however, since the configuration uses XPath expressions to identify the
elements in the XML response of the CompoundEmployee API calls.
Customizations that require a change in the add-in should be sent to SAP SuccessFactors as a requirement.
Changes in the add-in's VBA code are not recommended since these will be overwritten by the next update.
Dos and Don'ts for Using the Employee Delta Export Add-In for Microsoft Excel [page 69]
Check out some changes that you can make when adjusting the Employee Delta Export Add-In. And see
what we don't recommend doing.
When extending Employee Delta Export for Microsoft Excel you can apply three categories of changes to the
reporting workbooks.
Column configuration is in the hidden rows one, two and three of each result worksheet. You can make
configuration visible using the function Show Configuration Rows/Columns in the SuccessFactors group on the
Developer tab.
Row 1 contains an XPath expression identifying the segment in the XML result of the Compound Employee API
that carries the field to be shown in the column in question. For example, the XPath .//personal_information
identifies the bold element in the XML result below.
<person xmlns="urn:sfobject.sfapi.successfactors.com">
<birth_name>Kendrick</birth_name>
<personal_information>
...
<first_name>Amy</first_name>
...
<last_name>Kendrick</last_name>
...
<start_date>2014-07-11</start_date>
</personal_information>
...
</person>
Row 2 contains an XPath fragment that identifies the element starting from the corresponding segment XPath in
row 1. For example, if you want to show the field first_name in the column just enter first_name in row 2.
Row 3 can contain a valid Microsoft Excel formula that calculates the values in this column from other columns.
The formula must use cells references in row 3 to refer to values in the same row. The formula will be copied to rows
below automatically.
Note
Cells containing formulas must have the cell format General. Make sure that the cell format is correct before
you enter a formula.
The example below shows the configuration for first name, last name, and formatted name calculated from the first
and last name. Note especially the formula in cell G3 of the graphic below.
All columns of the same segment XPath should be configured contiguously. A column with a different segment
XPath B in between a sequence of columns with XPath A leads to unexpected results. However, calculated
columns interrupting the sequence is not harmful.
Context
For the following description let's assume you want to add the field custom_string5 of Personal Information.
Procedure
1. Figure out the field name of the field in the signature of the Compound Employee API.
For a reference of valid fields please go to the SFAPI Data Dictionary in Admin Tools. The dictionary says the
field name is /person/personal_information/custom_string5
2. Make the first three rows of the worksheet visible. These rows contain configuration information.
3. Insert a new column where you want the additional data to appear.
4. In the first row of the new column, add .//personal_information, which is an XPath expression selecting
the time slices of personal information within the result of the Compound Employee API.
The starting point of the XPath is assumed to be the <person> element. XPath expressions may also include
restrictions like .//address_information[address_type='home']. The XPath can also make use of
content in neighboring columns of the same row. In order to do this, introduce a name for the column with the
prefix EC_Col_ and use the part following the prefix in the XPath.
Example
5. In the second row of the new column add custom_string5, which is the field name of the new field in the result
of Compound Employee API.
The final XPath picking the field value out of the XML result is concatenated from the segment XPath above
and the field name, which is in fact taken as an XPath fragment.
6. Add the newly added columns to the formula that determines if a row is relevant.
The purpose of the Employee Delta Export application is to show only records that shall be forwarded to a
payroll system or a similar system. Typically, these are the records which are new or have changed significantly
a. Go to the column with the name EC_RelevantChanges on the same sheet and adapt the formula in row 3 of
this column.
The formula will return a value unequal blank if the row contains relevant changes. This ensures that the
row appears on the result sheet. Note that this column may be hidden. You can figure out where it is by
using the Name Manager function on the Formulas tab in Excel.
The next time you run the extraction, the new column will be populated if the field value has changed in
Employee Central since the specified report start date.
b. If you want to see both the current field value and the old value on the sheet, introduce a second column
for the same field.
This works mostly as described above with the difference that the field name entered in the second row
must be custom_string5/@previousValue. This denotes the value as it was at the point in time of the last
extraction.
c. If you want to see the current value regardless of whether it was changed since the last extraction or not,
use custom_string5/@currentValue as a field name in the second row of the column in question.
This makes sense for key fields as well as for attributes such as currency.
d. In the segment XPath, you can use a notation such as full://personal_information.
This denotes that the column is filled from the full extract rather than from the delta extract. This ensures
that the field is filled even if personal_information (in this example) has not actually changed.
Note
Using the full:// notation in the field XPath row makes it easier to sort the columns.
The columns User ID and Person ID (columns B and C) are always sortable even though they don’t use
the full:// notation.
e. You may populate the columns of a particular sheet from different segments in the API result structure.
Note, however, that data from different segments may go into different rows in the worksheet. This may
lead to unexpected results.
Extend the result sheets of Employee Delta Export for Microsoft Excel by adding a column that contains a
calculated value.
Procedure
To add a column that contains a value calculated from other columns of the same row, enter a formula into row 3 of
the column that refers to other cells in the same row.
Cells containing formulas must have the cell format General. Make sure that the cell format is correct before
you enter a formula.
Context
The CompoundEmployee API only provides external codes for fields based on picklists. Here's how to display your
own user-friendly descriptions rather than the external codes:
Procedure
Add a new column with a formula that does a lookup to the Picklists sheet, which is typically hidden.
Take column Address Type in the sample reporting workbook CompEmpDelta_multiSheet.xlsx as a reference. It
uses this formula:
=VLOOKUP(CONCATENATE("addressType|";G3);Picklists!A:D;4;FALSE)
The formula looks for the row containing the address type's external code on sheet Picklists and returns the value
in column 4 which is in fact the label.
Note
Cells containing formulas must have the cell format General. Make sure that the cell format is correct before
you enter a formula.
Display your own user-friendly descriptions rather than the external codes for fields based on foundation objects
(FOs).
Context
The CompoundEmployee API only provides external codes for fields based on foundation objects. Here's how to
display your own user-friendly descriptions rather than the external codes for FO-based columns.
Note
Time dependencies of foundation objects are not considered. Only the currently effective values are used.
Procedure
1. Add a new column containing a formula that does a lookup to the Lookup sheet, which is typically hidden.
Use column Pay Component in the sample reporting workbook CompEmpDelta_multiSheet.xlsx as a reference.
It uses the following formula:
=VLOOKUP(E3;EC_Lookup_PayComponent;2;FALSE)
This formula looks for the row containing the pay component's external code in table
EC_Lookup_PayComponent on sheet Lookup and returns the value in column 4 which is in fact the label. The
table is filled automatically when unresolved references are found after processing the result of the Compound
Employee API call.
Note
Cells containing formulas must have the cell format General. Make sure that the cell format is correct
before you enter a formula.
Delete columns from Employee Delta Export for Microsoft Excel if you don't need them.
Procedure
1. Use Design Delete Column on the Developer tab to remove columns from result sheets.
When deleting columns using this tool, all references stay valid.
2. Check the formulas in row 3 for REF! errors and resolve them, especially the EC_RelevantChanges column. If
the column you want to delete is referenced in a lookup as source column, you have to delete the lookup
column as well. If the REF! error appears in the formula in the EC_RelevantChanges column, delete the
expression containing the REF! entry from the formula.
Example
=IF(OR(#REF!<>G3;H3<>I3);"X";"")
Change it to:
=IF(OR(H3<>I3);"X";"")
In this way, you make sure that the changed calculation still works as desired, because corrupt formulas
will prevent the formula to work at all.
3. To verify that workbook configuration is still intact, use the Check Consistency function on the Developer tab
after removing columns.
Related Information
Show personal information like first name or last name along with the user ID in Employee Delta Export for
Microsoft Excel.
Context
The CompoundEmployee API only returns an employee's user ID. Here's how to show personal information along
with this ID:
Note
Only personal data for active users can be retrieved. The lookup logic will have an impact on performance.
Procedure
This formula refers to the table EC_Lookup_PersonalInfo on the LookupPerson sheet. Once the formula is detected
by the delta reporting logic, the personal information is retrieved for the user IDs found in the column referred to by
the formula (in this case column A).
Show information about workflow approvals related to a segment in the Microsoft Excel that's populated by the
Employee Delta Export Add-In.
Procedure
1. Introduce a column that is mapped to the field workflow_request_id of the segment in question.
This formula refers to the table EC_Lookup_Workflow on sheet LookupOData. Once the formula is detected by
the Employee Delta Export logic, the workflow information is retrieved for the workflow requests found in the
column referred to by the formula (in this case column J).
Note
Add more filters to the Selection sheet for Employee Delta Export for Microsoft Excel. It already has multiple default
fields you can use for filtering employees, but you can add more if necessary.
Context
Procedure
For a reference of valid fields, go to the SFAPI Data Dictionary in the Admin Tools. Uppercase/lowercase
don't matter for the parameter name.
2. Add a new locally applied filter.
a. Go to the Selection sheet and add a new row similar to the one for country/region.
b. For the cell where the filter value is entered you need to introduce a name following the pattern
EC_FilterAtClient_<parameter name> where <parameter name> is a name of your choice.
c. Go to the Config sheet and add the new parameter to the XPaths of one of the Additional Filters sections
that are already in place or add a new XPath to one of these sections.
Next Steps
You can also add filter parameters that are applied locally on the client after the result of the CompoundEmployee
API call is available. To do so, add a new filter condition on the Config sheet that uses the new filter parameter as a
placeholder.
If you have enabled Payment Information in Provisioning, there are a few steps you need to take to make the
Payment Info sheet visible in the multi sheet workbook as well as new columns on the Hire and Change sheets of
the single sheet workbook.
Procedure
1. To enable Payment Information in the multi-sheet workbook, make the following adjustments in the Change
sheets table to fill the Payment Info result sheet:
a. Delete Direct Deposit.
b. Add Payment Info.
The Payment Info sheet is not used by the multi-sheet workbook by default, therefore, it is not included in the
Change Sheets table on the Config sheet by default.
You can add either Direct Deposit or Payment Info. If you include both sheets in the table, you'll get a warning.
The request that is sent to the Compound Employee API changes depending on which sheet is added to the
table.
If you have already enabled Payment Information in Provisioning but the workbook is configured to use Direct
Deposit, you will get a warning message and the call will not be executed. Same applies to the case where
Direct Deposit is enabled in Provisioning and the workbook is configured to use Payment Info.
2. To enable Payment Information in the single-sheet workbook, go to the Config sheet and set the Select Option
for Use Payment Information V3 to Yes.
If you have already enabled Payment Information in Provisioning, but the workbook is configured to use Direct
Deposit, you will get a warning message and the call will not be executed. The same applies to the case where
Direct Deposit is enabled in Provisioning and the workbook is configured to use Payment Information.
Use the Requested Segments table in Employee Delta Export for Microsoft Excel to choose which segments are
extracted from the backend, thus reducing the amount of data that is being retrieved.
Procedure
By default, the Requested Segments table contains all segments supported by the CompoundEmployee API by
their technical name.
2. Remove the segments that aren’t needed for data processing in your case, to reduce the amount of data that is
extracted from the backend.
3. If necessary, add one ore more of the following segments that aren't available in the standard query:
○ Deduction Recurring
○ One Time Deduction
○ Alternative Cost Distribution
○ Personal Documents Information
By default, these result sheets are included in the Change Sheet table on the Config Sheet, but aren’t filled with
results. Data extraction for these sheets will only happen if defined in the Requested Segments Table.
Restriction
Recurring Deduction, One Time Deduction, and Alternative Cost Distribution must have start dates later
than October 10, 2015. Delta calculation can't be performed for time periods before, due to missing MDF
audit history data. You can't use the period-based delta functionality if you request One Time Deductions
(deductions_non_recurring).
4. After adjusting the segment list in the Requested Segments table remember to set the configuration parameter
Build Dynamic Request on the Config Sheet to Yes so that the request XML is built using the segments you
maintained in the table.
Related Information
Check out some changes that you can make when adjusting the Employee Delta Export Add-In. And see what we
don't recommend doing.
Field Sequence
Fields related to a particular segment in the result of the CompoundEmployee API must be in sequence without
being interrupted by fields from other segments. The reason is that in sheets showing changes, a new row is
started as soon as the segment changes. If the field sequence is interrupted, the fields of the same segment spread
across different rows.
Don't delete the first 3 hidden rows of the worksheets that show the changes of an entity.
Named Columns
Don't delete named columns on the change sheets. To figure out whether a column is a named column, select the
column and check the name field in the area above the A1 cell. Other columns can be deleted without restrictions,
for example if the users no longer want to see it.
Copying Sheets
You can copy sheets from one workbook to another to save time. A typical use case is to copy the Config or the
Systems sheet to duplicate settings. To do so, right-click on the source sheet, choose Copy, and choose the target.
This can, however, create undesired copies of names that carry references to the source file. Use the Name
Manager in Microsoft Excel to check your sheets and to remove the undesired names.
Make sure to set a Report Start Date and other available selection criteria, such as the Requested Segments table,
to narrow down the target population that is extracted to the Delta Export workbook. Making these settings
improves the performance and memory usage.
By default, the Requested Segments table is delivered containing all segments that are supported by the Compound
Employee API. Remove all the segments of the table that you don't need for data processing. In that way, data
extraction takes less time and post-processing has less data that needs to be managed.
Note
Removing segments is only relevant if you've set the Build Dynamic Request parameter.
Using Formulas
If the basic fields retrieved from the backend don't fully meet your requirements, you can introduce new columns
that use formulas to calculate the content from other basic fields. For example, you can use a formula to compute a
full address from the columns postal code, city, country, and address1. Enter the formula in row 3 of a change sheet.
Only this ensures that it’s copied to the data when the sheet is populated.
Columns containing formulas should typically not be considered in the formula contained in the column named
EC_RelevantChanges if the original field is already in there. The reason is that the calculation can fail in a row for
some reason and the row can appear unexpectedly.
Population Changes
Replication of employee changes is easy when you have one payroll (or other type of) subsequent system to where
you transfer the data. Things become more complex once you have various subsequent systems with different
processors using different variants for the reporting workbooks. This is what we call populations. One population is
a set of filter criteria, which specifies the employees going into one subsequent system.
Things become even more complex once employees move around between different populations. In this case, you
need to ensure that processors recognize when an employee enters their population and only receive changes for
employees who belong to their population.
What you should do when an error occurs in Employee Delta Export for Microsoft Excel.
Context
When an error occurs during data extraction that needs to be analyzed by your administrator or by SAP, proceed as
follows:
Procedure
Related Information
Hyperlinks
Some links are classified by an icon and/or a mouseover text. These links provide additional information.
About the icons:
● Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your agreements
with SAP) to this:
● The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.
● SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any
damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.
● Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering a SAP-hosted Web site. By using such links, you
agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this information.
Example Code
Any software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax and
phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of example
code unless damages have been caused by SAP's gross negligence or willful misconduct.
Bias-Free Language
SAP supports a culture of diversity and inclusion. Whenever possible, we use unbiased language in our documentation to refer to people of all cultures, ethnicities, genders,
and abilities.
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. All
other product and service names mentioned are the trademarks of their
respective companies.