SAP SuccessFactors - How do I set up my connection with specific permissions for an HRIS integration?

Overview

This article covers the steps needed to generate credentials in your SAP SuccessFactors instance. These credentials can be scoped to only specific fields and employees by following the steps below.

Prerequisites

Please ensure you fulfill all the requirements to set up the integration:

• You have Administrator permissions in your company's SAP SuccessFactors instance

Instructions

Step 1: Create a new user that will be used to link

1. Search for and select the Import Employee Data task
2. Update the action to Download Template
3. Select an entity of Basic Import and click Generate Template

4. Open the downloaded file and add a row with the below information

   Field	Sample value	Notes
   Status	active
   User ID	integration_sample	This should be anything that will help you remember the user/integration
   Username	integration_sample	This should be anything that will help you remember the user/integration
   First Name	Sample	This should be anything that will help you remember the user/integration
   Last Name	Integration	This should be anything that will help you remember the user/integration
   Email	integration_sample@example.com	Doesn't need to be valid
   Manager	NO_MANAGER
   HR	NO_HR
   Default Locale	en_US

5. After configuring and saving the file, go back to SAP and update the action to Import Data
6. Choose and entity of Basic Import, select your file, then click Import
   1. Note, you can validate your file first by selecting Validate Import File Data
7. Confirm the success dialog appears
8. After a few seconds to a minute, search for the user you've created. If the user appears, you've successfully created the user.

Step 2: Create a new Permission Group for the user

1. Search Manage Permission Groups in your search bar to navigate to the Permission Groups page.

2. Click Create New to begin creating a new Permission Group for linking.
   1. Choose a name you'll remember that will help track that this Permission Group is for this specific connection. 
   2. The User Type needs to be Employee, and the Choose Group Members should include the User you created in Step 1.
   3. You do not need to input anything in regards to the Exclude Section, or the Granted Permission Roles at this time.

3. Click Done to create and save this Permission Group.

Step 3: (Optional) create a Permissions Group for the "target" employees

If you want to only provide access to certain employees (employees within a given company, non-contingent workers, etc) and don't already have a Permissions Group for the target audience, follow the steps in this section.

1. Click Create New to begin creating a new Permission Group for the target audience

2. Give the group a name like "

   target audience"
3. Apply the filters:
   1. The example below provides access to employees in the "Atlanta"Note, you can test the filters by clicking
   2. Update, then selecting the Active Group Membership number
4. Once done specifying the filters, click Done

Step 4: Create Permission Role with proper permissions

1. Search up Manage Permission Roles in your search bar to navigate to the Permission Role page.

2. Begin creating a new Permissions Role by selecting Create
3. Configure the name of the Group, then click Next
   1. Choose a name you'll remember that will help track that this specific connection.
4. Identify and select the permissions that matter for the use case you are trying to achieve. Details below:
   1. Employee Central Effective Dated Entities > Personal Information

      1. Note you can select all by clicking View Current at the top of the grid. Doing so will auto-select all the below fields. 

         Permission	Access	Notes
         Personal Information Actions	View Current	Required for employee name and/or demographic data Gives access to the PerPersonal entity
         First Name	View Current
         Middle Name	View Current
         Last Name	View Current
         Preferred Name	View Current
         Gender	View Current
         Marital Status	View Current
         Nationality	View Current
         Any custom fields or other fields you have/want to provide access to	View Current

      2. Employee Central Effective Dated Entities > Addresses 

         Permission	Access	Notes
         Address Information Actions	View Current	Required for Employee address data

      3. Employee Central Effective Dated Entities > Job Information

         1. If you want to pull an Employee's job/position, we suggest selecting all by clicking View History at the top of the grid. Doing so will auto-select all the below fields. 

            Permission	Access	Notes
            Job Information Actions	View History	Required for employment data (job and/or pay) Gives access to the EmpJob entity
            Position	View History
            Position Entry Date	View History
            Company	View History
            Business Unit	View History
            Division	View History
            Department	View History
            Location	View History
            Cost Center	View History
            Supervisor	View History
            Job Classification	View History
            Job Title	View History
            Regular/Temporary	View History
            FTE	View History
            Employee Type	View History
            Employee Class	View History
            Employment Type	View History
            jobInfo_seq-number	View History
            jobInfo_event-reason	View History
            Any custom fields or other fields you have/want to provide access to	View History

      4. Employee Central Effective Dated Entities > Compensation Information

         1. If you want to pull an Employee's pay, we suggest selecting all by clicking View History at the top of the grid. Doing so will auto-select all the below fields. 

            Permission	Access	Notes
            Compensation Information Actions	View History	Required for employment data (pay only) Gives access to the EmpCompensation entity
            Pay Group	View History
            Current Salary	View History
            New Salary	View History
            compInfo_event-reason	View History
            Any custom fields or other fields you have/want to provide access to	View History

      5. General User Permission
         1. User Search
            1. Minimum required permission for all use cases
            2. Gives access to User entity
      6. Employee Data > HR Information

         1. Note you can select all by clicking View Current at the top of the grid. Doing so will auto-select all the below fields. 

            Permission	Access	Notes
            Biographical Information	View	Minimum required permission for all use cases Gives access to the PerPerson entity
            Phone Information	View	Required for employee phone data
            Email Information	View	Required for employee email data
            Business Email Address	View	Required for employee email data
            Business Address
            Any custom fields or other fields you have/want to provide access to	View

      7. Employee Data Employment Details

         1. Note you can select all by clicking View Current at the top of the grid. Doing so will auto-select all the below fields. 

            Permission	Access	Notes
            Employment Details MSS	View	Required for any employee use case Gives access to the EmpEmployment entity
            Hire Date	View	Required for any employee use case
            Termination Date	View	Required for any employee use case
            Original Start Date	View
            Any custom fields or other fields you have/want to provide access to	View

      8. Payroll Integration Permissions 

         Permission	Access	Notes
         Employee Payroll Run Results	View History	Required for employee payroll result data
         Employee Payroll Run Results.employeePayrollRunResultsItems	View Current	Required for employee payroll result data

      9. Miscellaneous Permissions

         Permission	Access	Notes
         Payment Information	View History	Required for employee bank information data
         Payment Information .Details	View Current	Required for employee bank information data

      10. Employee Central API
          1. Employee Central Foundation (read-only)
             1. Minimum required permission for all use cases
             2. Gives access to Company-related data
      11. Manage System Properties
          1. Picklist Management and Picklists Mappings Set Up
             1. Minimum required permission for all use cases
             2. Gives access to view the labels for fields like employment status

