Skip to main content

Setting up Your SuccessFactors Integration

Overview

This help center article walks you through setting up the SuccessFactors integration. There are 2 different levels of integration that will be covered:

  • Basic Integration - This allows you to upload candidates from Gem into SuccessFactors and checks for any existing candidate records to prevent creating duplicates.
  • Advanced Integration - This allows you to use Talent Compass features if they have been enabled for your team.

 

Requirements

These are the requirements you must meet in order to set up the SuccessFactors integration:

  • Your team's ATS has been set to SuccessFactors in Gem. (This can be done by your Gem Customer Success Manager.)

  • You must be a Gem Admin.

  • You must be a SuccessFactors admin with the following permissions:

    • Manage Integration Tools

    • Manage OAuth2 Client Applications

 

Setting Up the Integration

Basic Integration

Most of the work that you'll need to do in order to set up the SuccessFactors integration will take place in SuccessFactors. There, you will create and copy the required fields of information into Gem in order to connect the two platforms together.

 

Part 1: Setup in SuccessFactors

First, you'll need to register Gem as a client application in SuccessFactors. General steps are detailed below, but additional guidance can be found in the SuccessFactors Help Portal here.

  1. Log into SuccessFactors using your administrator account. 

  2. Go to your Admin Center > API Center > OAuth Configuration for OData and choose Register Client Application. 
  3. On the new OAuth client registration screen, enter in the following information:
Field Description
Company The name of your company. This should be pre-filled.
Application Name Any unique name will do. We suggest "Gem" or "Gem Client" for easy identification. 
Description (Optional)
Application URL www.gem.com
Bind to Users (Optional) You can enable this option to restrict the access of Gem to specific users.
User IDs (Required if you enabled the Bind to Users option)
X.509 Certificate (Required) Go to your Team Settings page in Gem to generate the certificate, copy it, and add it here.

 

Part 2: Setup in Gem

mceclip0.png

Gem needs the following pieces of information from SuccessFactors. See below on how to get them and have the fields ready to be copy/pasted into your Gem Team Settings page:

  • Company ID
  • SuccessFactors username
  • Application URL
  • API Key (Client ID)

Company ID - In SuccessFactors, click on your profile button in the top-right corner and select "Show version information". A pop-up will appear with information about your instance and we are looking for the Company ID field. It might look something like "SFCPART000123".

SuccessFactors username - This will be the username/account that Gem will need access to in order to make calls to the SuccessFactors API and get your team's data from it. The user needs to be set up with the appropriate permissions and while it can technically be your own username, we highly recommend creating a new user instead of using your own for the specific purpose of this integration. That way, if you leave the company or have your permissions changed, the SuccessFactors integration does not break for your entire team. Click here to jump to the section in this article where we guide you through creating a SuccessFactors user and list the permissions needed.

Application URL - This will be your SuccessFactors instance's URL. Simply head to SuccessFactors and copy the link to any page. Gem will automatically update the link's formatting behind the scenes and prefix it with "api" after you save the configuration. For example, if your SuccessFactors URL is https://salesdemo8.successfactors.com, Gem will automatically update it to https://apisalesdemo8.successfactors.com.

API Key (Client ID) - Once you've registered the Gem application in SuccessFactors using the steps above, a unique API key will be automatically generated and assigned to it. Gem will need the API key, so you can view and copy it after clicking the View option from your registered applications list in SuccessFactors.

 

Additional Steps Library

Creating a SuccessFactors user for Gem (see SuccessFactors username section above):

    1. Create a new user on your SuccessFactors instance. Note the user name that you've chosen. You will need it to enter into Gem.

    2. Create a permission role in Manage Permission Roles.

    3. Depending on your Gem feature set, see list below of Basic or Advanced permissions.

    4. Link this permission role to the new user that you've created in Manage Permission Groups.

Basic Integration

For forwarding the Job Request:

  • Recruiting Permissions OData API Job Requisition Update

For Deduplication & Upload:

  • Recruiting Permissions OData API Candidate Create
  • Recruiting Permissions OData API Candidate Update

 

Advanced Integration (include Basic permissions above, too)

  • Recruiting Permissions OData API Application Export
  • Recruiting Permissions OData API Candidate Export
  • Recruiting Permissions OData API Job Requisition Export
  • Recruiting Permissions OData API Application Audit Export

 

