When I got my first computer using the device needed expert skills. There was no mouse and you had to type instructions to make it do something. It was not ready for non-technical people. Today computers are used by everybody. The same was true for building integrations. To build integrations we used a middleware. Those tools required again expert knowledge and development skills. The SAP SuccessFactors Integrations Centre was introduced to change this. With this tool people without technical or coding skills can be enabled to build integrations!
In my previous post I mentioned that I want to write a series of blogs about APIs. Phil commented on this one and asked for an introduction into the Integration Center. I also mentioned that I like to use real scenarios or requirements before I explain the architecture and the final detailed solution. In this post I like to combine both. First give a quick intro into Integration Center and why this is a really cool tool and 2nd use a requirement from a customer scenario to explain calculated fields and calculated filters in the integration center
I like to start with an overview to explain what is possible with this tool. I also like to mention a few things which you cannot build with it and where a cloud middleware such as SAP Integration Suite is the better option.
In general an integration in the integration center needs a source to read and a target to write. Each arrow in the picture below shows which combinations between source and target are possible. In addition, it shows using orange color which protocols are possible and in blue which data format the protocols are supporting. Last it indicates in green if the integrations can be scheduled using a predefined time based schedule (S), e.g. daily or if it can be triggered by an intelligent service (I) or application (A) event.
As a result you can build integrations reading from SF and writing to a 3rd party but not the other way around. SFTP on the other side can be used for both source and target. And in general either source or target has to be SuccessFactors.
Another important limitation is that there is no orchestration of multiple APIs possible. Reading from the source and writing into the target has to be on single API call. You can expand/navigate in SuccessFactors OData or have deep structures in JSON/XMLs but you can not combine two different APIs and mix or merge the results.
All functions and features are explained in our Integration Center documentation at help.sap.com. A quick overview of the capabilities is documented in our implementation design principle document called "SAP SuccessFactors Integrations Tools: Integration Center and SAP Cloud Platform Integration" which you can find on our customer community
While documentation is good it does not help that much with concrete scenarios and requirements. I'm a big fan of learning from examples and copy from them. There are templates provided on the SAP API Business Hub for different common integration scenarios, like Recruiting Management Background checks. Checking the SAP API Business Hub for SuccessFactors integrations before building an own custom integration should always be the first step. In case a custom integration in the Integration Center has to be build you will find a set of good examples in this community. I sorted them using the different integration types I mentioned in the picture above. Use those to copy and learn from:
SFTP to SF(inbound):
SF to SFTP event based (outbound):
SF to SFTP scheduled (outbound):
SuccessFactors to SuccessFactors
General Best Practices and Overview
New hires are created in SAP SuccessFactors Employee Central. Usually they are coming from a Recruiting or Onboarding process often weeks or months before the employee starts in the company. As part of the process the employee is being created with his personal, employment and compensation information. While the person is not yet an employee of the company the private email address is being used for communication and set as the primary email of the employee.
In order to ensure that the employee can also access his laptop or also other business systems the new hire information is being transferred to an Active Directory (AD) using an integration between the Employee Central System and the Active Directory. The active directory is taking care about creating the identity for the employee and provision it to all other system which require it. In addition the AD can also be used to generate an business email address, a user name and telephone numbers. This information will get passed back to the Employee Central system.
Employee Central supports writing of email addresses using the PerEmail OData API. A validation in this API ensures that only one email address can be set as primary. As a result, to write the business email address as the primary one when there is already a primary email address of type private the API has to toggle both email types in one request. An attempt to write the business email address as the primary one with providing the private email address set to not primary will result in an error.
This behavior of the API requires a consumer to read the private email address first, change the primary flag to false and add the business email address with primary set to true and put both emails into one write API request. Unfortunately some Active Directories do not support this orchestration of the API.
After the Active Directory has written the business email into Employee Central without setting the primary flag, we need a way to set the primary flag for the business email and revoke the primary flag from the private email before the new hire starts in the company.
The above logic should also work the same way if there is another non-business email type set to primary.
As soon as the business email is set to primary the primary flag should not get touched anymore even if the employee changes the primary flags at a later point in time again.
It should be configurable how many days before the new hire starts this process should kick in.
It should be possible to schedule this process after the point in time Active Directory has written back the business email.
All of this should be done without using any code or middleware.
The architecture below shows how we solve this using the build-in integration center of SAP SuccessFactors.
In a first steps the private email of the new hire is created as the primary email by the HR Admin or Manager in the system using the UI. As a result the new hire data will also be transferred to the Active Directory for further provisioning into other business systems. At this point in time he business email will get generated.
In a 2nd step the active directory writes back the business email as a non primary one. This process of writing back the email is usually a scheduled process which happens before the employee starts in the company.
Right after the time the write back of the email was scheduled the integration center is started and picks up all emails of new hires which start the next day. The primary flag of the business email for those employees is set to true and the private emails address primary flag is set to false.
The major part of the solution is the Integration Center. It uses the SuccessFactors OData APIs to read the email information and write it again. This roundtrip is one of the supported integration types of the integration center. The screenshot below shows this reading and writing of the email data. We are writing in incremental purge mode, which means we are just updating records from the read data and keeping other records untouched (in contrast to full purge mode which would delete email records for an employee which are not read before). As someone can see it is a simple one to one mapping with exception of the primary flag.
The primary flag is not mapped at all. It is a calculated field. And the logic for this field is pretty simple. When it is an business email address (code 8448) and the primary flag is false it should be changed to true and when it is not a business email address and the primary flag it true it should be changed to false:
Someone could think that this logic would result in undefined primary flags for all email types which are not primary and not of type business. But when we look at the filter to retrieve the data we will see that those records are not retrieved at all.
The filter of the OData API defines what is retrieved and processed by the integration center. In this case we have used two different filters. The first filter retrieves only employees which start at the company the next day:
It used the hire date of the employment (OData navigation from PerEmail) and compares it to now minus one day. Hence emails from employees are selected only if the hire date is tomorrow. This concept of selecting emails based on attributes of related entities following a navigation in OData is also called a deep filter. In this case we filter the emails based on the hire date of the employment.
But as mentioned before we also need a 2nd filter. We just want to have emails of type business email and the one other email type which has the primary flag set. For this we use a so called calculated filter. This filter is applied after the data has been retrieved from the OData API and filters further. This allows to filter out records in the Integration Center where OData does not support a filter natively.
The screenshot above shows the details of the filter. By setting the "Field Value" to "False" the corresponding record is filtered out. If not set to "False" the email record is processed. As someone can see if the primary flag is true and the email type is business we ignore the record because in the case there is nothing to, the business email is already the primary one. The "else" part filters out all emails which are not primary and not of type business email. As a result only two email records will pass, either a business email with primary flag set to false or a non-business email with primary flag set to true. This is why the calculated field for primary does not have to take care of emails which are not of type business and have set the primary flag to false because they are not selected here.
Finally the scheduling is set to daily direct after the schedule of the write back from the active directory:
The integration center can be used for many simple integration use cases, it requires no code or development skills, comes without any extra license costs and offers build in monitoring and alerting capabilities for integrations.
More information about the SAP SuccessFactors Integration Center and when to use it and when it is a better option to use a cloud middleware as offered in the SAP Integration Suite can be found in our SAP SuccessFactors implementation design principles documents. Check out the document "Developing Integrations in SuccessFactors: Integration Center and SAP Cloud Platform Integration" in the customer community here: https://community.successfactors.com/t5/Implementation-Design-Principles/ct-p/ImplementationDesignPr...
Right, there was one more promise in my blog post: Examples to copy from. Here is the whole flow to download and import into the Integration Center from GitHub:
https://github.com/d040159/Integration-Examples/blob/main/IntegrationCenter/Set%20primary%20flag%20o...
In my previous post I mentioned that I want to write a series of blogs about APIs. Phil commented on this one and asked for an introduction into the Integration Center. I also mentioned that I like to use real scenarios or requirements before I explain the architecture and the final detailed solution. In this post I like to combine both. First give a quick intro into Integration Center and why this is a really cool tool and 2nd use a requirement from a customer scenario to explain calculated fields and calculated filters in the integration center
Getting started with Integration Center
I like to start with an overview to explain what is possible with this tool. I also like to mention a few things which you cannot build with it and where a cloud middleware such as SAP Integration Suite is the better option.
In general an integration in the integration center needs a source to read and a target to write. Each arrow in the picture below shows which combinations between source and target are possible. In addition, it shows using orange color which protocols are possible and in blue which data format the protocols are supporting. Last it indicates in green if the integrations can be scheduled using a predefined time based schedule (S), e.g. daily or if it can be triggered by an intelligent service (I) or application (A) event.
As a result you can build integrations reading from SF and writing to a 3rd party but not the other way around. SFTP on the other side can be used for both source and target. And in general either source or target has to be SuccessFactors.
Another important limitation is that there is no orchestration of multiple APIs possible. Reading from the source and writing into the target has to be on single API call. You can expand/navigate in SuccessFactors OData or have deep structures in JSON/XMLs but you can not combine two different APIs and mix or merge the results.
All functions and features are explained in our Integration Center documentation at help.sap.com. A quick overview of the capabilities is documented in our implementation design principle document called "SAP SuccessFactors Integrations Tools: Integration Center and SAP Cloud Platform Integration" which you can find on our customer community
While documentation is good it does not help that much with concrete scenarios and requirements. I'm a big fan of learning from examples and copy from them. There are templates provided on the SAP API Business Hub for different common integration scenarios, like Recruiting Management Background checks. Checking the SAP API Business Hub for SuccessFactors integrations before building an own custom integration should always be the first step. In case a custom integration in the Integration Center has to be build you will find a set of good examples in this community. I sorted them using the different integration types I mentioned in the picture above. Use those to copy and learn from:
SFTP to SF(inbound):
- Cost Center: https://blogs.sap.com/2017/10/04/integration-center-design-your-inbound-to-successfactor-integration...
- Position Migration: https://blogs.sap.com/2020/08/29/how-to-migrate-position-data-by-using-integration-center/
SF to SFTP event based (outbound):
- New hire: https://blogs.sap.com/2018/03/26/near-real-time-processing-with-intelligent-services-and-integration...
- First Time Manager: https://blogs.sap.com/2020/07/12/intelligent-services-centre-and-integration-centre-to-trigger-inter...
SF to SFTP scheduled (outbound):
- Benefits: https://blogs.sap.com/2018/03/25/exporting-benefits-from-employee-center-using-integration-center-ed...
- Learning: https://blogs.sap.com/2017/07/02/integration-center-a-viable-and-flexible-alternative-for-lms-connec...
- Employee Master Data: https://blogs.sap.com/2019/04/04/how-to-send-employee-master-data-to-a-third-party-in-xml-format-usi...
SuccessFactors to SuccessFactors
- Update background elements or MDF with EC data: https://blogs.sap.com/2020/09/28/using-integration-center-and-or-intelligent-services-centre-to-upda...
- Automatic Update of Time Data: https://blogs.sap.com/2020/06/10/doing-cool-stuff-really-easily-with-successfactors-integration-cent...
General Best Practices and Overview
- Choosing the right starting Entity: https://community.successfactors.com/t5/API-and-Integration-Resources/Integration-Center-Choosing-th...
- When to use integration Center and when SAP Integration Suite: https://blogs.sap.com/2019/06/21/successfactors-integrations-tools-integration-center-and-sap-cloud-...
- Integration Center Step by Step Guide: https://blogs.sap.com/2020/04/14/create-your-first-integration-with-successfactors-integration-cente...
- Further Templates and Examples for Integration Center Definitions: https://api.sap.com/themes/SAPSF?searchterm=&filter=(Type%20eq%20(SuccessFactors%20Integration%20Cen...
Toggling Primary Flag for Business Email Type using Integration Center
New hires are created in SAP SuccessFactors Employee Central. Usually they are coming from a Recruiting or Onboarding process often weeks or months before the employee starts in the company. As part of the process the employee is being created with his personal, employment and compensation information. While the person is not yet an employee of the company the private email address is being used for communication and set as the primary email of the employee.
In order to ensure that the employee can also access his laptop or also other business systems the new hire information is being transferred to an Active Directory (AD) using an integration between the Employee Central System and the Active Directory. The active directory is taking care about creating the identity for the employee and provision it to all other system which require it. In addition the AD can also be used to generate an business email address, a user name and telephone numbers. This information will get passed back to the Employee Central system.
The Problem
Employee Central supports writing of email addresses using the PerEmail OData API. A validation in this API ensures that only one email address can be set as primary. As a result, to write the business email address as the primary one when there is already a primary email address of type private the API has to toggle both email types in one request. An attempt to write the business email address as the primary one with providing the private email address set to not primary will result in an error.
This behavior of the API requires a consumer to read the private email address first, change the primary flag to false and add the business email address with primary set to true and put both emails into one write API request. Unfortunately some Active Directories do not support this orchestration of the API.
The Requirement
After the Active Directory has written the business email into Employee Central without setting the primary flag, we need a way to set the primary flag for the business email and revoke the primary flag from the private email before the new hire starts in the company.
The above logic should also work the same way if there is another non-business email type set to primary.
As soon as the business email is set to primary the primary flag should not get touched anymore even if the employee changes the primary flags at a later point in time again.
It should be configurable how many days before the new hire starts this process should kick in.
It should be possible to schedule this process after the point in time Active Directory has written back the business email.
All of this should be done without using any code or middleware.
The Architecture
The architecture below shows how we solve this using the build-in integration center of SAP SuccessFactors.
In a first steps the private email of the new hire is created as the primary email by the HR Admin or Manager in the system using the UI. As a result the new hire data will also be transferred to the Active Directory for further provisioning into other business systems. At this point in time he business email will get generated.
In a 2nd step the active directory writes back the business email as a non primary one. This process of writing back the email is usually a scheduled process which happens before the employee starts in the company.
Right after the time the write back of the email was scheduled the integration center is started and picks up all emails of new hires which start the next day. The primary flag of the business email for those employees is set to true and the private emails address primary flag is set to false.
The Solution
The major part of the solution is the Integration Center. It uses the SuccessFactors OData APIs to read the email information and write it again. This roundtrip is one of the supported integration types of the integration center. The screenshot below shows this reading and writing of the email data. We are writing in incremental purge mode, which means we are just updating records from the read data and keeping other records untouched (in contrast to full purge mode which would delete email records for an employee which are not read before). As someone can see it is a simple one to one mapping with exception of the primary flag.
The primary flag is not mapped at all. It is a calculated field. And the logic for this field is pretty simple. When it is an business email address (code 8448) and the primary flag is false it should be changed to true and when it is not a business email address and the primary flag it true it should be changed to false:
Someone could think that this logic would result in undefined primary flags for all email types which are not primary and not of type business. But when we look at the filter to retrieve the data we will see that those records are not retrieved at all.
The filter of the OData API defines what is retrieved and processed by the integration center. In this case we have used two different filters. The first filter retrieves only employees which start at the company the next day:
It used the hire date of the employment (OData navigation from PerEmail) and compares it to now minus one day. Hence emails from employees are selected only if the hire date is tomorrow. This concept of selecting emails based on attributes of related entities following a navigation in OData is also called a deep filter. In this case we filter the emails based on the hire date of the employment.
But as mentioned before we also need a 2nd filter. We just want to have emails of type business email and the one other email type which has the primary flag set. For this we use a so called calculated filter. This filter is applied after the data has been retrieved from the OData API and filters further. This allows to filter out records in the Integration Center where OData does not support a filter natively.
The screenshot above shows the details of the filter. By setting the "Field Value" to "False" the corresponding record is filtered out. If not set to "False" the email record is processed. As someone can see if the primary flag is true and the email type is business we ignore the record because in the case there is nothing to, the business email is already the primary one. The "else" part filters out all emails which are not primary and not of type business email. As a result only two email records will pass, either a business email with primary flag set to false or a non-business email with primary flag set to true. This is why the calculated field for primary does not have to take care of emails which are not of type business and have set the primary flag to false because they are not selected here.
Finally the scheduling is set to daily direct after the schedule of the write back from the active directory:
Summary and Outlook
The integration center can be used for many simple integration use cases, it requires no code or development skills, comes without any extra license costs and offers build in monitoring and alerting capabilities for integrations.
More information about the SAP SuccessFactors Integration Center and when to use it and when it is a better option to use a cloud middleware as offered in the SAP Integration Suite can be found in our SAP SuccessFactors implementation design principles documents. Check out the document "Developing Integrations in SuccessFactors: Integration Center and SAP Cloud Platform Integration" in the customer community here: https://community.successfactors.com/t5/Implementation-Design-Principles/ct-p/ImplementationDesignPr...
Right, there was one more promise in my blog post: Examples to copy from. Here is the whole flow to download and import into the Integration Center from GitHub:
https://github.com/d040159/Integration-Examples/blob/main/IntegrationCenter/Set%20primary%20flag%20o...
- SAP Managed Tags:
7 Comments
| User | Count |
|---|---|
| 7 | |
| 4 | |
| 3 | |
| 2 | |
| 2 | |
| 2 | |
| 2 | |
| 2 | |
| 2 | |
| 2 |
