Tutorial: Configure attribute write-back from Microsoft Entra ID to SAP SuccessFactors

Article
10/23/2023

The objective of this tutorial is to show the steps to write-back attributes from Microsoft Entra ID to SAP SuccessFactors Employee Central.

Overview

You can configure the SAP SuccessFactors Writeback app to write specific attributes from Microsoft Entra ID to SAP SuccessFactors Employee Central. The SuccessFactors writeback provisioning app supports assigning values to the following Employee Central attributes:

Work Email
Username
Business phone number (including country code, area code, number, and extension)
Business phone number primary flag
Cell phone number (including country code, area code, number)
Cell phone primary flag
User custom01-custom15 attributes
loginMethod attribute

Note

This app does not have any dependency on the SuccessFactors inbound user provisioning integration apps. You can configure it independent of SuccessFactors to on-premises AD provisioning app or SuccessFactors to Microsoft Entra ID provisioning app.

Refer to the Writeback scenarios section of the SAP SuccessFactors integration reference guide for more details on the supported scenarios, known issues and limitations.

Who is this user provisioning solution best suited for?

This SuccessFactors Writeback user provisioning solution is ideally suited for:

Organizations using Microsoft 365 that desire to write-back authoritative attributes managed by IT (such as email address, phone, username) back to SuccessFactors Employee Central.

Configuring SuccessFactors for the integration

All SuccessFactors provisioning connectors require credentials of a SuccessFactors account with the right permissions to invoke the Employee Central OData APIs. This section describes steps to create the service account in SuccessFactors and grant appropriate permissions.

Create/identify API user account in SuccessFactors
Create an API permissions role
Create a Permission Group for the API user
Grant Permission Role to the Permission Group

Create/identify API user account in SuccessFactors

Work with your SuccessFactors admin team or implementation partner to create or identify a user account in SuccessFactors that will be used to invoke the OData APIs. The username and password credentials of this account will be required when configuring the provisioning apps in Microsoft Entra ID.

Create an API permissions role

Log in to SAP SuccessFactors with a user account that has access to the Admin Center.
Search for Manage Permission Roles, then select Manage Permission Roles from the search results.
From the Permission Role List, click Create New.
Add a Role Name and Description for the new permission role. The name and description should indicate that the role is for API usage permissions.
Under Permission settings, click Permission..., then scroll down the permission list and click Manage Integration Tools. Check the box for Allow Admin to Access to OData API through Basic Authentication.
Scroll down in the same box and select Employee Central API. Add permissions as shown below to read using ODATA API and edit using ODATA API. Select the edit option if you plan to use the same account for the write-back to SuccessFactors scenario.
Click on Done. Click Save Changes.

Create a Permission Group for the API user

In the SuccessFactors Admin Center, search for Manage Permission Groups, then select Manage Permission Groups from the search results.
From the Manage Permission Groups window, click Create New.
Add a Group Name for the new group. The group name should indicate that the group is for API users.
Add members to the group. For example, you could select Username from the People Pool drop-down menu and then enter the username of the API account that will be used for the integration.
Click Done to finish creating the Permission Group.

Grant Permission Role to the Permission Group

In SuccessFactors Admin Center, search for Manage Permission Roles, then select Manage Permission Roles from the search results.
From the Permission Role List, select the role that you created for API usage permissions.
Under Grant this role to..., click Add... Button.
Select Permission Group... from the drop-down menu, then click Select... to open the Groups window to search and select the group created above.
Review the Permission Role grant to the Permission Group.
Click Save Changes.

Preparing for SuccessFactors Writeback

The SuccessFactors Writeback provisioning app uses certain code values for setting email and phone numbers in Employee Central. These code values are set as constant values in the attribute-mapping table and are different for each SuccessFactors instance. This section provides steps to capture these code values.

Note

Please involve your SuccessFactors Admin to complete the steps in this section.

Identify Email and Phone Number picklist names

In SAP SuccessFactors, a picklist is a configurable set of options from which a user can make a selection. The different types of email and phone number (such as business, personal, and other) are represented using a picklist. In this step, we will identify the picklists configured in your SuccessFactors tenant to store email and phone number values.

