How to integrate SAP SuccessFactors with Sapho version 4.1 or greater

Prerequisites

Before you set up the connector in Sapho you need to do a few things.

1: Create a dedicated User ID

You need to create an Admin user in the Provisioning instance. Typically all activities in Provisioning are performed by a SuccessFactors Certified Consultant. Give the user a distinguishable name e.g. Username - saphoapiuser, First Name - Sapho, Last Name - API User.
Note: Our advice is to create a separate dedicated user for connecting SAP SuccessFactors to Sapho. However, you might also use an already existing Admin user.

2: Grant the necessary permissions to the User ID

Log in the SF BizX instance. You will need to follow the Role Based Permission (RBP) approach to set up the permissions for the dedicated User ID. This involves creating a Permission Role and a Permission Group.

3.1: Create a Permission Role

Go to Admin Centre. Access Manage Permission Roles by entering it in the search box at the top of the page.

sf1.png

Click Create New to add a new role.

sf2.png

Enter a meaningful Role Name, for example, Sapho API User (but feel free to use a name that is aligned to your company’s naming standards).

sf3.png

Under Permission settings, click Permission… button. Scroll down to the link Manage Integration Tools and check the first checkbox - Select All. Click Done on the dialog.

sf4.png

Click Save Changes at the bottom of the Permission Role Detail page.

3.2: Create a Permission Group

Go to Admin Centre. Access Manage Permission Groups by entering it in the search box at the top of the page.

sf6.png

Click Create New to add a new role.

sf7.png

Give the group a meaningful name (e.g. to keep it simple you can call it Sapho API User). Go to the People Pool section and select Username from the dropdown.

sf8.png

On the Search Results screen, enter the username of the dedicated user (e.g. saphoapiuser), select the checkbox next to the name, and click Done.

sf9.png

You’ll return on the previous screen. Click Done again.

3.3: Assign the new Permission Group to the Permission Role

Go back to Permission Roles by entering Manage Permission Roles in the search box at the top of the page.
Click on the previously created permission role (e.g. Sapho API User).

sf10.png

Once in the Permission Role, scroll to Grant this role to… section and click the Add button.

sf11.png

On the Grant this role to… screen, click the Select… button.

sf12.png

Search for the previously created group (e.g. Sapho API User), select the checkbox next to the name, and click Done.

sf13.png

You’ll return on the previous screen. Click Done again. And then click Save Changes at the bottom of the Permission Role Detail page.

You can now navigate back to the Sapho API User Permission Group to confirm the assignment. Once you are in the API User group, you will see Granted Permission Roles has an entry Sapho API User in the list of Permission Roles.

sf14.png

4: Register the OAuth2 Client

Go to Admin Centre. Access Manage OAuth2 Client Applications by entering it in the search box at the top of the page.

sf15.png

Click Register Client Application.

sf16.png

Enter Application Name - Sapho.
Enter Application URL - https://www.sapho.com/.
Click on Generate X.509 Certificate.

sf17.png

Enter a Common Name (CN) - Sapho. You may leave the rest of the fields empty as they are. Click the Generate button.

sf18.png

Click the Download button to download a copy of the X.509 certificate on your machine. Store it in a secure place for later reference.

sf19.png

Finally, click the Register button.

The new application will be listed on the Manage Oauth2 Client Applications page. Click View.

sf20.png

On the detail page, you will find the API Key. Copy & paste it in a secure place for later reference.

sf21.png

 

How to set up the SAP SuccessFactors connector in Sapho

The instructions below assume that you are on “What is the connection information?” screen for SAP SuccessFactors.

(Applicable only for Sapho version 4.3 or higher: the instructions below also assume that the dropdown labeled Are you using the Learning module? is set to "No".)

Step 1: Enter the API endpoint URL of the data center hosting your SuccessFactors instance

Your SuccessFactors support representative can tell you the location of the data center hosting your instance. When you know the location, refer to the table on this page to obtain the API endpoint URL.
For example, if your production instance is hosted in Ashburn, Virginia (USA), the API endpoint URL you need to enter is https://api8.successfactors.com/odata/v2/.

Step 2: Enter the Company ID

This is the Company ID assigned by SuccessFactors to your organization.

Step 3: Enter the User ID

This is the ID of the dedicated admin user (e.g. saphoapiuser) you created as a prerequisite.

Step 4: Enter the Client ID

This is the API Key that you copied earlier from the OAuth2 Client Application detail page.

Step 5: Enter the Client Private Key

To get the Client Private Key, open the certificate file downloaded from SuccessFactors using Notepad (or any such app). The X.509 certificate has 2 parts – the private key and the certificate. Copy the characters between —–BEGIN ENCRYPTED PRIVATE KEY—– and —–END ENCRYPTED PRIVATE KEY—– and paste them in Sapho.

Click Next.

Step 6: Finish the creation of the connector

Step 7: Wait for Sapho to sync with SAP SuccessFactors

It might take a while to load data from SAP SuccessFactors. While this happens, there is going to be a spinner inline with the connector on the Connectors page.

 

Troubleshooting

Possible issue #1: If Sapho Server runs on premises behind a corporate firewall, it might not be able to connect to the SAP SuccessFactors cloud. 

Solution: Identify the location of the data center hosting your SuccessFactors instance and refer to the table on this page to obtain the API endpoint URL specific to that data center. Trim the /odata/v2 part of the URL. In your firewall, allow access to the remaining URL with port 443.

For example, if your production instance is hosted in Ashburn, Virginia (USA), the API endpoint URL specific to that data center is https://api8.successfactors.com/odata/v2/. So, you need to allow access to hostname https://api8.successfactors.com with port 443.

 

Possible issue #2: The OData API is disabled. 

Solution: The OData API is set to enabled by default, unless you manually turn it off in Provisioning. Check with your SAP SuccessFactors partner or support representative if the OData API is enabled in Provisioning.

 

Possible issue #3: The user account used to connect SAP SuccessFactors to Sapho does not have enough privileges for accessing OData APIs.

Solution: First, check the permissions assigned to the given user by doing the following steps:

1- Go to Admin Center.

2 - In the search box, enter "View User Permission" and select it.

3 - In Advanced Search, enter the username of the given user and click Search.

4 - Click View Permission next to the username.

5 - A list of permissions is displayed along with the roles that grant those permissions. Scroll to the section labeled "Manage Integration Tools."

6 - Check if the user has all the permissions listed below.

sf24.png

If the user account doesn't have all permissions, follow closely steps 2 and 3 from the Prerequisites section on this page.