IMPLEMENTATION GUIDE | PUBLIC
Document Version: Q4 2019 – 2019-11-

© 2019 SAP SE or an SAP

affiliate

company. All rights reserved.

THE BEST RUN

2 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode

• 1 Introduction to Compound Employee API Delta Transmission..........................
• 1.1 Business Context.............................................................
• 1.2 Employee Master Data Synchronization: From Full to Delta Transmission......................
• 1.3 Provisioning Settings and Permissions..............................................
• 1.4 Notation for Examples..........................................................
• 2 Using the Delta Transmission Mode of Compound Employee API.......................
• 2.1 Effective-Dated and Period-Based Delta Transmission..................................
• 2.2 Delta Transmission Query Request................................................
  • Select Items.............................................................
  • Time-Restricted Delta Transmission Support for MDF Objects..........................
  • Where Expression..........................................................
  • Select Condition hiringNotCompleted...........................................
  • Sorting by Start Date in the Where Expression.....................................
  • Query Parameters.........................................................
  • Controlling Parameters for Delta Transmission.....................................
• 2.3 Delta Transmission Query Response...............................................
  • Query Response for Effective-Dated and Period-Based Delta Transmission.................
• 2.4 Action Codes...............................................................
• 2.5 Previous Fields..............................................................
• 2.6 Event Information............................................................
  • Insert New Job Time Slice with Multiple Events.....................................
  • Insert New Job Time Slice to Existing Time Slice....................................
  • Change Event of a Concurrent Time Slice.........................................
  • Change Not Event Related Job Field of a Concurrent Time Slice.........................
  • Delete Job Time Slice (Active).................................................
  • Delete Job Time Slice (In Between).............................................
• 3 Effective-Dated Delta Transmission.............................................
• 3.1 Use Cases for Effective-Dated Entities..............................................
  • Time Slice Handling for Effective-Dated Entities Without Semantic Key....................
  • Time Slice Handling for Effective-Dated Entities with Semantic Key......................
• 3.2 Example: Compensation and Pay Compensation Recurring...............................
• 3.3 Non-Effective-Dated Entities....................................................
• 4 Period-Based Delta Transmission...............................................
• 4.1 Enabling Period-Based Delta Transmission..........................................
  • End Date Handling.........................................................
  • Parameter isNotFirstQuery...................................................
• 4.2 Use Cases for Period-Based Delta Transmission.......................................
  • First Time Slice Starting After the Provided Period..................................
  • First Time Slice Effective in the Provided Period....................................
  • Subsequent Time Slice Effective in the Provided Period...............................
  • Change of Time Slice Starting Before the Provided Period.............................
  • Change of Time Slice Starting and Ending Before the Provided Period.....................
  • Change of Subsequent Time Slice Effective in the Provided Period.......................
  • Deletion of Subsequent Time Slice Starting After the Provided Period.....................
• 5 How Compound Employee API Delta Transmission Handles Foundation Objects............
• 5.1 External Codes..............................................................
• 5.2 Attributes of Effective-Dated Foundation Objects......................................
  • Current and Previous Values of Attributes........................................
• 6 How Compound Employee API Delta Transmission Reacts to Data Purge.................
• 7 Limitations of Compound Employee API Delta Transmission..........................
• 7.1 Supported Segments.........................................................
• 7.2 Non-Supported Segments......................................................
• 7.3 Personal Documents with Duplicate Semantic Key.....................................
• 7.4 Emergency Contacts with Duplicate Semantic Key.....................................
• 7.5 Support of Specific Attributes...................................................
• 7.6 Issues When Using Select Conditions..............................................
• Content PUBLIC Implementing the Employee Central Compound Employee API in Delta Transmission Mode

This document describes changes to this guide for the recent releases.

Q4 2019

Table 1: The following table summarizes changes to this guide for the Q4 2019 release

What's New Description More Info
New query request parameter
hiringNotCompleted

You can use the new parameter
hiringNotCompleted to return
only data of hired employees or to re­
turn data of hired employees plus data
of candidates (new hires that did not
yet complete the Manage Pending Hire
process).

Where Expression [page 14 ]
Select Condition hiringNotCompleted
[page 17 ]

Q1 – Q3 2019

Table 2: The following table summarizes changes to this guide for the Q1, Q2, and Q3 2019 releases

What's New Description More Info

No changes We did not update this document.

4 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
What's New in the Delta Transmission Mode of Employee Central Compound Employee
API

Q4 2018

Table 3: The following table summarizes changes to this guide for the Q4 2018 release

What's New Description More Info

Updating info about Select items We corrected the information given for
the emergency_contact_primary seg­
ment. This segment is supported in the
effective-dated delta as well as the pe­
riod-based delta transmission mode.
We added the
DRTMPurgeStatusOverview segment.
This segment is not supported in the
delta transmission mode.

Select Items [page 12 ]

Q3 2018

Table 4: The following table summarizes changes to this guide for the Q3 2018 release

What's New Description More Info

Updating info on LAST_MODIFIED_ON
parameter

We corrected the info about how far
back the last modified date can go: It's
3 months (not 6 months as previously
said).

Where Expression [page 14 ]

Implementing the Employee Central Compound Employee API in Delta Transmission Mode What's New in the Delta Transmission Mode of Employee Central Compound Employee API PUBLIC 5

What's important to know about Compound Employee API in general and about its delta transmission mode.

Business Context [page 6 ]
What is the Compound Employee (CE) API?
Employee Master Data Synchronization: From Full to Delta Transmission [page 7 ]
Take a look at the difference between full transmission and delta transmission mode of the Compound
Employee API.
Provisioning Settings and Permissions [page 8 ]
The delta transmission mode of Compound Employee API uses the same Provisioning settings and
role-based permissions as the standard mode.
Notation for Examples [page 8 ]
Within this documentation, we use a specific notation for the visualization of time slices of the
snapshot data, the current data, and the calculated delta of an effective-dated entity.

What is the Compound Employee (CE) API?

Employee Central can be used as leading application for employee master data. 3rd party systems, such as payroll or benefits providers, require Employee Central employee data (Global HR Data) to trigger their own services and follow-up processes. Therefore, a regular replication of Global HR Data to the 3rd party systems has to be ensured. For this purpose, replication processes call the so-called Compound Employee (CE) API, a SOAP-based web service inside Employee Central to retrieve employee master data out of Employee Central.

6 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Introduction to Compound Employee API Delta Transmission

Figure 1: Employee Central: Employee Master Data Integration

Compound Employee API is a query API within Employee Central, which is used to extract the employee master data that is relevant for the 3rd party system. The Compound Employee API response is structured similarly to the data structures in Employee Central.

The Compound Employee API is commonly used to synchronize employee master data between Employee Central and other on-demand or on-premise applications. It returns data about new employees and about changes of employee data. Replication of employee master data by calling Compound Employee API happens synchronously, which means that the response is immediately returned.

The Compound Employee API supports both full and delta transmission:

● In full transmission mode, the API replicates the complete employee data including future and historical
data, independent of whether the data was changed since the last replication or not.
● In delta transmission mode, the API only returns employee data that was created, changed, or deleted
since the last replication.

Take a look at the difference between full transmission and delta transmission mode of the Compound Employee API.

To set up the data synchronization and to initially load the employee master data from Employee Central into the consuming system, first a full-transmission query of Compound Employee API can be triggered. With this

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Introduction to Compound Employee API Delta Transmission PUBLIC 7

first synchronization, all employee data including historical data is sent to consuming systems. Afterwards, only changed employees need to be sent to the consumers to update the employee master data on consuming side accordingly.

In the past, replication of data changes was only possible for changes that happened since the last synchronization, meaning that the consumer used the Compound Employee API full transmission mode to retrieve only changed employees. However, the response of the full transmission contained the complete historical data of the employees, and it was up to the consumer to figure out which data was changed.

With support of delta transmission in Compound Employee API, it is possible to determine the concrete data changes of employees that have happened since a given point in time. In contrast to full transmission, consumers only get the changed data for an employee including the previous values, with a clear indication on how to process the data.

The delta transmission mode of Compound Employee API uses the same Provisioning settings and role-based permissions as the standard mode.

For more information, see Setting Up the Compound Employee API in Implementing the Employee Central Compound Employee API. Find the most current version of these guides in SAP Help Portal at http:// help.sap.com/hr_ec.

Within this documentation, we use a specific notation for the visualization of time slices of the snapshot data, the current data, and the calculated delta of an effective-dated entity.

Let's look at an example:

The snapshot data and the current data each have two time slices.

The first time slice of the snapshot data has value A. The second time slice has value B.

Figure 2: Snapshot Data

The first time slice of the current data has value C instead of A, which means that the value of the time slice was changed from A to C. The second time slice was not changed and still has value B. The changed time slice is shown in red color for better visualization.

Figure 3: Current Data

8 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Introduction to Compound Employee API Delta Transmission

The delta is calculated by the delta processor on the basis of the snapshot data and the current data. The first time slice shows Change C (A->C) , which means that the calculated action code for the time slice is CHANGE and the values were changed from A to C, where C is the current value.

Here, the changed time slice is shown in green color.

Figure 4: Delta to Be Transferred

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Introduction to Compound Employee API Delta Transmission PUBLIC 9

What you should know when using the delta transmission mode of Compound Employee API.

Effective-Dated and Period-Based Delta Transmission [page 10 ]
Employee Central's Compound Employee API offers two different kinds of delta transmission:
effective-dated and period-based.
Delta Transmission Query Request [page 11 ]
Find out about how the query request of the Compound Employee API call is structured.
Delta Transmission Query Response [page 25 ]
Here's what the query response of the Compound Employee API call looks like.