In SuccessFactors Admin Center, search for Manage business configuration.
Under HRIS Elements, select emailInfo and click on the Details for the email-type field.
On the email-type details page, note down the name of the picklist associated with this field. By default, it is ecEmailType. However it may be different in your tenant.
Under HRIS Elements, select phoneInfo and click on the Details for the phone-type field.
On the phone-type details page, note down the name of the picklist associated with this field. By default, it is ecPhoneType. However it may be different in your tenant.

Retrieve constant value for emailType

In SuccessFactors Admin Center, search and open Picklist Center.
Use the name of the email picklist captured from the previous section (such as ecEmailType) to find the email picklist.
Open the active email picklist.
On the email type picklist page, select the Business email type.
Note down the Option ID associated with the Business email. This is the code that we will use with emailType in the attribute-mapping table.

Note

Drop the comma character when you copy over the value. For example, if the Option ID value is 8,448, then set the emailType in Microsoft Entra ID to the constant number 8448 (without the comma character).

Retrieve constant value for phoneType

In SuccessFactors Admin Center, search and open Picklist Center.
Use the name of the phone picklist captured from the previous section to find the phone picklist.
Open the active phone picklist.
On the phone type picklist page, review the different phone types listed under Picklist Values.
Note down the Option ID associated with the Business phone. This is the code that we will use with businessPhoneType in the attribute-mapping table.
Note down the Option ID associated with the Cell phone. This is the code that we will use with cellPhoneType in the attribute-mapping table.

Note

Drop the comma character when you copy over the value. For example, if the Option ID value is 10,606, then set the cellPhoneType in Microsoft Entra ID to the constant number 10606 (without the comma character).

Configuring SuccessFactors Writeback App

This section provides steps for

Add the provisioning connector app and configure connectivity to SuccessFactors
Configure attribute mappings
Enable and launch user provisioning

Part 1: Add the provisioning connector app and configure connectivity to SuccessFactors

To configure SuccessFactors Writeback:

Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.
Browse to Identity > Applications > Enterprise applications > New application.
Search for SuccessFactors Writeback, and add that app from the gallery.
After the app is added and the app details screen is shown, select Provisioning
Change the Provisioning Mode to Automatic
Complete the Admin Credentials section as follows:
- Admin Username – Enter the username of the SuccessFactors API user account, with the company ID appended. It has the format: username@companyID
- Admin password – Enter the password of the SuccessFactors API user account.
- Tenant URL – Enter the name of the SuccessFactors OData API services endpoint. Only enter the host name of server without http or https. This value should look like: api4.successfactors.com.
- Notification Email – Enter your email address, and check the "send email if failure occurs" checkbox.
Note

The Microsoft Entra provisioning service sends email notification if the provisioning job goes into a quarantine state.
- Click the Test Connection button. If the connection test succeeds, click the Save button at the top. If it fails, double-check that the SuccessFactors credentials and URL are valid.
- Once the credentials are saved successfully, the Mappings section will display the default mapping. Refresh the page, if the attribute mappings are not visible.

Part 2: Configure attribute mappings

In this section, you will configure how user data flows from SuccessFactors to Active Directory.

On the Provisioning tab under Mappings, click Provision Microsoft Entra users.
In the Source Object Scope field, you can select which sets of users in Microsoft Entra ID should be considered for write-back, by defining a set of attribute-based filters. The default scope is "all users in Microsoft Entra ID".

Tip

When you are configuring the provisioning app for the first time, you will need to test and verify your attribute mappings and expressions to make sure that it is giving you the desired result. Microsoft recommends using the scoping filters under Source Object Scope to test your mappings with a few test users from Microsoft Entra ID. Once you have verified that the mappings work, then you can either remove the filter or gradually expand it to include more users.
The Target Object Actions field only supports the Update operation.

In the mapping table under Attribute mappings section, you can map the following Microsoft Entra attributes to SuccessFactors. The table below provides guidance on how to map the write-back attributes.

