Tutorial: Configure attribute write-back from Azure AD to SAP SuccessFactors

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

Overview

You can configure the SAP SuccessFactors Writeback app to write specific attributes from Azure Active Directory 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 Azure AD provisioning app.

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

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 Azure AD.

Create an API permissions role

  1. Log in to SAP SuccessFactors with a user account that has access to the Admin Center.

  2. Search for Manage Permission Roles, then select Manage Permission Roles from the search results.

    Manage Permission Roles

  3. From the Permission Role List, click Create New.

    Create New Permission Role

  4. 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.

    Permission role detail

  5. 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.

    Manage integration tools

  6. 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.

    Read write permissions

  7. Click on Done. Click Save Changes.

Create a Permission Group for the API user

  1. In the SuccessFactors Admin Center, search for Manage Permission Groups, then select Manage Permission Groups from the search results.

    Manage permission groups

  2. From the Manage Permission Groups window, click Create New.

    Add new group

  3. Add a Group Name for the new group. The group name should indicate that the group is for API users.

    Permission group name

  4. 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.

    Add group members

  5. Click Done to finish creating the Permission Group.

Grant Permission Role to the Permission Group

  1. In SuccessFactors Admin Center, search for Manage Permission Roles, then select Manage Permission Roles from the search results.

  2. From the Permission Role List, select the role that you created for API usage permissions.

  3. Under Grant this role to..., click Add... button.

  4. Select Permission Group... from the drop-down menu, then click Select... to open the Groups window to search and select the group created above.

    Add permission group

  5. Review the Permission Role grant to the Permission Group.

    Permission Role and Group detail

  6. 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 (e.g. business, personal, 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.

  1. In SuccessFactors Admin Center, search for Manage business configuration.

    Manage business configuration

  2. Under HRIS Elements, select emailInfo and click on the Details for the email-type field.

    Get email info

  3. 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.

    Identify email picklist

  4. Under HRIS Elements, select phoneInfo and click on the Details for the phone-type field.

    Get phone info

  5. 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.

    Identify phone picklist

Retrieve constant value for emailType

  1. In SuccessFactors Admin Center, search and open Picklist Center.

  2. Use the name of the email picklist captured from the previous section (e.g. ecEmailType) to find the email picklist.

    Find email type picklist

  3. Open the active email picklist.

    Open active email type picklist

  4. On the email type picklist page, select the Business email type.

    Select business email type

  5. 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.

    Get email type code

    Note

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

Retrieve constant value for phoneType

  1. In SuccessFactors Admin Center, search and open Picklist Center.

  2. Use the name of the phone picklist captured from the previous section to find the phone picklist.

    Find phone type picklist

  3. Open the active phone picklist.

    Open active phone type picklist

  4. On the phone type picklist page, review the different phone types listed under Picklist Values.

    Review phone types

  5. 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.

    Get business phone code

  6. 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.

    Get cell phone code

    Note

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

Configuring SuccessFactors Writeback App

This section provides steps for

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

To configure SuccessFactors Writeback:

  1. Go to https://portal.azure.com

  2. In the left navigation bar, select Azure Active Directory

  3. Select Enterprise Applications, then All Applications.

  4. Select Add an application, and select the All category.

  5. Search for SuccessFactors Writeback, and add that app from the gallery.

  6. After the app is added and the app details screen is shown, select Provisioning

  7. Change the Provisioning Mode to Automatic

  8. 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 Azure AD 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.

    Azure portal

    • 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.

  1. On the Provisioning tab under Mappings, click Provision Azure Active Directory Users.

  2. In the Source Object Scope field, you can select which sets of users in Azure AD should be considered for write-back, by defining a set of attribute-based filters. The default scope is "all users in Azure AD".

    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 Azure AD. Once you have verified that the mappings work, then you can either remove the filter or gradually expand it to include more users.

  3. The Target Object Actions field only supports the Update operation.

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

    # Azure AD attribute SuccessFactors Attribute Remarks
    1 employeeId personIdExternal By default, this attribute is the matching identifier. Instead of employeeId you can use any other Azure AD 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 Azure AD 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 Azure AD Connect sync: Directory extensions to sync samAccountName to Azure AD. 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 Azure AD 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 Azure AD 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.
  5. Validate and review your attribute mappings.

    Writeback attribute mapping

  6. Click Save to save the mappings. Next, we will update the JSON Path API expressions to use the phoneType codes in your SuccessFactors instance.

  7. Select Show advanced options.

    Show advanced options

  8. 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.

  9. The API expression column in this view displays the JSON Path expressions used by the connector.

  10. Update the JSON Path expressions for business phone and cell phone to use the ID value (businessPhoneType and cellPhoneType) corresponding to your environment.

    Phone JSON Path change

  11. 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 in the Azure portal.

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.

  1. In the Provisioning tab, set the Provisioning Status to On.

  2. 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 Azure AD 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.

    Select Writeback scope

    Note

    The SuccessFactors Writeback provisioning app does not support "group assignment". Only "user assignment" is supported.

  3. Click Save.

  4. This operation will start the initial sync, which can take a variable number of hours depending on how many users are in the Azure AD tenant and the scope defined for the operation. You can check the progress bar to the track the progress of the sync cycle.

  5. 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.

  6. Once the initial sync is completed, it will write an audit summary report in the Provisioning tab, as shown below.

    Provisioning progress bar

Supported scenarios, known issues and limitations

Refer to the Writeback scenarios section of the SAP SuccessFactors integration reference guide.

Next steps