4. After setting the permissions, click Next in the bottom right
5. Review the permissions one more time, then click Save
6. A pop up will appear asking if you want to continue to assign the role. Click Yes
7. You'll be taken to a Role Assignment screen. In the Basic Information tab make sure the below is populated, then select Next.
   1. Name: can leave as is
   2. Target Population User Type: Employee
   3. Status: Active
8. In the Grant Access To tab, grant access to the User you imported in Step 1 by selecting the Permissions Groups you created in Step 2, then click Next.
9. You'll be taken to the Define a Target Population tab. IMPORTANT, please read the below: 
   1. If you want to grant access to all users & employees:
      1. Select Everyone
   2. If you want to only grant access to specific employee:
      1. Select Filtered By
      2. Choose Permission Group
      3. Select the Permissions Group for the target employees that you created in Step 3
10. Select Next to proceed to Define Data Blocking
    1. Note, depending on your selected permissions, you might not have a Data Blocking step
11. Leave the default Data Blocking selected and select Next to proceed to the Preview
12. Review your setup, then select Save

Step 5: Find your SAP SuccessFactors API server URL

1. To find your API Server URL, navigate to the list of SAP SuccessFactors API Servers
2. In the listed API Server URLs, search for the environment that matches your subdomain.
   1. For example, if your domain was https://salesdemo4.successfactors.com, search for salesdemo4.
   2. If you are unsure what your API Server URL is, or are having trouble connecting, we recommend reaching out to your SAP Support team to obtain your API Server URL.

1. Once you've found the URL, copy the entire URL.In this example, it would be: apisalesdemo4.successfactors.com
2. Enter your SAP SuccessFactors API Server URL into the integration authorization component as shown below:

Step 6: Input the username and company ID in the linking flow

1. In the linking flow, input the username of the User you created in Step 1

2. If you don't know your company ID, select your profile image in the top right, then select Show version information.

   

3. Your Company ID will appears in the pop up - sample below
4. Once you obtain your company ID, enter it in the linking flow as shown, then select Next

Step 7: Generate your SAP SuccessFactors Client ID and Secret

1. In your Admin Center, go to Tools, and search Manage OAuth2 Client Applications (If your page looks different, search for Manage OAuth2Client Applications in the search tool on your homepage).

2. Click Register Client Application.

3. Fill out your application details:
   1. Application Name & Application URL (what actually goes in these fields is not important, except that the URL has to begin with https://).
   2. Check Bind to Users
   3. Input the username of the user you created in step 1 in the User IDs field

4. Click Generate X.509 Certificate. Fill out Common Name (name doesn't matter) and hit Generate.

5. Once the certificate populates, download and save it. You will have downloaded a file called Certificate.pem.

6. Click Register (it will have replaced the Generate button).
7. Back on your Manage OAuth2 Client Applications, go to the application you just created and click Edit.

1. You will now see an API key listed - this is your Client ID. Copy and save this Key.

9. Open up the "Certificate.pem" file that you downloaded previously in a text editor. The string between ——BEGIN ENCRYPTED PRIVATE KEY——- and —-END ENCRYPTED PRIVATE KEY——- is your Client Secret. Copy the Client Secret and save.

10. Enter your Client ID and Secret into the integration authorization component as shown below:

The linking flow should now attempt to validate your credentials. This can take a few seconds to about a minute. If you've done everything correctly, you should then see a success screen, then you're done!