In this document we shall discuss the Compound Employee API (CE) and upcoming changes to the Last Modified field relative to the structure of API queries.
The Compound Employee API is a service used to extract employee data out of Employee Central. This API replicates employee master data from Employee Central to SAP systems, payroll systems and benefits systems.
- Currently the Compound Employee API allows the field last_modified_on and snapshot_date to be older than 3 months.
- With the H2 2020 release (second half of 2020), the Compound Employee API threshold will be restricted to 3 months. Any date further in the past will be excluded.
Find below the Current Schedule for Guardrail Restriction Application
|Date for Guardrail Restriction Application||Data Centers To Be Updated|
|Included in Production Release 2H 2021||DC11, DC17, DC18, DC19, DC22, DC23, DC26, DC40, DC41, DC47, DC48, DC49, DC50, DC55, and DC56|
|Scheduled for February 19, 2022*||DC60|
|Scheduled for April 1, 2022 *||DC4, DC8, DC10, DC44|
|Included in Production Release 1H 2022 *||DC2, DC12|
* Typical disclaimers apply
1. How to Migrate:
Customers will need to adjust the field(s) last_modified_on and snapshot_date in current integrations to be at most 3 months back in time.
This limitation is for every Compound Employee API mode (Full Transmission, Delta and Snapshot Mode).
The configuration effort to make this change is minimal, but it will require thorough testing to your downstream systems.
2. Example Queries:
2.1. Example of a Compound Employee API query with last_modified_on filter:
where last_modified_on > to_DateTime('2019-01-07T06:28:29Z')
2.2. Example of a Compound Employee API query with snapshot_date filter:
where snapshot_date > to_DateTime('2019-01-07T06:28:29Z')
2.3. Example of a Compound Employee API query in Delta mode:
where last_modified_on> to_DateTime('2019-01-07T06:28:29Z')
For integrations with a middleware, please adapt in the middleware the schedule time.
For more information on this topic, view this help.sap.com guide.
Troubleshooting: For more information on how Compound Employee API is working, view this help.sap.com guide.
3. Will it be possible to get Employees records even if they have not been changed between now and 3 months back?
Yes, this will be still possible. You can call Compound Employee API without the last_modifed_on filter and get all Employees.
4. What should I do if I want to get only employee data that is active since a certain date(for example 1 Year)?
You can use Compound Employee API with the effective_end_date filter. With this filter you get only the employee records that are active in the system from this date onwards.
5. How is the best practice to use Compound Employee API?
Best Practice is to use the initial load to replicate all employees to the target system (here you don’t need the last_modified_on filter).
After the successfully run you will only replicate the changes periodically (for example every day). For the subsequent replication of changes, the last_modified_on filter is used.
6. Why will the last_modified_on date be restricted to 3 months?
The last_modified_on is designed to keep the EC system and the target system in sync. This will happen periodically. Most use cases require a synchronization between 1 day and 1 months.
To date, we have found no use cases where a last_modified_on needs to be more than 3 months in the past.
7. I am using the last_modified_on filter with a date that is more than 3 months in the past, what should I do?
Using last_modified_on for more than 3 months would not return any employee data. You would see error message in API response.You can reduce the last_modified_on, so that the synchronization between EC and your target system will happen more often.
If you replicate daily, the last_modified_on needs to go back only 1 day. If you replicate monthly, the last_modified_on needs to go back 1 month.
8. Will any changes be lost if I reduce the last_modified_on?
No. For example if you run a daily job, you will then replicate all the changes that have been done since the last job.
If you use then the execution_timestamp from the previous Compound Employee API call for your next call, you will not lose any information.
Special note on Delta / Period Delta Mode:
With the restriction on Last Modified On & Snapshot Date, we limit the query to 3 months or less. For Initial Load in the Full Transmission, you can remove the Last Modified On filter and you get all Employees. In Delta or Period Delta you cannot remove the Last Modified On because it is mandatory.
To do an Initial Load in Delta or Period Delta we will allow the possibility to set last_modified_on > to_DateTime('2000-01-01T00:00:00Z') and then you can do the Initial Load with Delta or Period Delta.
This possibility will only work if you use exactly this date format ‘2000-01-01T00:00:00Z’. All other date formats will be validated and restricted.
For further questions or queries on this Compound Employee change, kindly post the same on the Community Forum dedicated to this enhancement here: Innovation Alert - Compound Employee API Change to Last Modified On & Snapshot Date – H2 2020
NOTE: After receiving feedback from our customers, we are enforcing the restrictions only on the Preview environment in the Second Half 2020 Release (2H 2020). We will be enforcing the restrictions on the Production environment in the Second Half 2021 (2H 2021) Production Release. For more information and registration details, please see https://community.successfactors.com/t5/Employee-Central-Resources-Blog/Compound-Employee-API-Change-to-Last-Modified-On-amp-Snapshot/bc-p/257983
Compound Employee, CE, last modified on, snapshot date, second half , KBA , LOD-SF-INT-CE , Compound Employee API , LOD-SF-INT , Integrations , Product Enhancement