--- source_url: "https://learn.microsoft.com/en-us/entra/identity/app-provisioning/sap-successfactors-integration-reference" title: "Microsoft Entra ID and SAP SuccessFactors integration reference - Microsoft Entra ID | Microsoft Learn" mirrored_at: 2026-08-14T01:03:19.562Z host: learn.microsoft.com cited_in_42a: true mirror_canonical: "https://index.42a.ai/learn.microsoft.com/en-us/entra/identity/app-provisioning/sap-successfactors-integration-reference" --- > **Original source:** https://learn.microsoft.com/en-us/entra/identity/app-provisioning/sap-successfactors-integration-reference [Microsoft Entra user provisioning service](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/user-provisioning) integrates with [SAP SuccessFactors Employee Central](https://www.sap.com/products/hcm/employee-central-payroll.html) to manage the identity life cycle of users. Microsoft Entra ID offers three prebuilt integrations: - [SuccessFactors to on-premises Active Directory user provisioning](https://learn.microsoft.com/en-us/entra/identity/saas-apps/sap-successfactors-inbound-provisioning-tutorial) - [SuccessFactors to Microsoft Entra user provisioning](https://learn.microsoft.com/en-us/entra/identity/saas-apps/sap-successfactors-inbound-provisioning-cloud-only-tutorial) - [SuccessFactors Writeback](https://learn.microsoft.com/en-us/entra/identity/saas-apps/sap-successfactors-writeback-tutorial) This article explains how the integration works and how you can customize the provisioning behavior for different HR scenarios. Microsoft Entra also supports single-sign on to SuccessFactors. For more information, see [Microsoft Entra single sign-on (SSO) integration with SuccessFactors](https://learn.microsoft.com/en-us/entra/identity/saas-apps/successfactors-tutorial). ## Establishing connectivity Microsoft Entra provisioning service uses basic authentication to connect to Employee Central OData API endpoints. When setting up the SuccessFactors provisioning app, use the _Tenant URL_ parameter in the _Admin Credentials_ section to configure the [API data center URL](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/d599f15995d348a1b45ba5603e2aba9b/af2b8d5437494b12be88fe374eba75b6.html). To further secure the connectivity between Microsoft Entra provisioning service and SuccessFactors, add the Microsoft Entra IP ranges in the SuccessFactors IP allowlist: 1. Download the [latest IP Ranges](https://www.microsoft.com/download/details.aspx?id=56519) for the Azure Public Cloud. 2. Open the file and search for tag `AzureActiveDirectory`. 3. Copy all IP address ranges listed within the element _addressPrefixes_ and use the range to build your IP address restriction list. 4. Translate the CIDR values to IP ranges. 5. Log in to SuccessFactors admin portal to add IP ranges to the allowlist. Refer to SAP [support note 2253200](https://userapps.support.sap.com/sap/support/knowledge/2253200). You can now [enter IP ranges](https://answers.sap.com/questions/12882263/whitelisting-sap-cloud-platform-ip-address-range-i.html) in this tool. ## Supported entities For every user in SuccessFactors, Microsoft Entra provisioning service retrieves the following entities. Each entity is expanded using the OData API _$expand_ query parameter as outlined in the _Retrieval rule_ column. Some entities are expanded by default, while some entities are expanded only if a specific attribute is present in the mapping. # SuccessFactors Entity OData Node Retrieval rule 1 `PerPerson` `*root node*` Always 2 `PerPersonal` `personalInfoNav` Always 3 `PerPhone` `phoneNav` Always 4 `PerEmail` `emailNav` Always 5 `EmpEmployment` `employmentNav` Always 6 `User` `employmentNav/userNav` Always 7 `EmpJob` `employmentNav/jobInfoNav` Always 8 `EmpEmploymentTermination` `activeEmploymentsCount` Always 9 `User's manager` `employmentNav/userNav/manager/empInfo` Always 10 `FOCompany` `employmentNav/jobInfoNav/companyNav` Only if `company` or `companyId` attribute is mapped 11 `FODepartment` `employmentNav/jobInfoNav/departmentNav` Only if `department` or `departmentId` attribute is mapped 12 `FOBusinessUnit` `employmentNav/jobInfoNav/businessUnitNav` Only if `businessUnit` or `businessUnitId` attribute is mapped 13 `FOCostCenter` `employmentNav/jobInfoNav/costCenterNav` Only if `costCenter` or `costCenterId` attribute is mapped 14 `FODivision` `employmentNav/jobInfoNav/divisionNav` Only if `division` or `divisionId` attribute is mapped 15 `FOJobCode` `employmentNav/jobInfoNav/jobCodeNav` Only if `jobCode` or `jobCodeId` attribute is mapped 16 `FOPayGrade` `employmentNav/jobInfoNav/payGradeNav` Only if `payGrade` attribute is mapped 17 `FOLocation` `employmentNav/jobInfoNav/locationNav` Only if `location` attribute is mapped 18 `FOCorporateAddressDEFLT` `employmentNav/jobInfoNav/addressNavDEFLT` If mapping contains one of the following attributes: `officeLocationAddress, officeLocationCity, officeLocationZipCode` 19 `FOEventReason` `employmentNav/jobInfoNav/eventReasonNav` Only if `eventReason` attribute is mapped 20 `EmpGlobalAssignment` `employmentNav/empGlobalAssignmentNav` Only if `assignmentType` is mapped 21 `EmploymentType Picklist` `employmentNav/jobInfoNav/employmentTypeNav` Only if `employmentType` is mapped 22 `EmployeeClass Picklist` `employmentNav/jobInfoNav/employeeClassNav` Only if `employeeClass` is mapped 23 `EmplStatus Picklist` `employmentNav/jobInfoNav/emplStatusNav` Only if `emplStatus` is mapped 24 `AssignmentType Picklist` `employmentNav/empGlobalAssignmentNav/assignmentTypeNav` Only if `assignmentType` is mapped 25 `Position` `employmentNav/jobInfoNav/positionNav` Only if `positioNav` is mapped 26 `Manager User` `employmentNav/jobInfoNav/managerUserNav` Only if `managerUserNav` is mapped ## How full sync works Based on the attribute-mapping, during full sync Microsoft Entra provisioning service sends the following "GET" OData API query to fetch effective data of all active and terminated workers. Parameter Description OData API Host Appends https to the _Tenant URL_. Example: `https://api4.successfactors.com` OData API Endpoint `/odata/v2/PerPerson` OData $format query parameter `json` OData $filter query parameter `(personEmpTerminationInfoNav/activeEmploymentsCount ne null) and (lastModifiedDateTime le )` OData $expand query parameter This parameter value depends on the attributes mapped. Example: `employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav,phoneNav,emailNav,employmentNav/jobInfoNav/companyNav/countryOfRegistrationNav,employmentNav/jobInfoNav/divisionNav,employmentNav/jobInfoNav/departmentNav` OData customPageSize query parameter `100` Note During the full initial sync, both active and terminated workers from SAP SuccessFactors are fetched. For each SuccessFactors user, the provisioning service looks for an account in the target (Microsoft Entra ID / on-premises Active Directory) using the matching attribute defined in the mapping. For example: if _personIdExternal_ maps to _employeeId_ and is set as the matching attribute, then the provisioning service uses the _personIdExternal_ value to search for the user with _employeeId_ filter. If a user match is found, then it updates the target attributes. If no match is found, then it creates a new entry in the target. To validate the data returned by your OData API endpoint for a specific `personIdExternal`, update the `SuccessFactorsAPIEndpoint` in the API query with your API data center server URL and use a tool like cURL or Graph Explorer to invoke the query. If the "in" filter doesn't work, you can try the "eq" filter. ``` https://[SuccessFactorsAPIEndpoint]/odata/v2/PerPerson?$format=json& $filter=(personIdExternal in '[personIdExternalValue]')& $expand=employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav, phoneNav,phoneNav/phoneTypeNav,emailNav,employmentNav/jobInfoNav/businessUnitNav,employmentNav/jobInfoNav/companyNav, employmentNav/jobInfoNav/companyNav/countryOfRegistrationNav,employmentNav/jobInfoNav/costCenterNav, employmentNav/jobInfoNav/divisionNav,employmentNav/jobInfoNav/departmentNav,employmentNav/jobInfoNav/jobCodeNav, employmentNav/jobInfoNav/locationNav,employmentNav/jobInfoNav/locationNav/addressNavDEFLT,employmentNav/jobInfoNav/payGradeNav, employmentNav/empGlobalAssignmentNav,employmentNav/empGlobalAssignmentNav/assignmentTypeNav,employmentNav/jobInfoNav/emplStatusNav, employmentNav/jobInfoNav/employmentTypeNav,employmentNav/jobInfoNav/employeeClassNav,employmentNav/jobInfoNav/eventReasonNav ``` ## How incremental sync works After full sync, Microsoft Entra provisioning service maintains `LastExecutionTimestamp` and uses it to create delta queries for retrieving incremental changes. The timestamp attributes present in each SuccessFactors entity, such as `lastModifiedDateTime`, `startDate`, `endDate`, and `latestTerminationDate`, are evaluated to see if the change falls between the `LastExecutionTimestamp` and `CurrentExecutionTime`. If yes, then the entry change is considered to be effective and processed for sync. Here's the OData API request template that Microsoft Entra ID uses to query SuccessFactors for incremental changes. You can update the variables `SuccessFactorsAPIEndpoint`, `LastExecutionTimestamp` and `CurrentExecutionTime` in the request template use a tool like cURL or Graph Explorer to check what data is returned. Alternatively, you can also retrieve the actual request payload from SuccessFactors by [enabling OData API Audit logs](#enabling-odata-api-audit-logs-in-successfactors). ``` https://[SuccessFactorsAPIEndpoint]/odata/v2/PerPerson/$count?$format=json&$filter=(personEmpTerminationInfoNav/activeEmploymentsCount ne null) and ((lastModifiedDateTime ge datetimeoffset'' and lastModifiedDateTime le datetimeoffset'') or (personalInfoNav/startDate ge datetimeoffset'' and personalInfoNav/startDate le datetimeoffset'') or ((personalInfoNav/lastModifiedDateTime ge datetimeoffset'' and personalInfoNav/lastModifiedDateTime le datetimeoffset'') and (personalInfoNav/startDate le datetimeoffset'' and (personalInfoNav/endDate ge datetimeoffset'' or personalInfoNav/endDate eq null))) or (employmentNav/startDate ge datetimeoffset'' and employmentNav/startDate le datetimeoffset'') or ((employmentNav/lastModifiedDateTime ge datetimeoffset'' and employmentNav/lastModifiedDateTime le datetimeoffset'') and (employmentNav/startDate le datetimeoffset'' and (employmentNav/endDate ge datetimeoffset'' or employmentNav/endDate eq null))) (employmentNav/jobInfoNav/startDate ge datetimeoffset'' and employmentNav/jobInfoNav/startDate le datetimeoffset'') or ((employmentNav/jobInfoNav/lastModifiedDateTime ge datetimeoffset'' and employmentNav/jobInfoNav/lastModifiedDateTime le datetimeoffset'') and (employmentNav/jobInfoNav/startDate le datetimeoffset'' and (employmentNav/jobInfoNav/endDate ge datetimeoffset'' or employmentNav/jobInfoNav/endDate eq null))) or (phoneNav/lastModifiedDateTime ge datetimeoffset'' and phoneNav/lastModifiedDateTime le datetimeoffset'') or (emailNav/lastModifiedDateTime ge datetimeoffset'' and emailNav/lastModifiedDateTime le datetimeoffset'') or (personEmpTerminationInfoNav/latestTerminationDate ge datetimeoffset'' and personEmpTerminationInfoNav/latestTerminationDate le datetimeoffset'') or (employmentNav/userNav/lastModifiedDateTime ge datetimeoffset'' and employmentNav/userNav/lastModifiedDateTime le datetimeoffset'')) &$expand=employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav,phoneNav,emailNav,employmentNav/userNav/manager/empInfo,employmentNav/jobInfoNav/companyNav,employmentNav/jobInfoNav/departmentNav,employmentNav/jobInfoNav/locationNav,employmentNav/jobInfoNav/locationNav/addressNavDEFLT,employmentNav/jobInfoNav/locationNav/addressNavDEFLT/stateNav&customPageSize=100 ``` ## How pre-hire processing works This section explains how the SAP SuccessFactors connector processes pre-hire records (workers with hire date / start date in future). Let's say there is a pre-hire with employeeId "1234" in SuccessFactors Employee Central with start date on 1-June-2023. Let's further assume that this pre-hire record was first created either in Employee Central or in the Onboarding module on 15-May-2023. When the provisioning service first observes this record on 15-May-2023 (either as part of full sync or incremental sync), this record is still in pre-hire state. Due to this, SuccessFactors does not send the provisioning service all attributes (example: userNav/username) associated with the user. Only bare minimum data about the user such as `companyName`, `personIdExternal`, `firstname`, `lastname` and `startDate` is available. To process pre-hires successfully, the following pre-requisites must be met: 1. The `personIdExternal` attribute must be set as the primary matching identifier (joining property). If you configure a different attribute (example: userName) as the joining property then the provisioning service will not be able to retrieve the pre-hire information. 2. The `startDate` attribute must be available and its JSONPath must be set to either `$.employmentNav.results[0].startDate` or `$.employmentNav.results[-1:].startDate`. 3. The pre-hire record must be in one of the following states in Employee Central: 'active' (t), 'inactive' (f), or 'active\_external\_suite' (e). For details about these states refer to the [SAP support note 2736579](https://launchpad.support.sap.com/#/notes/0002736579). Note For a pre-hire who has no history with the organization, both the \[0\] and \[-1:\] index will work for `startDate`. For a pre-hire who is a re-hire or conversion, we cannot deterministically tell the order and this may cause certain rehire/converted workers to get processed on their actual start date. This is a known limitation in the connector. During full sync or incremental sync or on-demand provisioning, when the provisioning service encounters a pre-hire record, it sends the following OData query to SuccessFactors with "asOfDate" filter set to the startDate of the user (such as asOfDate=2023-06-01). ``` https://[SuccessFactorsAPIEndpoint]/odata/v2/PerPerson?$format=json&$ filter=(personIdExternal in '1234' and employmentNav/userNav/status in 't','f','e')&asOfDate=2023-06-01&$ expand=employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav,phoneNav,emailNav,employmentNav/userNav/manager/empInfo,employmentNav/jobInfoNav/companyNav,employmentNav/jobInfoNav/costCenterNav,employmentNav/jobInfoNav/divisionNav,employmentNav/jobInfoNav/departmentNav,employmentNav/ ``` If you are observing issues with pre-hire processing, you can use the above OData request format to query your SuccessFactors instance replacing the API endpoint, `personIdExternal` and `asOfDate` filter with values corresponding to your test scenario. ## Reading attribute data When Microsoft Entra provisioning service queries SuccessFactors, it retrieves a JSON result set. The JSON result set includes many attributes stored in Employee Central. By default, the provisioning schema is configured to retrieve only a subset of those attributes. To retrieve more attributes, follow the steps listed: 1. Browse to **Enterprise Applications** > **SuccessFactors App** > **Provisioning** > **Edit Provisioning** > **Attribute Mapping** page. 2. Select the **Advanced Options** dropdown and then select **Edit target User attributes**. 3. The **API expression** column in this view displays the JSONPath expressions used by the connector. ![API-Expression](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/media/sap-successfactors-integration-reference/jsonpath-api-expressions.png#lightbox) 4. You can either edit an existing JSONPath value or add a new attribute with a valid JSONPath expression to the schema. The next section provides a list of common scenarios for editing the JSONPath values. ## Handling different HR scenarios JSONPath is a query language for JSON that is similar to XPath for XML. Like XPath, JSONPath allows for the extraction and filtration of data out of a JSON payload. By using JSONPath transformation, you can customize the behavior of the Microsoft Entra provisioning app to retrieve custom attributes and handle scenarios such as rehiring, worker conversion and global assignment. This section covers how you can customize the provisioning app for the following HR scenarios: - [How Microsoft Entra provisioning integrates with SAP SuccessFactors](#how-microsoft-entra-provisioning-integrates-with-sap-successfactors) - [Establishing connectivity](#establishing-connectivity) - [Supported entities](#supported-entities) - [How full sync works](#how-full-sync-works) - [How incremental sync works](#how-incremental-sync-works) - [How pre-hire processing works](#how-pre-hire-processing-works) - [Reading attribute data](#reading-attribute-data) - [Handling different HR scenarios](#handling-different-hr-scenarios) - [Retrieving more attributes](#retrieving-more-attributes) - [Retrieving custom attributes](#retrieving-custom-attributes) - [Mapping employment status to account status](#mapping-employment-status-to-account-status) - [Handling worker conversion and rehiring scenarios](#handling-worker-conversion-and-rehiring-scenarios) - [Retrieving current active employment record](#retrieving-current-active-employment-record) - [Handling global assignment scenario](#handling-global-assignment-scenario) - [Handling concurrent jobs scenario](#handling-concurrent-jobs-scenario) - [Retrieving position details](#retrieving-position-details) - [Provisioning users in the Onboarding module](#provisioning-users-in-the-onboarding-module) - [Enabling OData API Audit logs in SuccessFactors](#enabling-odata-api-audit-logs-in-successfactors) - [Writeback scenarios](#writeback-scenarios) - [Supported scenarios for phone and email write-back](#supported-scenarios-for-phone-and-email-write-back) - [Enabling writeback with UserID](#enabling-writeback-with-userid) - [Unsupported scenarios for phone and email write-back](#unsupported-scenarios-for-phone-and-email-write-back) - [Next steps](#next-steps) ### Retrieving more attributes The default Microsoft Entra SuccessFactors provisioning app schema ships with [90+ predefined attributes](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/sap-successfactors-attribute-reference). To add more SuccessFactors attributes to the provisioning schema, use the steps listed: 1. Use the OData query to retrieve data for a valid test user from Employee Central. ``` https://[SuccessFactorsAPIEndpoint]/odata/v2/PerPerson?$format=json& $filter=(personIdExternal in '[personIdExternalValue]')& $expand=employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav, phoneNav,phoneNav/phoneTypeNav,emailNav,employmentNav/jobInfoNav/businessUnitNav,employmentNav/jobInfoNav/companyNav, employmentNav/jobInfoNav/companyNav/countryOfRegistrationNav,employmentNav/jobInfoNav/costCenterNav, employmentNav/jobInfoNav/divisionNav,employmentNav/jobInfoNav/departmentNav,employmentNav/jobInfoNav/jobCodeNav, employmentNav/jobInfoNav/locationNav,employmentNav/jobInfoNav/locationNav/addressNavDEFLT,employmentNav/jobInfoNav/payGradeNav, employmentNav/empGlobalAssignmentNav,employmentNav/empGlobalAssignmentNav/assignmentTypeNav,employmentNav/jobInfoNav/emplStatusNav, employmentNav/jobInfoNav/employmentTypeNav,employmentNav/jobInfoNav/employeeClassNav,employmentNav/jobInfoNav/eventReasonNav ``` 2. Determine the Employee Central entity associated with the attribute - If the attribute is part of _EmpEmployment_ entity, then look for the attribute under _employmentNav_ node. - If the attribute is part of _User_ entity, then look for the attribute under _employmentNav/userNav_ node. - If the attribute is part of _EmpJob_ entity, then look for the attribute under _employmentNav/jobInfoNav_ node. 3. Construct the JSON Path associated with the attribute and add this new attribute to the list of SuccessFactors attributes. - Example 1: Let's say you want to add the attribute `okToRehire`, which is part of `employmentNav` entity, then use the JSONPath `$.employmentNav.results[0].okToRehire` - Example 2: Let's say you want to add the attribute _timeZone_, which is part of _userNav_ entity, then use the JSONPath `$.employmentNav.results[0].userNav.timeZone` - Example 3: Let's say you want to add the attribute _flsaStatus_, which is part of _jobInfoNav_ entity, then use the JSONPath `$.employmentNav.results[0].jobInfoNav.results[0].flsaStatus` 4. Save the schema. 5. Restart provisioning. ### Retrieving custom attributes By default, the following custom attributes are predefined in the Microsoft Entra SuccessFactors provisioning app: - _custom01-custom15_ from the User (userNav) entity - _customString1-customString15_ from the EmpEmployment (employmentNav) entity called _empNavCustomString1-empNavCustomString15_ - _customString1-customString15_ from the EmpJobInfo (jobInfoNav) entity called _empJobNavCustomString1-empNavJobCustomString15_ Let's say, in your Employee Central instance, _customString35_ attribute in _EmpJobInfo_ stores the location description. You want to flow this value to Active Directory _physicalDeliveryOfficeName_ attribute. To configure attribute-mapping for this scenario, use the steps: 1. Edit the SuccessFactors attribute list to add a new attribute called _empJobNavCustomString35_. 2. Set the JSONPath API expression for this attribute as: `$.employmentNav.results[0].jobInfoNav.results[0].customString35` 3. Save and reload the mapping change in the Microsoft Entra admin center. 4. In the attribute-mapping blade, map _empJobNavCustomString35_ to _physicalDeliveryOfficeName_. 5. Save the mapping. Extending this scenario: - If you want to map _custom35_ attribute from the _User_ entity, then use the JSONPath `$.employmentNav.results[0].userNav.custom35` - If you want to map _customString35_ attribute from the _EmpEmployment_ entity, then use the JSONPath `$.employmentNav.results[0].customString35` ### Mapping employment status to account status By default, the Microsoft Entra SuccessFactors connector uses the `activeEmploymentsCount` field of the `PersonEmpTerminationInfo` object to set account status. You may encounter one of the following issues with this attribute. 1. There's a known issue where the connector may disable the account of a terminated worker one day prior to the termination on the last day of work. 2. If the `PersonEmpTerminationInfo` object gets set to null, during termination, then AD account disabling doesn't work because the provisioning engine filters out records where the `personEmpTerminationInfoNav` object is set to null. If you're running into any of these issues or prefer mapping employment status to account status, you can update the mapping to expand the `emplStatus` field and use the employment status code present in the field `emplStatus.externalCode`. Based on [SAP support note 2505526](https://launchpad.support.sap.com/#/notes/2505526), here's a list of employment status codes that you can retrieve in the provisioning app. - A = Active - D = Dormant - U = Unpaid Leave - P = Paid Leave - S = Suspended - F = Furlough - O = Discarded - R = Retired - T = Terminated Use the steps to update your mapping to retrieve these codes. 1. Open the attribute mapping page of your SuccessFactors provisioning app. 2. Under the **Advanced Options** dropdown, select **Edit target User attributes**. 3. Find the attribute `emplStatus` and update the JSONPath to `$.employmentNav.results[0].jobInfoNav.results[0].emplStatusNav.externalCode`. The update makes the connector retrieve the employment status codes in the table. 4. Save the changes. 5. In the attribute mapping blade, update the expression mapping for the account status flag. Provisioning Job Account status attribute Mapping expression SuccessFactors to Active Directory User Provisioning `accountDisabled` `Switch([emplStatus], "True", "A", "False", "U", "False", "P", "False")` SuccessFactors to Microsoft Entra user provisioning `accountEnabled` `Switch([emplStatus], "False", "A", "True", "U", "True", "P", "True")` 6. Save the changes. 7. Test the configuration using [provision on demand](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/provision-on-demand). 8. After confirming that sync works as expected, restart the provisioning job. ### Handling worker conversion and rehiring scenarios **About worker conversion scenario:** Worker conversion is the process of converting an existing full-time employee to a contractor or a contractor to a full-time employee. In this scenario, Employee Central adds a new _EmpEmployment_ entity along with a new _User_ entity for the same _Person_ entity. The _User_ entity nested under the previous _EmpEmployment_ entity is set to null. **About rehiring scenarios:** In SuccessFactors, there are two options to process rehiring employees: - Option 1: Create a new person profile in Employee Central - Option 2: Reuse existing person profile in Employee Central If your HR process uses Option 1, then no changes are required to the provisioning schema. If your HR process uses Option 2, then Employee Central adds a new _EmpEmployment_ entity along with a new _User_ entity for the same _Person_ entity. You can handle both scenarios so that the new employment data shows up when a conversion or rehire occurs. Bulk update the provisioning app schema using the steps listed: 1. Open the attribute mapping page of your SuccessFactors provisioning app. 2. Select the **Advanced Options** dropdown and then select **Edit schema** to open the schema editor. > ![Screenshot shows the Review your schema here link that opens the schema editor.](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/media/sap-successfactors-integration-reference/review-schema.png#lightbox) 3. Click on the **Download** link to save a copy of the schema before editing. > ![Screenshot shows the Schema editor with Download select to save a copy of the schema.](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/media/sap-successfactors-integration-reference/download-schema.png#lightbox) 4. In the schema editor, press Ctrl-H key to open the find-replace control. 5. In the find text box, copy, and paste the value `$.employmentNav.results[0]` 6. In the replace text box, copy, and paste the value `$.employmentNav.results[-1:]`. This JSONPath expression returns the latest _EmpEmployment_ record. > ![find-replace-conversion](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/media/sap-successfactors-integration-reference/find-replace-conversion-scenario.png#lightbox) 7. Click on the "replace all" option to update the schema. 8. Save the schema. 9. The above process updates all JSONPath expressions as follows: - Old JSONPath: `$.employmentNav.results[0].jobInfoNav.results[0].departmentNav.name_localized` - New JSONPath: `$.employmentNav.results[-1:].jobInfoNav.results[0].departmentNav.name_localized` 10. Test the configuration using [provision on demand](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/provision-on-demand). 11. After confirming that sync works as expected, restart the provisioning job. Note The approach described above only works if SAP SuccessFactors returns the employment objects in ascending order, where the latest employment record is always the last record in the _employmentNav_ results array. The order in which multiple employment records are returned isn't guaranteed by SuccessFactors. If your SuccessFactors instance has multiple employment records corresponding to a worker and you always want to retrieve attributes associated with the active employment record, use steps described in the next section. ### Retrieving current active employment record Using the JSONPath root of `$.employmentNav.results[0]` or `$.employmentNav.results[-1:]` to fetch employment records works in most scenarios and keeps the configuration simple. However, depending on how your SuccessFactors instance is configured, there may be a need to update this configuration to ensure that the connector always fetches the latest active employment record. This section describes how you can update the JSONPath settings to definitely retrieve the current active employment record of the user. It also handles worker conversion and rehiring scenarios. 1. Open the attribute mapping page of your SuccessFactors provisioning app. 2. Select the **Advanced Options** dropdown and then select **Edit schema** to open the schema editor. 3. Click on the **Download** link to save a copy of the schema before editing. 4. In the schema editor, press Ctrl-H key to open the find-replace control. 5. Perform the following find replace operations. Ensure there's no leading or trailing space when performing the find-replace operations. If you're using `[-1:]` index instead of `[0]`, then update the _string-to-find_ field accordingly. **String to find** **String to use for replace** **Purpose** `$.employmentNav.results[0].jobInfoNav.results[0].emplStatus` `$.employmentNav..jobInfoNav..results[?(@.emplStatusNav.externalCode == 'A' || @.emplStatusNav.externalCode == 'U' || @.emplStatusNav.externalCode == 'P' )].emplStatusNav.externalCode` With this find-replace, we're adding the ability to expand emplStatusNav OData object. `$.employmentNav.results[0].jobInfoNav.results[0]` `$.employmentNav..jobInfoNav..results[?(@.emplStatusNav.externalCode == 'A' || @.emplStatusNav.externalCode == 'U' || @.emplStatusNav.externalCode == 'P')]` With this find-replace, we instruct the connector to always retrieve attributes associated with the active SuccessFactors EmpJobInfo record. Attributes associated with terminated/inactive records in SuccessFactors are ignored. `$.employmentNav.results[0]` `$.employmentNav..results[?(@.jobInfoNav..results[?(@.emplStatusNav.externalCode == 'A' || @.emplStatusNav.externalCode == 'U' || @.emplStatusNav.externalCode == 'P')])]` With this find-replace, we instruct the connector to always retrieve attributes associated with the active SuccessFactors Employment record. Attributes associated with terminated/inactive records in SuccessFactors are ignored. 6. Save the schema. 7. The above process updates all JSONPath expressions. 8. For prehire processing to work, the JSONPath associated with `startDate` attribute must use either `[0]` or `[-1:]` index. Under the **Advanced Options** dropdown, select **Edit target User attributes**. Find the attribute `startDate` and set it to the value `$.employmentNav.results[-1:].startDate` 9. Save the schema. 10. To ensure that terminations are processed as expected, you can use one of the following settings in the attribute mapping section. Provisioning Job Account status attribute Expression to use if account status is based on "activeEmploymentsCount" Expression to use if account status is based on "emplStatus" value SuccessFactors to Active Directory User Provisioning `accountDisabled` `Switch([activeEmploymentsCount], "False", "0", "True")` `Switch([emplStatus], "True", "A", "False", "U", "False", "P", "False")` SuccessFactors to Microsoft Entra user provisioning `accountEnabled` `Switch([activeEmploymentsCount], "True", "0", "False")` `Switch([emplStatus], "False", "A", "True", "U", "True", "P", "True")` 11. Save your changes. 1. 12. Test the configuration using [provision on demand](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/provision-on-demand). 13. After confirming that sync works as expected, restart the provisioning job. ### Handling global assignment scenario When a user in Employee Central is processed for global assignment, SuccessFactors adds a new _EmpEmployment_ entity and sets the _assignmentClass_ to "GA". It also creates new _User_ entity. Thus, the user now has: - One _EmpEmployment_ + _User_ entity that corresponds to home assignment with _assignmentClass_ set to "ST" and - Another _EmpEmployment_ + _User_ entity that corresponds to the global assignment with _assignmentClass_ set to "GA" To fetch attributes belonging to the standard assignment and global assignment user profile, use the steps listed: 1. Open the attribute mapping page of your SuccessFactors provisioning app. 2. Select the **Advanced Options** dropdown and then select **Edit schema** to open the schema editor. 3. Click on the **Download** link to save a copy of the schema before editing. 4. In the schema editor, press Ctrl-H key to open the find-replace control. 5. In the find text box, copy, and paste the value `$.employmentNav.results[0]` 6. In the replace text box, copy, and paste the value `$.employmentNav.results[?(@.assignmentClass == 'ST')]`. Note the whitespace surrounding the == operator, which is important for successful processing of the JSONPath expression. 7. Click on the "replace all" option to update the schema. 8. Save the schema. 9. The above process updates all JSONPath expressions as follows: - Old JSONPath: `$.employmentNav.results[0].jobInfoNav.results[0].departmentNav.name_localized` - New JSONPath: `$.employmentNav.results[?(@.assignmentClass == 'ST')].jobInfoNav.results[0].departmentNav.name_localized` 10. Reload the attribute mapping page of the app. 11. Select the **Advanced Options** dropdown and then select **Edit target User attributes**. 12. Add new attributes to fetch global assignment data.For example: if you want to fetch the department name associated with a global assignment profile, you can add the attribute _globalAssignmentDepartment_ with the JSONPath expression set to `$.employmentNav.results[?(@.assignmentClass == 'GA')].jobInfoNav.results[0].departmentNav.name_localized`. 13. You can now either flow both department values to Active Directory attributes or selectively flow a value using expression mapping. Example: the expression sets the value of AD _department_ attribute to _globalAssignmentDepartment_ if present, else it sets the value to _department_ associated with standard assignment. - `IIF(IsPresent([globalAssignmentDepartment]),[globalAssignmentDepartment],[department])` 14. Save the mapping. 15. Test the configuration using [provision on demand](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/provision-on-demand). 16. After confirming that sync works as expected, restart the provisioning job. ### Handling concurrent jobs scenario When a user in Employee Central has concurrent/multiple jobs, there are two _EmpEmployment_ and _User_ entities with _assignmentClass_ set to "ST". To fetch attributes belonging to both jobs, use the steps listed: 1. Open the attribute mapping page of your SuccessFactors provisioning app. 2. Select the **Advanced Options** dropdown and then select **Edit target User attributes**. 3. Let's say you want to pull the department associated with job 1 and job 2.The predefined attribute _department_ already fetches the value of department for the first job. You can define a new attribute called _secondJobDepartment_ and set the JSONPath expression to `$.employmentNav.results[1].jobInfoNav.results[0].departmentNav.name_localized` 4. You can now either flow both department values to Active Directory attributes or selectively flow a value using expression mapping. 5. Save the mapping. 6. Test the configuration using [provision on demand](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/provision-on-demand). 7. After confirming that sync works as expected, restart the provisioning job. ### Retrieving position details The SuccessFactors connector supports expansion of the position object. To expand and retrieve position object attributes such as job level or position names in a specific language, you can use JSONPath expressions as shown. Attribute Name JSONPath expression positionJobLevel $.employmentNav.results\[0\].jobInfoNav.results\[0\].positionNav.jobLevel positionNameFR $.employmentNav.results\[0\].jobInfoNav.results\[0\].positionNav.externalName\_fr\_FR positionNameDE $.employmentNav.results\[0\].jobInfoNav.results\[0\].positionNav.externalName\_de\_DE ### Provisioning users in the Onboarding module Inbound user provisioning from SAP SuccessFactors to on premises Active Directory and Microsoft Entra ID now supports advance provisioning of prehires present in the SAP SuccessFactors Onboarding 2.0 module. When the Microsoft Entra provisioning service encounters a new hire profile with a future start date, it queries SAP SuccessFactors to get new hires with one of the following status codes: `active`, `inactive`, `active_external_suite`. The status code `active_external_suite` corresponds to prehires present in the SAP SuccessFactors Onboarding 2.0 module. For a description of these status codes, refer to [SAP support note 2736579](https://launchpad.support.sap.com/#/notes/0002736579). The default behavior of the provisioning service is to process prehires in the Onboarding module. If you want to exclude processing of prehires in the Onboarding module, update your provisioning job configuration as follows: 1. Open the attribute mapping page of your SuccessFactors provisioning app. 2. Under the **Advanced Options** dropdown, select **Edit target User attributes** to add a new attribute called `userStatus`. 3. Set the JSONPath API expression for this attribute as: `$.employmentNav.results[0].userNav.status` 4. Save the schema to return back to the attribute mapping page. 5. Select **Scoping filters** and apply a scoping filter `userStatus NOT EQUALS`. 6. Save the mapping and validate that the scoping filter works using provisioning on demand. Note The connector currently doesn't support retrieving Onboarding users who are in an inactive\_external\_suite state. These user states occur when new hires initially begin onboarding but later rescind their offer, requiring the cancellation of the onboarding process. There is no workaround for this scenario; it requires out-of-band handling to deactivate users whose onboarding is cancelled. ### Enabling OData API Audit logs in SuccessFactors The Microsoft Entra SuccessFactors connector uses SuccessFactors OData API to retrieve changes and provision users. If you observe issues with the provisioning service and want to confirm what data was retrieved from SuccessFactors, you can enable OData API Audit logs in SuccessFactors. Retrieve the request payload sent by Microsoft Entra ID from the audit logs. To troubleshoot, you can copy this request payload in a tool like cURL or Graph Explorer, set it up to use the same API user that is used by the connector and see if it returns the desired changes from SuccessFactors. ## Writeback scenarios This section covers different write-back scenarios. It recommends configuration approaches based on how email and phone number is set up in SuccessFactors. ### Supported scenarios for phone and email write-back # Scenario requirement Email primary flag value Business phone primary flag value Cell phone primary flag value Business phone mapping Cell phone mapping 1 \* Only set business email as primary. \* Don't set phone numbers. true true false \[Not Set\] \[Not Set\] 2 \* In SuccessFactors, business email and business phone is primary \* Always flow Microsoft Entra telephone number to business phone and mobile to cell phone. true true false telephoneNumber mobile 3 \* In SuccessFactors, business email and cell phone is primary \* Always flow Microsoft Entra telephone number to business phone and mobile to cell phone true false true telephoneNumber mobile 4 \* In SuccessFactors business email is primary. \* In Microsoft Entra ID, check if work telephone number is present, if present, then check if mobile number is also present. Mark work telephone number as primary only if mobile number isn't present. true Use expression mapping: `IIF(IsPresent([telephoneNumber]), IIF(IsPresent([mobile]),"false", "true"), "false")` Use expression mapping: `IIF(IsPresent([mobile]),"false", "true")` telephoneNumber mobile 5 \* In SuccessFactors business email and business phone is primary. \* In Microsoft Entra ID, if mobile is available, then set it as the business phone, else use telephoneNumber. true true false `IIF(IsPresent([mobile]), [mobile], [telephoneNumber])` \[Not Set\] - If there's no mapping for phone number in the write-back attribute-mapping, then only email is included in the write-back. - During new hire onboarding in Employee Central, business email and phone number may not be available. If setting business email and business phone as primary is mandatory during onboarding, you can set a dummy value for business phone and email during new hire creation. After some time, the write-back app updates the value. ### Enabling writeback with UserID The SuccessFactors Writeback app uses the following logic to update the User object attributes: - As a first step, it looks for _userId_ attribute in the changeset. If it's present, then it uses "UserId" for making the SuccessFactors API call. - If _userId_ isn't found, then it defaults to using the _personIdExternal_ attribute value. Usually the _personIdExternal_ attribute value in SuccessFactors matches the _userId_ attribute value. However, in scenarios such as rehiring and worker conversion, an employee in SuccessFactors may have two employment records, one active and one inactive. In such scenarios, to ensure that write-back updates the active user profile, update the configuration of the SuccessFactors provisioning apps as described. This configuration ensures that _userId_ is always present in the changeset visible to the connector and is used in the SuccessFactors API call. 1. Open the SuccessFactors to Microsoft Entra user provisioning app or SuccessFactors to on-premises AD user provisioning app. 2. Ensure that `extensionAttribute[1-15]` in Microsoft Entra ID always stores the `userId` of every worker's active employment record. The record maps SuccessFactors `userId` attribute to `extensionAttribute[1-15]` in Microsoft Entra ID. ![Inbound UserID attribute mapping](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/media/sap-successfactors-integration-reference/inbound-userid-attribute-mapping.png) 3. For guidance regarding JSONPath settings, refer to the section [Handling worker conversion and rehiring scenarios](#handling-worker-conversion-and-rehiring-scenarios) to ensure the _userId_ value of the active employment record flows into Microsoft Entra ID. 4. Save the mapping. 5. Run the provisioning job to ensure that the _userId_ values flow into Microsoft Entra ID. Note If you're using SuccessFactors to on-premises Active Directory user provisioning, configure Microsoft Entra Connect to sync the _userId_ attribute value from on-premises Active Directory to Microsoft Entra ID. 6. Open the SuccessFactors Writeback app in the Azure portal. 7. Map the desired _extensionAttribute_ that contains the userId value to the SuccessFactors _userId_ attribute. ![Writeback UserID attribute mapping](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/media/sap-successfactors-integration-reference/userid-attribute-mapping.png) 8. Save the mapping. 9. Go to _Attribute mapping -> Advanced -> Review Schema_ to open the JSON schema editor. 10. Download a copy of the schema as backup. 11. In the schema editor, hit Ctrl-F and search for the JSON node containing the userId mapping, where it's mapped to a source Microsoft Entra attribute. 12. Update the flowBehavior attribute from "FlowWhenChanged" to "FlowAlways" as shown. ![Mapping flow behavior update](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/media/sap-successfactors-integration-reference/mapping-flow-behavior-update.png) 13. Save the mapping and test the write-back scenario with provisioning-on-demand. ### Unsupported scenarios for phone and email write-back - In Employee Central, during onboarding personal email and personal phone is set as primary. The write-back app can't switch this setting and set business email and business phone as primary. - In Employee Central, business phone is set as primary. The write-back app can't change this and set cell phone as primary. - The write-back app can't read the current primary flag settings and use the same values for the write operation. The flag values configured in the attribute-mapping are always be used. - The SuccessFactors provisioning connectors, including the write-back connector, are not supported in Microsoft tenants operated by 21Vianet (China). ## Next steps - [Learn how to configure SuccessFactors to Active Directory provisioning](https://learn.microsoft.com/en-us/entra/identity/saas-apps/sap-successfactors-inbound-provisioning-tutorial) - [Learn how to configure writeback to SuccessFactors](https://learn.microsoft.com/en-us/entra/identity/saas-apps/sap-successfactors-writeback-tutorial) - [Learn more about supported SuccessFactors Attributes for inbound provisioning](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/sap-successfactors-attribute-reference)