Action Codes [page 28 ]
The delta transmission mode of Compound Employee API supports some action codes.
Previous Fields [page 29 ]
In case a field has been changed since the last modified date, a subelement called previous is added
to the field.
Event Information [page 30 ]
Job information and compensation information require special treatment because they contain the
information about the business events, for example, a newly-hired employee.

Employee Central's Compound Employee API offers two different kinds of delta transmission: effective-dated and period-based.

Effective-dated delta transmission is designed for consumers that work in an effective-dated manner. This means, it is assumed that consumers store the time frame (start and end date) when a data record is effective. Deltas are communicated with regard to the time frames that have been transmitted in the last replication.

Period-based delta transmission is intended for consumers that are not able to deal with effective dated objects. Deltas contain retroactive changes and effective dated objects that are relevant for the given period.

Not effective-dated objects are returned in both kinds of delta transmissions, if these are changed after the last replication.

Let's take a look at an example: An employee was hired and created in the system in September. In mid- October, the job data of the employee was changed using Make correction. Today (end of October), the salary was changed effective mid-October and the address was changed becoming effective in November. The last synchronization of the consumer took place before the change of the job data.

10 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Using the Delta Transmission Mode of Compound Employee API

Figure 5: Various changes an employee may go through

In effective-dated delta transmission, the Compound Employee API returns all changes that happened since the last synchronization, such as the change of the job, the change of the salary and the future address change.

For a consumer using period-based delta transmission and providing October 1 to October 31 as synchronization period, only the change of the job and the change of the salary will be replicated since these changes affect the given period and the data which has already been replicated to the consumer in the past. However, the change of the address remains unconsidered and will be transmitted in the next period of November, when it becomes effective.

 Note

Delta transmission is based on an active auditing to determine the historical data set of employees. This
means that auditing must be switched on during the system setup phase prior to the initial load of
employees into the system.

Find out about how the query request of the Compound Employee API call is structured.

The request has the following properties.

● queryString
This is the Select statement following SFQL grammar
● param
This is a list of optional parameters

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Using the Delta Transmission Mode of Compound Employee API PUBLIC 11

The query string is made up of a SELECT clause, a FROM clause, and a WHERE clause, as shown in the example below.

 Sample Code

<queryString>
SELECT <select_items>
FROM CompoundEmployee
WHERE <expression>
</queryString>

Select items and the expressions are case insensitive and are considered as long as the spelling is correct.

Select Items [page 12 ]
The Select items are a list of all entities to be returned as part of the hierarchical query response XML.
Time-Restricted Delta Transmission Support for MDF Objects [page 13 ]
Delta transmission support for generic (MDF) objects in the Compound Employee API has timely
restrictions.
Where Expression [page 14 ]
In the Where expression, select parameters and operators can be used to restrict the query response.
Select Condition hiringNotCompleted [page 17 ]
Use the hiringNotCompleted select condition in the query request if you want your downstream
systems to receive only data that has been validated against the employee data model in Employee
Central.
Sorting by Start Date in the Where Expression [page 20 ]
Time slices of effective-dated objects in the response are by default sorted in descending order by start
date.
Query Parameters [page 21 ]
The <param> tag contains parameters that control the behavior of the API.
Controlling Parameters for Delta Transmission [page 22 ]
You can use these parameters to control Compound Employee API delta transmission.

2.2.1 Select Items

The Select items are a list of all entities to be returned as part of the hierarchical query response XML.

The restriction of fields in specific segments is not supported. The following substructures are supported:

Table 5: Supported Substructures

Segment

Supported in Supported in
Effective-Dated Delta Period-Based Delta Delta Since
person X X
personal_information X X
address_information X X

12 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Using the Delta Transmission Mode of Compound Employee API

Segment

Supported in
Supported in
Effective-Dated Delta Period-Based Delta Delta Since
email_information X X
phone_information X X
person_relation X X
direct_deposit X X
national_id_card X X
dependent_information X X
emergency_contact_primary X X Q2 2016
employment_information X X
global_assignment_information X X
job_information X X
alternative_cost_distribution X X October 11,
2015
compensation_information X X
paycompensation_recurring X X
paycompensation_non_recurring X X
payment_information – – Q4 2014
accompensation_dependent – –
job_relation X X
personal_documents_information X X October 11,
2015
deduction_recurring X X October 11,
2015
deduction_non_recurring X – October 11,
2015
ItDeclaration X X Q1 2015
DRTMPurgeStatusOverview – –

2.2.2 Time-Restricted Delta Transmission Support for MDF

Objects

Delta transmission support for generic (MDF) objects in the Compound Employee API has timely restrictions.

The reason is that history information for MDF objects is only available after a given point in time and with delta transmission enablement of the MDF objects in the Q4 2014 or Q4 2015 release. Therefore, no historical data can be read and consequently no delta can be calculated if a point in time is chosen before the history data is available. Processing of the query request will consequently be terminated if an MDF object is part of the request using a date before the above give time restrictions.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Using the Delta Transmission Mode of Compound Employee API PUBLIC 13

 Note
Affected MDF objects are: deduction_recurring , deduction_non_recurring , alternative_cost_distribution

Delta transmission support for the PaymentInformationV3 MDF object as well as the feature itself was introduced with the Q4 2014 release. Therefore deltas only can be calculated from that release onwards. The IT Declaration MDF object was introduced in Q1 2015. Therefore delta calculations are only supported from that release onwards.

2.2.3 Where Expression

In the Where expression, select parameters and operators can be used to restrict the query response.

The Compound Employee API does not support expressions with complex conditions on multiple fields and different logical operators.

Table 6: Supported Select Parameters and Operators

Select Parameter Remark Operators
LAST_MODIFIED_ON Mandatory parameter. Returns all em­
ployees, for which any employee data
has changed since this date and time.
The date can only go back as far as 3
months.

>

fromDate...toDate Mandatory parameter for period-based
delta transmission. Selects employees
that have changes effective within the
given period. Additionally, the period is
applied as filter to all effective dated
segments, so that only time slices are
returned that intersect with the given
period. This select parameter needs to
be combined with the you can further
restrict the set of selected employees
either by specifying an open period, by
using only one of the parameters or by
using both parameters to determine a
fixed time
range.last_modified_on select
parameter.

=