#	Microsoft Entra attribute	SuccessFactors Attribute	Remarks
1	employeeId	personIdExternal	By default, this attribute is the matching identifier. Instead of employeeId you can use any other Microsoft Entra attribute that may store the value equal to personIdExternal in SuccessFactors.
2	mail	email	Map email attribute source. For testing purposes, you can map userPrincipalName to email.
3	8448	emailType	This constant value is the SuccessFactors ID value associated with business email. Update this value to match your SuccessFactors environment. See the section Retrieve constant value for emailType for steps to set this value.
4	true	emailIsPrimary	Use this attribute to set business email as primary in SuccessFactors. If business email is not primary, set this flag to false.
5	userPrincipalName	[custom01 – custom15]	Using Add New Mapping, you can optionally write userPrincipalName or any Microsoft Entra attribute to a custom attribute available in the SuccessFactors User object.
6	On Prem SamAccountName	username	Using Add New Mapping, you can optionally map on-premises samAccountName to SuccessFactors username attribute. Use Microsoft Entra Connect Sync: Directory extensions to sync samAccountName to Microsoft Entra ID. It will appear in the source drop down as extension_yourTenantGUID_samAccountName
7	SSO	loginMethod	If SuccessFactors tenant is setup for partial SSO, then using Add New Mapping, you can optionally set loginMethod to a constant value of "SSO" or "PWD".
8	telephoneNumber	businessPhoneNumber	Use this mapping to flow telephoneNumber from Microsoft Entra ID to SuccessFactors business / work phone number.
9	10605	businessPhoneType	This constant value is the SuccessFactors ID value associated with business phone. Update this value to match your SuccessFactors environment. See the section Retrieve constant value for phoneType for steps to set this value.
10	true	businessPhoneIsPrimary	Use this attribute to set the primary flag for business phone number. Valid values are true or false.
11	mobile	cellPhoneNumber	Use this mapping to flow telephoneNumber from Microsoft Entra ID to SuccessFactors business / work phone number.
12	10606	cellPhoneType	This constant value is the SuccessFactors ID value associated with cell phone. Update this value to match your SuccessFactors environment. See the section Retrieve constant value for phoneType for steps to set this value.
13	false	cellPhoneIsPrimary	Use this attribute to set the primary flag for cell phone number. Valid values are true or false.
14	[extensionAttribute1-15]	userId	Use this mapping to ensure that the active record in SuccessFactors is updated when there are multiple employment records for the same user. For more details refer to Enabling writeback with UserID

Validate and review your attribute mappings.
Click Save to save the mappings. Next, we will update the JSON Path API expressions to use the phoneType codes in your SuccessFactors instance.
Select Show advanced options.
Click on Edit attribute list for SuccessFactors.

Note

If the Edit attribute list for SuccessFactors option does not show in the Azure portal, use the URL https://portal.azure.com/?Microsoft_AAD_IAM_forceSchemaEditorEnabled=true to access the page.
The API expression column in this view displays the JSON Path expressions used by the connector.
Update the JSON Path expressions for business phone and cell phone to use the ID value (businessPhoneType and cellPhoneType) corresponding to your environment.
Click Save to save the mappings.

Enable and launch user provisioning

Once the SuccessFactors provisioning app configurations have been completed, you can turn on the provisioning service.

Tip

By default when you turn on the provisioning service, it will initiate provisioning operations for all users in scope. If there are errors in the mapping or data issues, then the provisioning job might fail and go into the quarantine state. To avoid this, as a best practice, we recommend configuring Source Object Scope filter and testing your attribute mappings with a few test users before launching the full sync for all users. Once you have verified that the mappings work and are giving you the desired results, then you can either remove the filter or gradually expand it to include more users.

In the Provisioning tab, set the Provisioning Status to On.
Select Scope. You can select from one of the following options:
- Sync all users and groups: Select this option if you plan to write back mapped attributes of all users from Microsoft Entra ID to SuccessFactors, subject to the scoping rules defined under Mappings -> Source Object Scope.
- Sync only assigned users and groups: Select this option if you plan to write back mapped attributes of only users that you have assigned to this application in the Application -> Manage -> Users and groups menu option. These users are also subject to the scoping rules defined under Mappings -> Source Object Scope.
Note

SuccessFactors Writeback provisioning apps created after 12-Oct-2022 support the "group assignment" feature. If you created the app prior to 12-Oct-2022, it will only have "user assignment" support. To use the "group assignment" feature, create a new instance of the SuccessFactors Writeback application and move your existing mapping configurations to this app.
Click Save.
This operation will start the initial sync, which can take a variable number of hours depending on how many users are in the Microsoft Entra tenant and the scope defined for the operation. You can check the progress bar to the track the progress of the sync cycle.
At any time, check the Provisioning logs tab in the Azure portal to see what actions the provisioning service has performed. The provisioning logs lists all individual sync events performed by the provisioning service.
Once the initial sync is completed, it will write an audit summary report in the Provisioning tab, as shown below.