Advanced Integration

Once you are done setting up the Basic integration, you can proceed with this portion. Your team's Gem Customer Success Manager will play a significant role, so get in touch with them if you haven't already done so. If you are not sure who this individual is, please email our Support team at support@gem.com to check.
 
The main objective of the following steps will be so that Gem can be configured to account for bespoke or unique aspects of your SuccessFactors instance that are non-standard, such as field names.
 

Part 1: Mapping your team's field names to the standard SuccessFactors field names

As an example, the standard field named "School" on the entity "CandidateEducation" could be named differently across different organizations. This field may be named something such as "SchoolName" or "Education", etc. in your SuccessFactors instance. Understanding which fields have bespoke names in your SuccessFactors instance is essential for the proper mapping of your fields to Gem, allowing our system to make sense of your data.
 
To assist with this, your Gem Customer Success Manager will provide a list of all the bespoke field names found in your SuccessFactors instance and make mapping suggestions to the standard field name that most likely corresponds with it. A spreadsheet will be sent to you so that you can confirm the mapping is correct. 
 

Part 2: Marking all relevant fields as "reportable" in SuccessFactors

This will ensure that when Gem makes queries to the SuccessFactors OData API for certain fields, they will be visible and allow you to report on them. For example, with the "Department" field of the "JobApplication" entity in SuccessFactors, you'd be able to create a report and filter by "Department" in Gem and see stats like interview passthrough rates by each department.
 
Similar to Part 1, your Gem Customer Success Manager will obtain a list of all fields that Gem requires which are currently not reportable in your SuccessFactors instance. You will need to get in touch with your SuccessFactors partner to make these fields reportable and then inform your Gem Customer Success Manager once this is complete.
 
Note: There may be fields that you want to report on that are not currently supported in Gem. If you come across this, let your Gem Customer Success Manager know and they'll assist with creating a product feature request for your team so that it can be considered in the future.
 

Part 3: Configuring SuccessFactors webhooks

The main objective of this step is to set up webhooks, allowing SuccessFactors to send Gem real-time updates for certain events, such as job, candidate, or application changes.
  1. Navigate to your SuccessFactors Settings page in Gem.
  2. Under the section labeled "SuccessFactors webhook setup", click on the "eye" icon to reveal the webhook secret code and copy it. You will need it in an upcoming step.
  3. Click the "Download Integration Files" button. A .ZIP folder named "webhook_definitions.zip" will be downloaded to your computer. There will be 3 integration files inside, each titled to reflect a specific type of event in SuccessFactors: "candidateUpdated.icd", "jobRequisitionUpdated.icd", and "applicationUpdated.icd"
  4. Unzip the downloaded folder to extract the 3 files and save them to your computer. Click here for instructions if you're on a Windows computer. If you're on a Mac, click here.
  5. Head over to SuccessFactors and go to the "Integration Center". 
  6. Select "My Integrations".
  7. Click the "+Create" button in the upper-righthand corner and select "Import an Integration Definition" from the dropdown menu.
  8. Select any of the 3 files that were downloaded earlier and click "Upload".
  9. On the following page, go to the "Destination Settings" tab.
  10. In the "Password" field, paste the webhook secret code from Step #2.
  11. Click "Next", then "Save" in the bottom-lefthand corner. In the resulting dropdown menu, click "Save".
  12. Click on "Go to Intelligent Service Center". This should take you to the "Flows" section in the Intelligent Services Center for the file's corresponding event.
  13. Under "Custom Activities", click "Integrations" and select the corresponding integration that you just created (the name will start with "Gem"), then click "Add Integration".
  14. In the top-right corner, click "Actions" and select "Save Flow".
  15. Repeat Steps 5 through 14 for each of the remaining integration files. (You will go through this process a total of 3 times, once for each file.)
After all of the steps from these 3 parts are complete, check in with your Gem Customer Success Manager so they can help verify that your SuccessFactors integration is set up properly. If all looks well, you're done!

 

Have any issues or questions on this topic? Please feel free to contact your dedicated Gem Customer Success Manager directly or our Support team at support@gem.com.

Was this article helpful?