selectFromDate Returns all employees that satisfy all
job and/or compensation conditions
where the effective end date of the re­
spective time slices is greater than or
equal to the value of
selectFromDate. The value must
be a fixed date format, for example:
to_date('2016-01-01','yyyy
-MM-dd')

=

14 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Using the Delta Transmission Mode of Compound Employee API

Select Parameter Remark Operators
selectToDate Returns all employees that satisfy all
job and/or compensation conditions
where the effective start date of the re­
spective time slice is lower than or
equal to the value selectToDate.
The value must be a fixed date format,
for example:
to_date('2016-01-01','yyyy
-MM-dd')

=

COMPANY_TERRITORY_CODE Returns all employees that have a job at
a company located in the provided
country at any point in time. The com­
panies are determined using table
FO_LEGAL_ENTITY_T.

=, IN

PERSON_ID Returns all employees with the respec­
tive PERSON_ID.

=, IN, NOT IN

PERSON_ID_EXTERNAL Returns all employees with the respec­
tive PERSON_ID_EXTERNAL

=, IN, NOT IN

USER_ID Returns all employees with the respec­
tive USER_ID

=, IN, NOT IN

COMPANY Returns all employees that have a job at
the selected company. The select is
based on the external code of the com­
pany.

=, IN

EMPLOYEE_CLASS Returns all employees that have a job of
the respective EMPLOYEE_CLASS.
The select is based on the external
code of the employee class.

=, IN

DEPARTMENT Returns all employees that have a job in
the provided department. The select is
based on the external code of the de­
partment.

=, IN

DIVISION Returns all employees that have a job in
the provided division. The select is
based on the external code of the divi­
sion.

=, IN

BUSINESS_UNIT Returns all employees that have a job in
the provided business unit. The select is
based on the external code of the busi­
ness unit.

=, IN

LOCATION Returns all employees that have a job in
the provided location. The select is
based on the external code of the loca­
tion.

=, IN

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Using the Delta Transmission Mode of Compound Employee API PUBLIC 15

Select Parameter Remark Operators
JOB_CODE Returns all employees that have a job
with the provided job code. The select is
based on the external code of the job
code.

=, IN

COMPENSATION_PAY_GROUP Returns all employees that receive
compensation with the provided pay
group. The select is based on the exter­
nal code of the pay group.

=, IN

SourceOfRecord Returns all employees that have an em­
ployment with the provided source of
record information. The select is based
on the external code of the source of re­
cord information.

 Note
The field needs to be enabled and
made visible in data model before
this filter parameter can be used.
Additionally in data model a picklist
needs to be assigned to the Source
Of Record field.

=, IN

isContingentWorker Returns all employees that have an em­
ployment with the given value in field
IsContingentWorker. The ab­
sence of the isContingentWorker
condition is treated as
isContingentWorker=false to
preserve compatibility with older inte­
gration processes that expect real em­
ployees only. In order to select all per­
sons that are contingent workers, use
the condition
isContingentWorker=true. If
you want to request only regular em­
ployees use the condition
isContingentWorker=false. If
you want both employment types, use
condition isContingentWorker
IN (true, false).
For more information about how to set
up and configure Employee Central for
contingent workers, see Contingent
Workforce Management.

=, IN

 Note
Possible comparison values for the
IN operation and the equal opera­
tor are true, t, 1 , yes, and false, f, 0 ,
no. If the value in the field on the
database is undefined (technically:
null) it is treated as false.

16 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Using the Delta Transmission Mode of Compound Employee API

Select Parameter Remark Operators
hiringNotCompleted Evaluates the indicator property
hiringNotCompleted in the Em­
pEmployment entity in Employee Cen­
tral, which was introduced for Onboard­
ing 2.0. The property allows for differen-
tiating data records of candidates (that
is, new hires that didn't yet complete
the Manage Pending Hire process). If
hiringNotCompleted is false, the
Compound Employee API returns
only data of hired employees.
For more information about Onboarding
2.0, see Onboarding 2.0.

=

 Note
Possible comparison values are:
false, f, 0 , no. That is, you can use
the hiringNotCompleted fil-
ter in the WHERE condition only to
exclude employments of candi­
dates in the result.

Effective Period Selection

Using the select parameters selectFromDate and selectToDate, you can further restrict the set of selected employees either by specifying an open period, by using only one of the parameters, or or by using both parameters to determine a fixed time range.

 Note
You can only use effective period selection in combination with other select parameters of job_information
or compensation_information. If you don't use an additional parameter, the query returns an error.

2.2.4 Select Condition hiringNotCompleted

Use the hiringNotCompleted select condition in the query request if you want your downstream systems to receive only data that has been validated against the employee data model in Employee Central.

The hiringNotCompleted parameter evaluates the indicator property hiringNotCompleted in the EmpEmployment entity in Employee Central, which was introduced for Onboarding 2.0. This property allows for differentiating data records of candidates (that is, new hires that didn't yet complete the Manage Pending Hire process). For more information about Onboarding 2.0, see Onboarding 2.0.

The hiringNotCompleted field is part of the segment EMP_EMPLOYMENT_INFO. If the value for hiringNotCompleted of an employment is false, it’s a standard employment of a hired employee. If the value for hiringNotCompleted of an employment is true, it's the employment of a candidate. That is, the employment is possibly incomplete with respect to the employee data model of Employee Central.

In contrast to other select conditions, such as company or employee_class, using hiringNotCompleted in the delta mode doesn't lead to a CHANGE action when the corresponding field value changes. Employments that had previously (at the last_modified_on timestamp) been filtered out according to the

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Using the Delta Transmission Mode of Compound Employee API PUBLIC 17

hiringNotCompleted condition require an INSERT action. Because only the INSERT action provides all data of the employment and all its requested subsegments. If the employment in question is the only employment of this person, also the person segment requires an INSERT action with all requested subsegments.

Let's look at some examples.

 Note
In the following examples, PersA means: data in the person segment in version A. PersB means: data in the
Person segment in version B. EmplA means: data in the employement segment in version A, and so on.

Example (Initial Situation): One Single Employment Where

hiringNotCompleted Is True

Snapshot

Person Person1: PersA
Employment Employment1: EmplA (with hiringNotCompleted =
true)
Job Job1: JobA
Job2: JobA

Current

Person Person1: PersB
Employment Employment1: EmplB (with hiringNotCompleted =
true)
Job Job1: JobB
Job2: JobB

Delta with hiringNotCompleted = false

No result because the person is filtered out by the preselection

Delta without hiringNotCompleted condition

Person Change for Person1: PersA > PersB
Employment Change for Employment1: EmplA > EmplB
Job Change for Job1: JobA1 > JobB
Change for Job2: JobA2 > JobB

 Note
The CHANGE action can also be NO_CHANGE if the corresponding images of version A and B don't differ.

18 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Using the Delta Transmission Mode of Compound Employee API

Example (Transition Situation): One Single Employment Where

hiringNotCompleted Changes from True to False

Snapshot

Person Person1: PersA
Employment Employment1: EmplA (with hiringNotCompleted =
true)

Current

Person Person1: PersB
Employment Employment1: EmplB (with hiringNotCompleted =
false)

Delta with hiringNotCompleted = false

Person Insert for Person1: PersB
Employment Insert for Employment1: EmplB (with
hiringNotCompleted = false)

Delta without hiringNotCompleted condition

Person Change for Person1: PersA > PersB
Employment Change for Employment1: EmplA (with
hiringNotCompleted = true) > EmplB (with
hiringNotCompleted = false)

Example (Transition Situation): Multiple Employments Where

hiringNotCompleted Changes from True to False For One Employment

Snapshot

Person Person1: PersA
Employment Employment1: EmplA1 (with hiringNotCompleted =
false)
Employment2: EmplA2 (with hiringNotCompleted =
true)

Current

Person Person1: PersB
Employment Employment1: EmplB1 (with hiringNotCompleted =
false)

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Using the Delta Transmission Mode of Compound Employee API PUBLIC 19

Employment2: EmplB2 (with hiringNotCompleted =
false)

Delta with hiringNotCompleted = false

Person Change for Person1: PersA > PersB
Employment Change for Employment1: EmplA1 > EmplB
Insert for Employment2: EmplB2 (with
hiringNotCompleted = false)

Delta without hiringNotCompleted condition

Person Change for Person1: PersA > PersB
Employment Change for Employment1: EmplA1 > EmplB
Change for Employment2: EmplA2 (with
hiringNotCompleted = true) > EmplB2 (with
hiringNotCompleted = false)

Special Handling When employment_information Segment Isn't Requested

A special handling of the delta calculation is required when the employment_information segment isn't contained in the list of selected segments.

If the employment of a person has changed from hiringNotCompleted = true to hiringNotCompleted = false, an INSERT action must be done for the person if this is the only employment. If there’s another employment, which was replicated earlier, a CHANGE or NO_CHANGE action is required.

 Note

If there’s no change in any of the requested segments, but the employment (that's not requested) was
changed, the result contains this person with the following log entry:
The employee has changed since the last replication on ..., however, no data was
returned because the changes are not relevant

2.2.5 Sorting by Start Date in the Where Expression

Time slices of effective-dated objects in the response are by default sorted in descending order by start date.

This means that the newest time slice is always the first in the response. Semantic keys and sequence numbers are also considered in sorting.

20 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Using the Delta Transmission Mode of Compound Employee API

The Compound Employee API supports ascending and descending sorting by start date for effective-dated entities. Add the following expression to the WHERE clause:

 Code Syntax

<queryString>
SELECT person, personal_information, address_information,
employment_information, job_information
FROM CompoundEmployee
ORDER BY start_date ASC / DESC
</queryString>

Table 7: Syntax of ORDER BY Expressions

This syntax... Leads to this sorting order of effective-dated entities...
ORDER BY start_date DESC descending
ORDER BY start_date ASC ascending
ORDER BY start_date ascending

2.2.6 Query Parameters

The tag contains parameters that control the behavior of the API.

Each tag consists of a parameter name and one or more values.

 Code Syntax

<urn:param>
<urn:name>parameter name</urn:name>
<urn:value>parameter values</urn:value>
</urn:param>

Parameter values are case insensitive and are considered as long as the spelling is correct.

Table 8: Query Parameters and Their Meanings

Query Parameter Description
queryMode Must be used to switch on and to use delta transmission
delta Parameter value to enable delta transmission
periodDelta Parameter value to enable period-based delta transmission
maxRows The maximum number of rows to be returned by the query
call
startingRow The number of the first row to be returned by the call. For ex­
ample, if startingRow is 3, the first two rows are skipped
externalKeyMapping Can be used to return object keys that originate from an ex­
ternal system

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Using the Delta Transmission Mode of Compound Employee API PUBLIC 21

Query Parameter Description
costCenter If specified, the API returns the value of field
EXTERNAL_OBJECT_ID of the cost center MDF object in­
stead of the external code
resultOptions Can be used to switch between different options on how
much data will be returned in the response
changedSegmentsOnly If specified, the API returns only changed segments with an
action code not equal to No Change in delta transmission.
changedFieldsOnly If specified, the API returns only changed fields of a changed
segment in delta transmission. You have to combine this pa­
rameter value with the changedSegmentsOnly parame­
ter value.
isNotFirstQuery The parameter value is only supported in period-based delta
transmission and in combination with the fromDate and
toDate select parameter.
extendedConsistencyChecks If specified during delta transmission, the API conducts ad­
ditional validations for dates of time slices. It throws an error
for affected employees in cases of overlapping time slices or
gaps between time slices where no gaps are allowed. For the
affected employees, a log entry is returned that has the se­
verity ERROR.
renderPreviousTags If specified, the way that previous values are exposed in the
response message is changed. The API returns previous val­
ues in a separate tag and no longer in mixed data types.

 Note

In Dell Boomi AtomSphere, in a SuccessFactors Operation , if you use the resultOptions parameter in the
SFAPI Parameters field, you need to concatenate the parameter values using the plus sign (+).

For example: resultOptions=changedSegmentsOnly+changedFieldsOnly

2.2.7 Controlling Parameters for Delta Transmission

You can use these parameters to control Compound Employee API delta transmission.

Delta transmission needs be enabled and requires always a date/time indication for the last synchronization as part of the Where clause when calling the Compound Employee API.

 Code Syntax

FROM CompoundEmployee
WHERE ( last_modified_on > to_datetime(LastModifiedDate)

For both delta transmission modes, the query parameter queryMode and value delta needs to be passed to run the API in delta transmission mode.

22 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Using the Delta Transmission Mode of Compound Employee API

 Code Syntax

<urn:param>
<urn:name>queryMode</urn:name>
<urn:value>delta</urn:value>
</urn:param>

or

 Code Syntax

<urn:param>
<urn:name>queryMode</urn:name>
<urn:value>periodDelta</urn:value>
</urn:param>

To indicate the period for period-based delta transmission, the parameter couple fromDate ... toDate is required as part of the Where clause together with the last_modified_on date when calling the API. This period couple parameter needs to be passed with an AND operator in the Where clause. From selection point of view, employees need to match either the last_modified_on or the period criterion in order to get selected.

 Code Syntax

FROM CompoundEmployee
WHERE ( last_modified_on > to_datetime(LastModifiedDate)
AND fromDate = to_date(FromDate,'YYYY-MM-DD')
AND toDate = to_date(ToDate,'YYYY-MM-DD') )

 Note
If you have already been using period-based delta transmission with queryMode value delta before Q3
2016, you have to change the value to periodDelta in Q4 2016 or Q1 2017, or else the API will error out
once the transition phase is over.

Parameter changedSegmentsOnly [page 23 ]
Consumers who are only interested in changed segments can call the Compound Employee API delta
mode with the parameter changedSegmentsOnly.
Parameter Value isNotFirstQuery [page 24 ]
Use the isNotFirstQuery parameter value to avoid duplicates.

2.2.7.1 Parameter changedSegmentsOnly

Consumers who are only interested in changed segments can call the Compound Employee API delta mode with the parameter changedSegmentsOnly.

Delta transmission can be used in two different modes. In standard mode, the complete history for an employee for all requested segments is returned. Such a query response XML includes action code information to indicate which data has changed and for which information no change has happened. The advantage is that the consumer receives complete information about all employee records when using effective-dated delta

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Using the Delta Transmission Mode of Compound Employee API PUBLIC 23

transmission, but receives changes indicated from the action code. This is useful in situations where the consumer must process information although it has not changed in Employee Central.

Example

The change of a field in the Job Information segment (for example, change of legal entity, country or pay group or the termination and rehire of the employee) may make it necessary to recreate the employee with all its data. In such a case, it is beneficial to the consumer that person-specific data such as address, names, and so on is sent with the query response even though this data has not changed.

 Note
For period-based delta transmission, only the unchanged segments are returned that intersect with the
given period.

To request changed segments only, call the delta mode with the parameter changedSegmentsOnly:

<urn:param>
<urn:name>resultOptions</urn:name>
<urn:value>changedSegmentsOnly</urn:value>
</urn:param>

If this parameter is passed using the query string, the Compound Employee API filters out the segments with the action code NO CHANGE, so that only INSERT, CHANGE, and DELETE information is communicated. However, the hierarchical structure is considered. In case there is a change on a sub-segment, the unchanged super-segment is returned as well.

<employment_information>
<action>NO CHANGE</action>
...
<job_information>
<action>CHANGE</action>
...
<end_date>9999-12-31</end_date>
...
<start_date>2014-05-01</start_date>
</job_information>
<employment_information>

2.2.7.2 Parameter Value isNotFirstQuery

Use the isNotFirstQuery parameter value to avoid duplicates.

The period-based delta transmission can be used in two different ways. The standard is to get information about employees with effective-dated objects effective during the given period. In this case, the effective-dated objects are replicated with the action code INSERT or CHANGE since the Compound Employee API assumes that these are not yet replicated. To avoid duplicates and to identify real changes happening within the period, the Compound Employee API can be executed applying parameter resultOptions with value isNotFirstQuery, for example, in a “multiple replications per payroll period” scenario.

24 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Using the Delta Transmission Mode of Compound Employee API

Example

Period-based delta transmission can be used to replicate data for such a payroll period use case, where an extraction of data is triggered multiple times. In this scenario, data is replicated once it becomes effective for the period, for example, a new salary. Changes of the data are replicated in subsequent runs where only corrections in the same period to the payroll system are sent, such as corrections of accidently entered amounts for wage increases.

(^) urn:param urn:nameresultOptions</urn:name> urn:valueisNotFirstQuery</urn:value> </urn:param> In case of parameter value isNotFirstQuery, the Compound Employee API assumes the period matching effective-dated objects as already replicated and calculates deltas between current and snapshot image. Action codes are therefore also INSERT, CHANGE or DELETE, depending on the state of data that is already replicated.

Here's what the query response of the Compound Employee API call looks like.

The query response has the following properties:

● sfobject: List of employees with sub-entities, returned as hierarchical XML
● numResult: Number of top-level results
● hasMore: Indicator if more results are available
● querySessionId: Query session ID for paging

The query response follows the current Employee Central data model by building a hierarchically structured XML. The names of the sub-structures are derived from the underlying database tables and SAP SuccessFactors entity names. The leaf elements below are named according to HRIS field metadata (HRIS- field id or HRIS-field name) or MDF object instance name.

The Compound Employee API returns employees (persons with employment) only. Persons without employment are excluded from extraction and not returned. This means that technical users (admin users) and employee dependents are not returned as sfobject by the API. But dependents are considered as a sub- element of employees.

Query Response for Effective-Dated and Period-Based Delta Transmission [page 26 ]
The query response of Compound Employee API has some specifics regarding effective-dated and
period-based delta transmission.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Using the Delta Transmission Mode of Compound Employee API PUBLIC 25

2.3.1 Query Response for Effective-Dated and Period-Based

Delta Transmission

The query response of Compound Employee API has some specifics regarding effective-dated and period- based delta transmission.

In effective-dated delta transmission, the Compound Employee API selects all employees that were changed since the last synchronization, determines the snapshot image and the current image, and compares both images to calculate the delta. The response contains the calculated changes independent on whether objects in the past or if future dated objects were affected. Therefore, the consumer needs to be able to deal with effective dated objects and their time slices.

Figure 6: Calculation of Delta for Effective-Dated Delta Transmission

In period-based delta transmission, the Compound Employee API considers not only retroactive changes but also employees for which changes become effective in the provided period. But, changes are ignored, that become effective after the period.

In period-based delta transmission, the following criteria are considered to determine relevant employees for selection:

● Time slices starting within the provided period (like 3rd Personal Info time slice in figure) or
● Changed time slices starting before the period (like 2nd Job Info time slice in figure) or
● Changes of not effective dated entities

26 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Using the Delta Transmission Mode of Compound Employee API

Figure 7: Selection of Employees in Period-Based Delta Transmission

For the selected employees Compound Employee API returns the following relevant data

● All time slices that intersect with the provided period (see 2nd and 3rd Personal Info time slice and 3rd Job
Info time slice in figure)
● All time slices that start before the provided period and were changed (see 2nd Job Info time slice in figure)
● All changed not effective dated entities

Figure 8: Data of Employees Replicated when Using Period-Based Delta Transmission

Not effective-dated objects such as national IDs or email are returned in both kinds of delta transmissions, if these are changed after the given last_modified_on timestamp for the last replication.

In the example below, a delta transmission response of Compound Employee API is shown, in which an employee is returned who married on June 1, 2014.

 Sample Code

<person>
<action>NO CHANGE</action>
<created_by>root</created_by>
<created_on_timestamp>2014-05-14T07:20:55.000Z</created_on_timestamp>
<last_modified_by>root</last_modified_by>
<last_modified_on>2014-05-14T07:20:55.000Z</last_modified_on>
<last_saved_on>2014-05-14T07:21:02.793Z</last_saved_on>
<logon_user_id>261</logon_user_id>
<logon_user_is_active>true</logon_user_is_active>
<logon_user_name>261</logon_user_name>
<person_id>1180</person_id>
<person_id_external>261</person_id_external>
<personal_information>
<action>CHANGE</action>
<created_by>root</created_by>
<created_on_timestamp>2014-05-14T07:20:56.000Z</
created_on_timestamp>
<end_date>9999-12-31</end_date>
<first_name>Steve</first_name>

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Using the Delta Transmission Mode of Compound Employee API PUBLIC 27

<gender>M</gender>
<last_modified_by>root</last_modified_by>
<last_modified_on>2014-05-15T06:41:58.000Z</last_modified_on>
<last_name>Delta</last_name>
<last_saved_on>2014-05-15T06:41:58.824Z</last_saved_on>
<marital_status>
M
<previous>S<previous>
</marital_status>
<start_date>2014-05-01</start_date>
</personal_information>
</person>

Highlighted fields are:

● The action code for the not effective-dated person segment, which is not changed. Therefore, it is set to
NO CHANGE.
● The action code for the effective-dated personal information segment, which is set to CHANGE because of
the change in marital status from single (S) to married (M).
● The marital status showing the new value (M) and the previous value (S).

The delta transmission mode of Compound Employee API supports some action codes.

Table 9: Supported Action Codes

Action Code Description
INSERT An INSERT is communicated if a new record is created. For
example, when an employee is hired, all segments are re­
turned with action code INSERT.
CHANGE CHANGE is sent if an existing record has been modified. For
example, the amount of a bonus has been adjusted.
DELETE DELETE means that a record has been deleted completely
(for example, direct deposit information has been removed).
NO CHANGE NO CHANGE indicates that there were no relevant changes
on the exposed attributes of the segment since the last repli­
cation. In case a segment is effective dated, several instan­
ces of this segment might be in the response and each can
have a different action code. In cases where one instance
has the action code NO CHANGE, this means that in the
timeframe of this instance no differences exist compared to
the data status at the last replication.

The action codes are applied to effective-dated segments (like personal_information) as well as to non- effective-dated entities (such as national_id_card). In case of effective-dated segments, the consumer should be aware that the action code does not always resemble the action that has been performed on the UI.

28 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Using the Delta Transmission Mode of Compound Employee API

Example

An employee changes their job title on June 1. This means that a second job slice is created starting from June 1 and that the first job slice is delimited. In this case, the second job slice is not communicated with the action code INSERT, but with the action code CHANGE. The reason is that job data for the employee existed since the hire date of the employee. The second job slice only replaces the data records of the original hire job slice. Therefore, it is a CHANGE.

In case a field has been changed since the last modified date, a subelement called previous is added to the field.

While the field itself contains the current value of the field, the previous element shows which content the field had before the change.

Three data constellations are possible leading to three different types of Compound Employee API responses:

● Before the last modified date, no information existed about the employee’s marital status. In the
meantime, the marital status was changed to Single (S).

 Sample Code

<marital_status>
S
<previous/>
</marital_status>

● Before the last modified date, the employee’s marital status was Single (S). In the meantime, the marital
status was changed to Married (M).

 Sample Code

<marital_status>
M
<previous>S<previous>
</marital_status>

● Before the last modified date, the employee’s marital status was Married (M). In the meantime, the marital
status information was deleted.

 Sample Code

<marital_status>
<previous>M<previous>
</marital_status>

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Using the Delta Transmission Mode of Compound Employee API PUBLIC 29

Job information and compensation information require special treatment because they contain the information about the business events, for example, a newly-hired employee.

Whenever a new slice of job information or compensation information is created, this is triggered by a certain business event. Therefore, each slice of job and compensation contains event information.

Typical business events in Employee Central include:

● Hire
● Promotion
● Leave
● Job change
● Termination
● Rehire

Many of the business events are also important events for the consumer. Based on the events, different processes might be triggered on the consumer side. Also different exchange formats such as HR-XML position the business event as a central entity.

Therefore, in delta mode, the business events contained in job and confirmation slices are transferred in their own segments. They are non-effective-dated but have an event date that corresponds to the start date of the underlying job or compensation time slice.

It is possible that several events happen on the same date. In this case, several concurrent time slices are created that differ in their sequence number. The time slices that do not have the highest sequence number do not cover the whole time period but have an end date that equals to their start date. In the example below, the second time slice has three records with different business events. Each record has a transaction sequence number. The record with the highest sequence number contains the business data for the time slice. That's the reason why, in standard delta mode, only the job data or compensation data of the time slice with the highest sequence number is considered.

Figure 9: Example of Time Slices

The next sections describe the event handling in detail on basis of job information. Note that the handling of the events of compensation information is mainly the same.

Insert New Job Time Slice with Multiple Events [page 31 ]
This is the event handling when multiple time slices are inserted with the same start date and different
events.
Insert New Job Time Slice to Existing Time Slice [page 32 ]
This is the event handling when mulitple time slices are with the same start date and different events
are added to an already existing slice with the same start date.
Change Event of a Concurrent Time Slice [page 33 ]
This is the event handling when an event in one of the concurrent time slices is changed.
Change Not Event Related Job Field of a Concurrent Time Slice [page 34 ]

30 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Using the Delta Transmission Mode of Compound Employee API

This is the event handling when a not event-related field in one of the concurrent time slices is changed.
Delete Job Time Slice (Active) [page 35 ]
This is the event handling when the record with the highest transaction sequence number of a time
slice is deleted.
Delete Job Time Slice (In Between) [page 36 ]
This is the event handling when the record of a time slice is deleted which does not have the highest
transaction sequence number.

2.6.1 Insert New Job Time Slice with Multiple Events

This is the event handling when multiple time slices are inserted with the same start date and different events.

The delta processor calculates the delta for job information on basis of the records with the highest sequence number for each time slice. The job events are calculated for each start date by comparing the events valid on this start date in the snapshot data and the current data.

Snapshot Data

Figure 10: Snapshot

Current Data

Figure 11: Current

Delta to Be Transferred: Job

Figure 12: Job

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Using the Delta Transmission Mode of Compound Employee API PUBLIC 31

Delta to Be Transferred: Job

Figure 13: Job Events

2.6.2 Insert New Job Time Slice to Existing Time Slice

This is the event handling when mulitple time slices are with the same start date and different events are added to an already existing slice with the same start date.

Snapshot Data

Figure 14: Snapshot

Current Data

Figure 15: Current

Delta to Be Transferred: Job

Figure 16: Job

Delta to Be Transferred: Job Events

Figure 17: Job Events

32 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Using the Delta Transmission Mode of Compound Employee API

2.6.3 Change Event of a Concurrent Time Slice

This is the event handling when an event in one of the concurrent time slices is changed.

Snapshot Data

Figure 18: Snapshot

Current Data

Figure 19: Current

Delta to Be Transferred: Job

Figure 20: Job

Delta to Be Transferred: Job Events

Figure 21: Job Events

On the UI, this might be a simple change of job field. However, from a business perspective, it means that the employee does not go on leave. Therefore, an explicit delete must be sent for the Leave event.

The job data change is not communicated because the Compound API only sends job data of the concurrent job slice with the highest sequence number.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Using the Delta Transmission Mode of Compound Employee API PUBLIC 33

2.6.4 Change Not Event Related Job Field of a Concurrent

Time Slice

This is the event handling when a not event-related field in one of the concurrent time slices is changed.

Snapshot Data

Figure 22: Snapshot

Current Data

Figure 23: Current

Delta to Be Transferred: Job

Figure 24: Job

Delta to Be Transferred: Job Events

Figure 25: Job Events

As the event has not been changed, all events are sent with action NO CHANGE. The job data change on C is not relevant in standard delta mode since only the job slice with the highest sequence number is considered.

34 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Using the Delta Transmission Mode of Compound Employee API

2.6.5 Delete Job Time Slice (Active)

This is the event handling when the record with the highest transaction sequence number of a time slice is deleted.

Snapshot Data

Figure 26: Snapshot

Current Data

Figure 27: Current

Delta to Be Transferred: Job

Figure 28: Job

The delta information indicates that the job data of time slice C is valid now.

Delta to Be Transferred: Job Events

Figure 29: Job Events

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Using the Delta Transmission Mode of Compound Employee API PUBLIC 35

2.6.6 Delete Job Time Slice (In Between)

This is the event handling when the record of a time slice is deleted which does not have the highest transaction sequence number.

Snapshot Data

Figure 30: Snapshot

Current Data

Figure 31: Current

Delta to Be Transferred: Job

Figure 32: Job

Delta to Be Transferred: Job Events

Figure 33: Job Events

36 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Using the Delta Transmission Mode of Compound Employee API

Effective-dated delta transmission considers all changes that have happened from a given point in time.

The Compound Employee API query response contains all changes since that point in time happened for non- effective-dated and effective-dated entities including retroactive and future dated changes. Therefore this type of delta transmission is intended for consumers that are able to handle time slices and future dated information.

Use Cases for Effective-Dated Entities [page 37 ]
We differentiate time slice handling between effective-dated entities without semantic key (such as job
information) and effective-dated entities with semantic key (such as address information).
Example: Compensation and Pay Compensation Recurring [page 47 ]
Here's a complex example of delta calculation for compensation and pay compensation recurring.
Non-Effective-Dated Entities [page 48 ]
Take a look at delta transmission for non-effective-dated entities such as pay compensation non-
recurring, direct deposit, or national ID card.

We differentiate time slice handling between effective-dated entities without semantic key (such as job information) and effective-dated entities with semantic key (such as address information).

Time Slice Handling for Effective-Dated Entities Without Semantic Key [page 37 ]
Learn more about time slice handling in Compound Employee API for changes to effective-dated
entities without semantic key, such as job information or compensation.
Time Slice Handling for Effective-Dated Entities with Semantic Key [page 44 ]
Take a look at time slice handling in Compound Employee API for changes to effective-dated entities
with semantic key, such as address information.

3.1.1 Time Slice Handling for Effective-Dated Entities

Without Semantic Key

Learn more about time slice handling in Compound Employee API for changes to effective-dated entities without semantic key, such as job information or compensation.

These changes are always calculated against that historical state of the snapshot data of the employee.

Insertion of a Time Slice [page 38 ]
This is the handling when a new time slice is inserted.
Change of Values [page 40 ]

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Effective-Dated Delta Transmission PUBLIC 37

This is the handling when some values of an existing time slice were changed using Make Correction.
Deletion of a Time Slice [page 41 ]
This is the handling when a time slice is deleted.
Move of Start Date [page 42 ]
This is the handling when a time slice is moved to an earlier or a later point in time.

3.1.1.1 Insertion of a Time Slice

This is the handling when a new time slice is inserted.

A first time slice is added

Figure 34: Snapshot

Figure 35: Current

Figure 36: Delta to Be Transferred

The first time slice A is added, the snapshot data does not contain any time slice. The delta contains the time slice A with action INSERT.

A second time slice is added after the first time slice

Figure 37: Snapshot

Figure 38: Current

Figure 39: Delta to Be Transferred

38 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Effective-Dated Delta Transmission

The delta contains two time slices. The first time slice has the same values as before, but its end date is delimited to the start date of the new inserted time slice. Its action code is NO CHANGE since no values were changed. The second time slice has action code CHANGE because the values have changed from A to B in this time period. The CHANGE is returned because the object already existed and could only be changed.

A third time slice is added after the second time slice

Figure 40: Snapshot

Figure 41: Current

Figure 42: Delta to Be Transferred

The delta contains three time slices: The first time slice remains completely unchanged. The second time slice has the same values as before, only its end date is delimited to the start date of the new inserted time slice. For the first and the second time slice, the action code is NO CHANGE, since no values were changed. Only the third time slice has the action code CHANGE because the value changed from B to C in this time period.

A new time slice is inserted before the first time slice

Figure 43: Snapshot

Figure 44: Current

Figure 45: Delta to Be Transferred

The delta contains three time slices. The first time slice is the inserted time slice with values C and has action code INSERT. The other time slices are not changed and therefore have action code NO CHANGE.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Effective-Dated Delta Transmission PUBLIC 39

A new time slice is inserted after the first time slice

Figure 46: Snapshot

Figure 47: Current

Figure 48: Delta to Be Transferred

The delta contains three time slices. The first time slice has the same values as before, but its end date is delimited to the start date of the new inserted time slice. Its action code is NO CHANGE since no values were changed. The same applies to the third time slice, which remains completely unchanged. Only the second time slice has action code CHANGE because the values have changed from A to C in this time period.

3.1.1.2 Change of Values

This is the handling when some values of an existing time slice were changed using Make Correction.

Variant 1: A single time slice is changed

Figure 49: Changing a Single Time Slice

The delta contains the first time slice with action code CHANGE and the new value B.

40 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Effective-Dated Delta Transmission

Variant 2: One of several time slices is changed

Figure 50: Changing One of Multiple Time Slices

The delta contains the first time slice with action code CHANGE and the new value C. The second time slice has action code NO CHANGE and the unchanged value B.

3.1.1.3 Deletion of a Time Slice

This is the handling when a time slice is deleted.

Variant 1: The first time slice is deleted

Figure 51: Deletion of First Time Slice

The deletion of the first time slice is transmitted as an explicit deletion with action code DELETE. The second time slice is not affected by the change and has action code NO CHANGE.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Effective-Dated Delta Transmission PUBLIC 41

Variant 2: A time slice after the first time slice is deleted

Figure 52: Deletion of Second Time Slice

The delta contains three time slices. The first time slice has the same values as before but its end date is delimited to the start date of the deleted time slice. Its action code is NO CHANGE since no values were changed. The same applies to the third time slice which remains completely unchanged. The second time slice has the same values as the first time slice but compared to the snapshot data the value changed from B to A. Therefore the second time slice has the action code CHANGE.

3.1.1.4 Move of Start Date

This is the handling when a time slice is moved to an earlier or a later point in time.

Start date is moved to earlier point in time

Variant 1: The start date of a time slice is modified to an earlier point in time and the values of the time slice have not changed

Figure 53: Earlier Start Date Without Data Changes

In the delta, the changed time slice is split into two time slices – one time slice for the period where the values have changed and one time slice for the period without changes.

42 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Effective-Dated Delta Transmission

Variant 2: The start date of a time slice is modified to an earlier point in time and the values of the time slice have changed

Figure 54: Earlier Start Date With Data Changes

Also in this case, the changed time slice is split into two time slices, but now both time slices have the action code CHANGE since the values have been changed in both time periods.

Move Start Date to Later Point in Time

Variant 1: The start date of the first time slice is modified to a later point in time and values have changed

Figure 55: Later Start Date of First Time Slice, With Data Changes

The delta contains three time slices. The first time slice has the start date of the original first time slice of the snapshot data and is delimited to the new start date of the changed time slice. Its action code is DELETE since the time period is no longer covered in the current data. The second time slice of the delta corresponds to the first time slice of the current data and has CHANGE as action code since the value changed from A to C. The third time slice is unchanged and has action code NO CHANGE.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Effective-Dated Delta Transmission PUBLIC 43

Variant 2: The start date of a time slice after the first time slice is modified to a later point in time and the values of the time slice have changed

Figure 56: Later Start Date of Second Time Slice, With Data Changes

The delta contains four time slices. The first time slice has the same values as before, but its end date is delimited to the start date of the second time slice of the snapshot data. Its action code is NO CHANGE since no values were changed. The same applies to the last time slice, which remains unchanged. The second time slice has the same values as the first time slice, but compared to the snapshot data the value changed from B to A. Therefore the second time slice has the action code CHANGE. The third time slice of the delta corresponds to the second time slice of the current data and has previous value B.

3.1.2 Time Slice Handling for Effective-Dated Entities with

Semantic Key

Take a look at time slice handling in Compound Employee API for changes to effective-dated entities with semantic key, such as address information.

The main difference compared to the effective-dated entities without semantic key is that each time slice can have several records with different semantic keys. For address information, for example, the sematic key is defined by the address type and country. A time slice can have multiple addresses of different types:

Figure 57: Example of Address Types

For such entities, we calculate the deltas for each semantic key and time slice.

The following entities are effective dated with semantic key:

Table 10: Effective-Dated Entities with Semantic Key

Entity Key
Person global info country

44 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Effective-Dated Delta Transmission

Entity Key
Home address address_type

country
Person relationship relationship_type

related_person_id

Pay component recurring pay_component
Job relation relationship_type

Change of Values [page 45 ]
This is the handling when some values of an existing time slice were changed.

3.1.2.1 Change of Values

This is the handling when some values of an existing time slice were changed.

Change a standard attribute of the address of type Vacation

Figure 58: Changing a Time Slice

In this example, the home address has not changed and therefore all records with this semantic key have the action code NO CHANGE. The vacation address was changed from VA to VB and therefore has the action code CHANGE.

Insert a new time slice with a different country

A new time slice with a different country is added for the address of address type Home.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Effective-Dated Delta Transmission PUBLIC 45

Figure 59: Inserting a Time Slice

In this example, a new time slice was inserted for the vacation address and the home address. Since the attributes of the vacation address were not changed in the new time slice, all records of the vacation address have the action code NO CHANGE. For the home address, the address data and specifically the country were changed in the new time slice. Since the country is part of the semantic key of the address, the delta calculation returns a delete of the previous address in the United States and an insert of the new address in Germany for the new time slice.

Insert a new time slice and remove a record

A new time slice is inserted, the record of the vacation address is removed, and the home address is changed in the new time slice.

Figure 60: Inserting a Time Slice and Removing an Existing Time Slice

In this case, the delta contains three time slices and each time slice has a record for the home address and a record for the vacation address. In the first and third time slice all records have the action code NO CHANGE. In the second time slice, the record of the home address has the action CHANGE since the value changed from HA to HC. The record of the vacation address has the action code DELETE since it was deleted in this time period.

46 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Effective-Dated Delta Transmission

Here's a complex example of delta calculation for compensation and pay compensation recurring.

In the example, the time slices of the snapshot data and the current data are completely different, which leads to a split of time slices in the delta.

Figure 61: Delta Calculation for Compensation and Pay Compensation Recurring

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Effective-Dated Delta Transmission PUBLIC 47

Take a look at delta transmission for non-effective-dated entities such as pay compensation non-recurring, direct deposit, or national ID card.

For such entities, the delta processor checks whether a record was inserted, changed, or deleted and extracts it with the corresponding action code. The records are identified by a sematic key which is defined for each entity:

Table 11: Semantic Keys for Non-Effective-Dated Entities

Entity Key
Direct Deposit deposit_type

routing_number
account_number
account_type
process_type
National ID Card country

card_type

Pay Compensation Non Recurring pay_component_code

pay_date
sequence_number
Email email_type
Phone phone_type

Changing attributes that are part of the semantic key always lead to the extraction of two records: One record with the action DELETE and the old semantic key and one record with the action code INSERT and the new semantic key. If, for example, the pay date of a non-recurring pay compensation is changed, the delta contains a record with the action code DELETE with the old pay date and a record with the action code INSERT and the new pay date.

48 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Effective-Dated Delta Transmission

Example: Delta Calculation for Change of Pay Compensation Non-Recurring

Figure 62: Changing Pay Compensation Non-Recurring

Example: Delta Calculation for Change of Key Field of Pay Compensation

Non-Recurring

Figure 63: Changing Key Field of Pay Compensation Non-Recurring

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Effective-Dated Delta Transmission PUBLIC 49

Period-based delta transmission of the Compound Employee API is for consumers that are not able to process effective-dated entities and future time slices.

Some typical scenarios for period-based delta transmission are:

● Monthly payroll processing, where the payroll provider is interested in data relevant for the current payroll
period and retroactive changes. Whereas future dated changes are considered in a future payroll run,
meaning they won't be added to the query response for the current period.
● Daily synchronization, where the consumer is interested in data that becomes effective on this day.

Period-based delta transmission enables consumers to retrieve only changed data that is relevant for the given evaluation period. The following kinds of changes are relevant for period-based delta transmission:

● Changes on effective-dated entities with a validity in the past or with a validity overlapping with the given
period and happened after the last synchronization
● Changes on effective-dated entities done in the past and where the start date falls into the given period
● Changes on non-effective-dated entities happened after the last synchronization

Changes on future dated records of effective-dated entities are not considered as long as their validity time frame is outside of the evaluation period.

The advantage for consumers of this approach is that only effective-dated entities are replicated that are relevant for the specified period or that include retro-active changes. Future dated changes are omitted in that feature. Future dated records of effective-dated entities will be replicated once the consumer calls the Compound Employee API for a period in which these changes become effective.

Enabling Period-Based Delta Transmission [page 50 ]
Period-based delta transmission can be enabled by providing the start date and the end date of the
period together with the date of the last synchronization when calling the Compound Employee API.
Use Cases for Period-Based Delta Transmission [page 53 ]
Here are some use cases showing the result of period-based delta transmission for different situations
and changes of effective-dated entities.

Period-based delta transmission can be enabled by providing the start date and the end date of the period together with the date of the last synchronization when calling the Compound Employee API.

As is usual for delta transmission, the last synchronization date must be adjusted with every call. Furthermore, the periods must not overlap, so with every call another period needs to be requested. Ensure that these periods are disjunctive and starting one after the other so that there are no gaps. The length of the period is not limited; it is even possible to do a daily synchronization using the same date as start and end date of the period.

In case the same period must processed several times, the parameter isNotFirstQuery must be used.

End Date Handling [page 51 ]

50 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Period-Based Delta Transmission

Since period-based delta transmission is designed for consumers that are not able to handle effective-
dated entities and future changes, it ignores end dates of time slices that are outside of the given
period.
Parameter isNotFirstQuery [page 51 ]
Use the isNotFirstQuery parameter to call the Compound Employee API multiple times for the
same period.

4.1.1 End Date Handling

Since period-based delta transmission is designed for consumers that are not able to handle effective-dated entities and future changes, it ignores end dates of time slices that are outside of the given period.

Therefore, no end dates for such time slices are contained in the Compound Employee API response. Only if a time slice of an effective-dated object ends before or within the period, the end date is also part of the response.

4.1.2 Parameter isNotFirstQuery

Use the isNotFirstQuery parameter to call the Compound Employee API multiple times for the same period.

Consumers commonly call the Compound Employee API once a period using period-based delta transmission to get data that becomes effective for that period. This makes sense in some cases especially when using a short period (for example, daily synchronization), but not for long periods (for example, monthly), where more regular replication of changes might be needed. For such scenarios, period-based delta transmission offers the additional parameter isNotFirstQuery, which enables the consumer to call the Compound Employee API multiple times for the same period. If this parameter is included in the request, the API only considers data changes that were entered into the system since the last synchronization date and that affect the provided period or the time before that period. Unchanged data, even if it becomes effective in the period, is not replicated anymore.

The following example shows the response of the Compound Employee API depending on the value of the parameter for a subsequent time slice effective in the period.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Period-Based Delta Transmission PUBLIC 51

Example: Parameter isNotFirstQuery is not included in the request

Figure 64: Request for Period Delta Transmission

In this case, the parameter isNotFirstQuery is set to false. Since the subsequent time slice becomes effective in the period, period-based delta transmission returns the subsequent time slice with the action code CHANGE and indicates that field value changed from the previous value A to the new value B.

52 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Period-Based Delta Transmission

Example: Parameter isNotFirstQuery is included in the request

Figure 65: Request for Period Delta Transmission

In this case, the parameter isNotFirstQuery is set to true. Since the subsequent time slice was not changed since the last API call, period-based delta transmission does not return the subsequent time slice, because the API assumes that this time slice was already replicated in a previous run to the consumer.

Here are some use cases showing the result of period-based delta transmission for different situations and changes of effective-dated entities.

The diagrams show the data as it was at the last synchronization run, the data how it is currently in the system, and the resulting delta time slices including their action codes. The use cases are based on an effective-dated entity such as job or personal information.

First Time Slice Starting After the Provided Period [page 54 ]
This is the handling when a new time slice starts after the provided period.
First Time Slice Effective in the Provided Period [page 55 ]
This is the handling when a time slice starts in the provided period.
Subsequent Time Slice Effective in the Provided Period [page 55 ]
This is the handling when a value changes in the provided period.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Period-Based Delta Transmission PUBLIC 53

Change of Time Slice Starting Before the Provided Period [page 57 ]
This is the handling when a time slice starting before the provided period is changed.
Change of Time Slice Starting and Ending Before the Provided Period [page 58 ]
This is the handling when a time slice starting and ending before the provided period is changed.
Change of Subsequent Time Slice Effective in the Provided Period [page 58 ]
This is the handling when a subsequent time slice becomes effective and is changed in the provided
period.
Deletion of Subsequent Time Slice Starting After the Provided Period [page 59 ]
This is the handling when a subsequent time starting after the provided period is deleted.

4.2.1 First Time Slice Starting After the Provided Period

This is the handling when a new time slice starts after the provided period.

The employee has a time slice starting after the period. There is no data before this time slice.

Figure 66: Request for Period Delta Transmission

Since there is no relevant data before and during the provided period, period-based delta transmission does not return any data for the entity. The data is not relevant for the consumer yet and will be replicated in a later synchronization run.

54 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Period-Based Delta Transmission

4.2.2 First Time Slice Effective in the Provided Period

This is the handling when a time slice starts in the provided period.

The employee has a time slice starting in the period and there is no previous time slice.

Figure 67: Request for Period Delta Transmission

Period-based delta transmission returns the time slice of the entity because it becomes effective in the provided period. The action code is INSERT since it is the first time for this effective-dated entity to be replicated to the consumer.

4.2.3 Subsequent Time Slice Effective in the Provided Period

This is the handling when a value changes in the provided period.

The employee already has data for the entity and a subsequent time slice becomes effective in the provided period. The difference between the two time slices is the value of a field that changes from A to B.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Period-Based Delta Transmission PUBLIC 55

Figure 68: Request for Period Delta Transmission

Period-based delta transmission returns the subsequent time slice because it becomes effective in the provided period. The action code is CHANGE since the first time slice with value A was already replicated to the consumer in the past. The consumer is now informed about the change of the value from A to B starting with the start date of the second time slice.

56 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Period-Based Delta Transmission

4.2.4 Change of Time Slice Starting Before the Provided

Period

This is the handling when a time slice starting before the provided period is changed.

Figure 69: Request for Period Delta Transmission

Period-based delta transmission returns the time slice because the change affects the provided period. The action code is CHANGE since the time slice with value A was already replicated to the consumer.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Period-Based Delta Transmission PUBLIC 57

4.2.5 Change of Time Slice Starting and Ending Before the

Provided Period

This is the handling when a time slice starting and ending before the provided period is changed.

Figure 70: Request for Period Delta Transmission

Period-based delta transmission returns the time slice because this is a retro-active change that needs to be replicated to the consumer even if it is not relevant for the given period. The action code is CHANGE because it was already replicated to the consumer in the past with value A. The changed field is exposed with new value C and previous value A.

4.2.6 Change of Subsequent Time Slice Effective in the

Provided Period

This is the handling when a subsequent time slice becomes effective and is changed in the provided period.

The employee already has data for the entity, and a subsequent time slice becomes effective in the provided period. Additionally the subsequent time slices have been changed since the last synchronization and a field was changed from value B to C.

58 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Period-Based Delta Transmission

Figure 71: Request for Period Delta Transmission

Period-based delta transmission returns the subsequent time slice because it becomes effective in the provided period. The action code is CHANGE since the first time slice with value A was already replicated to the consumer in the past. Since the subsequent time slice was not replicated to the consumer yet, the consumer is not aware of the previous value B that was valid at the last synchronization date. Therefore the consumer is informed about the change of the field value from A to C starting at the start date of the second time slice.

4.2.7 Deletion of Subsequent Time Slice Starting After the

Provided Period

This is the handling when a subsequent time starting after the provided period is deleted.

The employee has already data for the entity and there is a subsequent time slice starting after the provided period. The data has already been replicated in the past using period-based delta transmission and the subsequent time slice was ignored so far since it starts in future. Now the subsequent time slice is deleted.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Period-Based Delta Transmission PUBLIC 59

Figure 72: Request for Period Delta Transmission

In this case, period-based delta transmission does not return any data because the deleted subsequent time slice has not yet been replicated to the consumer. Since the consumer is not aware of the subsequent time slice, there is no need to get the information about the deleted time slice.

60 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Period-Based Delta Transmission

Here are some things you should know about how the delta transmission mode handles foundation objects.

External Codes [page 61 ]
Take a look at how external codes of foundation objects are handled.
Attributes of Effective-Dated Foundation Objects [page 61 ]
The Compound Employee API exposes a few additional fields from foundation objects.

Take a look at how external codes of foundation objects are handled.

The Compound Employee API always returns the current value of the external code. Consequently, changes of external codes will not be communicated by Compound Employee API delta mode. This also implies that the change of an external code never triggers an employee extraction.

The Compound Employee API exposes a few additional fields from foundation objects.

Table 12: Additional Foundation Object Fields Exposed in the API

Foundation Object Field
Event Reason Event

Employee Status
Payroll Event

Legal Entity Country
Cost Center External Object ID
Frequency Annualization Factor

Pay Frequency

Changes of these fields in the foundation objects are critical and should normally not happen. If the fields are changed either using Make correction or by inserting or deleting time slices, this will result in inaccurate calculation of previous values and/or inaccurate determination of action codes. The reason is that the API does

Implementing the Employee Central Compound Employee API in Delta Transmission Mode How Compound Employee API Delta Transmission Handles Foundation Objects PUBLIC 61

not consider the history of the foundation objects and therefore the calculation of the snapshot data will already be based on the new values of the foundation objects. Therefore the delta that results from the comparison of the snapshot data and the current data is not the real delta as it would be required for correct synchronization of Employee Central and the consumer system. In this case, manual intervention is required and the consumer system must be synchronized using full-transmission mode.

Current and Previous Values of Attributes [page 62 ]
The calculation of the current and previous values considers the current time slices of the foundation
objects.

5.2.1 Current and Previous Values of Attributes

The calculation of the current and previous values considers the current time slices of the foundation objects.

Time slices of effective-dated foundation objects might not exactly match the employee information time slices. Here are some examples of current and previous values calculated for effective-dated foundation objects with the attributes listed in the previous section.

Example 1

Figure 73: FO Event Reason Data Change and Attribute Payroll Event (PE) – Job Slices Before and After Change

Figure 74: Job Delta to Be Transferred

For the 2nd time slice, payroll event Y is communicated with X as previous value.

Example 2

Figure 75: FO Event Reason Data Change and Attribute Payroll Event (PE)

62 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
How Compound Employee API Delta Transmission Handles Foundation Objects

Figure 76: Job Slices Before Change

Figure 77: Job Slices After Change

Figure 78: Job Delta to Be Transferred

For the 2nd time slice, payroll event X is communicated with Y as previous value.

Example 3

Figure 79: FO Event Reason Data Change and Attribute Payroll Event (PE) – Job Slices Before and After Change

Figure 80: Job Delta to Be Transferred

For the 3rd time slice, the action code is CHANGE and payroll event X is communicated as current value and Y as previous value.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode How Compound Employee API Delta Transmission Handles Foundation Objects PUBLIC 63

Data Retention Management allows purging of transactional data and audit data independently, with different retention periods. That's why Compound Employee API must be able to handle situations where transactional data was purged and audit data is still there.

In delta transmission mode, Compound Employee API determines the retention times of transactional data for each employee and entity. All records that are outside of the respective retention period of the underlying entity will be ignored. Delta is only calculated for the records that are valid in the retention period. For the period in which data was purged and for the following day, no delta is calculated.

This means that the following changes will not be exposed by delta calculation:

● New records that are valid outside of the retention period
● Changed or deleted records that were re-created after purge and are valid outside of the retention period

The API also checks for each entity whether the provided last_modified_on date is within the audit retention time of the entity. If this is not the case for one or more entities, Compound Employee API returns an error for the employee, indicating that the provided date is not allowed.

 Example

 Sample Code

<log
<log_item>
<person_id>4711</person_id>
<person_id_external>Steve</person_id_external>
<code>COMPOUND_EMPLOYEE/EMPLOYEE_ERROR</code>
<severity>ERROR</severity>
<message_text>
Data for user id Steve can't be returned: Please see log
items for more information.
</message_text>
</log_item>
<log_item>
<person_id>4711</person_id>
<person_id_external>Steve</person_id_external>
<code>COMPOUND_EMPLOYEE/LAST_MODIFIED_ON_IN_AUDIT_PURGE_PERIOD</
code>
<severity>ERROR</severity>
<message_text>
The provided last_modified_on is outside of the audit
retention period of entity
"phone_information" that starts on
2016-12-30T23:00:00.000Z. Please use a last_modified_on
later than 2016-12-30T23:00:00.000Z.
</message_text>
</log_item>
</log>

The audit retention time of phone information is configured to 6 months. The audit purge was executed for
this employee on June 30, and the audit records of all phone information changes prior to December 30

64 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
How Compound Employee API Delta Transmission Reacts to Data Purge

were deleted. Compound Employee API will not support delta queries for this employee that have a
last_modified_on date before December 30.

In period delta mode, also the provided fromDate is validated against the retention periods of the requested entities. When the fromDate is within the purge period of an entity for an employee, Compound Employee API will return an error for this employee.

 Example

 Sample Code

<log>
<log_item>
<person_id>4711</person_id>
<person_id_external>Steve</person_id_external>
<code>COMPOUND_EMPLOYEE/EMPLOYEE_ERROR</code>
<severity>ERROR</severity>
<message_text>
Data for user id Steve can't be returned: Please see log
items for more information.
</message_text>
</log_item>
<log_item>
<person_id>4711</person_id>
<person_id_external>Steve</person_id_external>
<code>COMPOUND_EMPLOYEE/FROM_DATE_IN_PURGE_PERIOD</code>
<severity>ERROR</severity>
<message_text>
The provided fromDate is outside of the retention period of
entity “address_information” that
starts on 2017-01-01. Please use a fromDate later than or
equal to 2017-01-01.
</message_text>
</log_item>
</log>

Implementing the Employee Central Compound Employee API in Delta Transmission Mode How Compound Employee API Delta Transmission Reacts to Data Purge PUBLIC 65

Take a look at some limitations of the delta transmission mode.

Supported Segments [page 66 ]
Delta transmission is supported by many segments, but not by all of them.
Non-Supported Segments [page 67 ]
Delta transmission is not supported by these segments.
Personal Documents with Duplicate Semantic Key [page 68 ]
If the semantic keys of multiple documents are identical, the query mode delta for Personal Documents
cannot be calculated.
Emergency Contacts with Duplicate Semantic Key [page 68 ]
Deltas for Emgerency Contact can't be calculated if the semantic key of multiple contacts are identical.
Support of Specific Attributes [page 68 ]
Delta mode does not consider changes of attributes that are retrieved from table USERS_SYS_INFO.
Issues When Using Select Conditions [page 69 ]
You might get unexpected results in case the Compound Employee API consumer forwards data to
other systems according to specific employee attributes such as country, legal entity, employee class,
or pay group.

Delta transmission is supported by many segments, but not by all of them.

The reason is that for some segments no audit information is written or there is no according HRIS element model. In this case, no historic data can be read and consequently no delta can be calculated. Affected segments are all MDF segments (deduction_recurring, deduction_non_recurring, payment_information, alternative_cost_distribution) as well as accompanying_dependent.

Table 13: Segments (Not) Supporting Delta Transmission

Segment Supported
person X
personal_information X
personal_information_{country_code} X
address_information X
email_information X
phone_information X

66 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Limitations of Compound Employee API Delta Transmission

Segment Supported
person_relation X
employment_information X
global_assignment_information X
job_information X
alternative_cost_distribution –
alternative_cost_distribution_item –
compensation_information X
paycompensation_recurring X
paycompensation_non_recurring X
payment_information –
accompanying_dependent –
job_relation X
direct_deposit X
national_id_card X
deduction_recurring –
deduction_recurring_item –
deduction_non_recurring –
PaymentInformationV3 –
ItDeclaration –

Delta transmission is not supported by these segments.

Delta transmission does not support the MDF object PaymentInformation (the old payment information entity) and HRIS object accompanying_dependent.

 Note
accompanying_dependent is no longer supported by Compound Employee API at all.

One time deductions (or deduction_non_recurring ) are not supported in period-based delta transmission in the Q4 2015 release. Therefore, if one-time deductions are part of the Select statement for period-based delta transmission, processing of the query is terminated and an error message is given.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Limitations of Compound Employee API Delta Transmission PUBLIC 67

If the semantic keys of multiple documents are identical, the query mode delta for Personal Documents cannot be calculated.

In this case, the whole person will not be rendered and an appropriate error message will be returned.The semantic key of Personal Documents is made up of the following keys:

● country
● document_type
● document_number

Deltas for Emgerency Contact can't be calculated if the semantic key of multiple contacts are identical.

In this case, the whole person will not be rendered and an error message is returned. The semantic key of Emergency Contact comprises the key's name and relationship.

Delta mode does not consider changes of attributes that are retrieved from table USERS_SYS_INFO.

The following attributes are affected:

Table 14: Attributes Retrieved from USERS_SYS_INFO Table

Segment Attribute
person logon_user_id

logon_user_name
logon_user_is_active

employment_information direct_reports

For these attributes, the current value is always returned in the response message. Consequently, no delta information can be provided.

68 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Limitations of Compound Employee API Delta Transmission

You might get unexpected results in case the Compound Employee API consumer forwards data to other systems according to specific employee attributes such as country, legal entity, employee class, or pay group.

The Compound Employee API delta mode is optimized for a single consumer that processes all data (for example, a single payroll system). Deltas are communicated with regard to all data records of the employee. In general, the Compound Employee API supports filters (selection parameters) on different attributes, so that employees can be extracted based on their values for these attributes. However, these filters are always applied on the employee as a whole. In this chapter, some examples are given. Although they refer to specific attributes, the same facts apply to the other mentioned attributes as well.

Example 1

Figure 81: Job Slices Before Transfer to US

Figure 82: Job Slices After Transfer to US

The consumer might have called the delta transmission mode with the selection condition that the company territory code is USA. Before the transfer, Compound Employee API will not return any data. After the transfer, Compound Employee API will return the employee with all their data. However, only the second job slice will have action code CHANGE, the others job slices as well as all other segments will have the action code NO CHANGE.

In cases where USA payroll is handled by a system other than Germany payroll, this might lead to problems since the employee does not exist in the USA payroll system yet. Thus, the information NO CHANGE on segments like personal information and address information might be misleading.

Example 2

The constellation could be the same as above and the Compound Employee API is called in delta mode with the selection condition that the company territory code is Germany. Even though the employee does not work in Germany anymore, he is selected for the Germany payroll and deltas are communicated.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Limitations of Compound Employee API Delta Transmission PUBLIC 69

Example 3

Figure 83: Job Slices Before Change

Figure 84: Job Slices After Pay Group of Second Slice Was Changed

It might be the case that the consumer uses different payroll systems and processes employees according to the pay group they belong to. Employees belonging to pay group 1 might be handled in a different system than employees belonging to pay group 2. The Compound Employee API request will be formed accordingly. For example, the consumer processing employees of pay group 2 will call the Compound Employee API delta mode with pay group 2 as selection parameter.

The consumer responsible for pay group 2 will receive the employee because one of the job slices contains pay group 2 as value. However, after the change of the pay group information to pay group 1, the consumer will not receive the employee anymore. This might be problematic in case the consumer completely relies on the delta transmission. The payroll system for pay group 2 will not be informed that the employee’s pay group has changed and it will not be informed about future changes.

70 PUBLIC

Implementing the Employee Central Compound Employee API in Delta Transmission Mode
Limitations of Compound Employee API Delta Transmission

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.

Beta and Other Experimental Features

Experimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use the experimental features in a live operating environment or with data that has not been sufficiently backed up. The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.

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.

Gender-Related Language

We try not to use gender-specific word forms and formulations. As appropriate for context and readability, SAP may use masculine word forms to refer to all genders.

Implementing the Employee Central Compound Employee API in Delta Transmission Mode Important Disclaimers and Legal Information PUBLIC 71

http://www.sap.com/contactsap

© 2019 SAP SE or an SAP affiliate company. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice. Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. 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. Please see https://www.sap.com/about/legal/trademark.html for additional trademark information and notices.

THE BEST RUN