SAP SuccessFactors Connector

Category: API Connectors

Introduction

This document helps you set up a mindzieDataDesigner connector to SAP SuccessFactors. The mindzieDataDesigner is the ETL tool used by mindzieStudio to convert data to process mining event logs. SAP SuccessFactors is a cloud-based Human Experience Management (HXM) suite that provides HR, payroll, talent management, and workforce analytics capabilities. This connector uses the SuccessFactors OData API with OAuth 2.0 authentication to extract HR data for process mining.

Overview

The SAP SuccessFactors connector uses the OData v2 API to provide secure, read-only access to SuccessFactors data. This connector supports OAuth 2.0 authentication with SAML 2.0 bearer assertion using X.509 certificates, which is the recommended authentication method for server-to-server integrations.

Key capabilities:

  • Extract Employee Central data (employee profiles, employment history, org structure)
  • Access time management, payroll, and talent data
  • Read-only access ensuring data integrity
  • Secure OAuth 2.0 authentication with X.509 certificates

System Requirements

  • SAP SuccessFactors instance with API access enabled
  • Administrator access to SuccessFactors Admin Center
  • Ability to create and manage API users and OAuth applications

Prerequisites

Before configuring the connector, ensure you have:

  • Admin Center Access: Permission to access the SuccessFactors Admin Center
  • User Management: Permission to create technical/API users
  • OAuth Configuration: Permission to register OAuth2 client applications
  • Role-Based Permissions (RBP): Permission to create and assign permission groups and roles
  • Certificate Management: Ability to generate or obtain X.509 certificates

Credentials Required by mindzie

After completing the setup, provide the following credentials to mindzie:

Credential Description Example
Company ID Your SuccessFactors company identifier mycompanyPROD
API Server URL OData API endpoint for your data center https://api15.sapsf.com
Technical User ID Username of the API service account mindzie_api_user
API Key Client ID from OAuth application registration NGYzNzg1YjctZDM4...
Private Key Private key from X.509 certificate (Certificate.pem) (PEM file contents)

Step 1: Determine Your API Server URL

SAP SuccessFactors uses different data centers. Your API server URL depends on which data center hosts your instance.

Data Center to API URL Mapping

Data Center Location API Server URL
DC2 Amsterdam https://api2.successfactors.eu
DC4 Ashburn https://api4.successfactors.com
DC5 Sydney https://api5.successfactors.com
DC8 Frankfurt https://api8.successfactors.eu
DC10 Ashburn (US Gov) https://api10.successfactors.com
DC12 Amsterdam https://api012.successfactors.eu
DC15 Shanghai https://api15.sapsf.cn
DC17 Ashburn https://api17.sapsf.com
DC18 Rot https://api18.sapsf.eu
DC19 Sydney https://api19.sapsf.com
DC20 Tokyo https://api20.sapsf.com
DC22 Riyadh https://api22.sapsf.com
DC23 Moscow https://api23.sapsf.com
DC24 Frankfurt https://api24.sapsf.eu
DC25 UAE https://api25.sapsf.com
DC26 Singapore https://api26.sapsf.com
DC27 Mumbai https://api27.sapsf.com
DC28 Canada https://api28.sapsf.com

Finding your data center:

  1. Log into SuccessFactors
  2. Look at the URL in your browser - the data center is typically indicated in the domain (e.g., performancemanager4.successfactors.com indicates DC4)
  3. Or contact your SuccessFactors administrator

Step 2: Find Your Company ID

  1. Log into SAP SuccessFactors Admin Center
  2. Navigate to Company Settings or Company System and Logo Settings
  3. The Company ID is displayed on this page
  4. This is typically a string like mycompanyPROD or ACME_Corp_Production

Alternative method:

  • Check your SuccessFactors login URL - the company ID is often part of the URL
  • Contact your SuccessFactors administrator

Step 3: Create a Technical API User

Create a dedicated service account for the mindzie integration. This user should never be used for interactive logins.

  1. Go to Admin Center -> Manage Employees
  2. Click Add New Employee or Add New User
  3. Fill in the required fields:
    • Username: mindzie_api_user (or your preferred naming convention)
    • First Name: mindzie
    • Last Name: API Service
    • Email: A monitored service account email address
  4. Set a secure password (this will be used for initial setup only)
  5. Important: This user should be flagged as a "technical user" or "service account" if your instance supports this distinction
  6. Save the user

Note: Record the username - this will be provided to mindzie as the Technical User ID.

Step 4: Create a Permission Group

Create a permission group to manage API access permissions.

  1. Go to Admin Center -> Manage Permission Groups
  2. Click Create New to create a new permission group
  3. Configure the group:
    • Group Name: mindzie_API_Access (or similar)
    • Description: Permission group for mindzie process mining API access
  4. Add the technical user created in Step 3 to this group
  5. Save the permission group

Step 5: Create a Read-Only Permission Role

Create a role that grants read-only access to the data required for process mining.

  1. Go to Admin Center -> Manage Permission Roles

  2. Click Create New to create a new role

  3. Configure the role:

    • Role Name: mindzie_ReadOnly_Role
    • Description: Read-only access for mindzie process mining integration

  4. Grant Permission Group: Assign the permission group created in Step 4

  5. Configure Permissions: Enable the following permissions based on your data requirements:

Administrator Permissions

Permission Description
Admin access to OData API Required for API access
Admin access to Metadata Framework Access to entity metadata

User Permissions

Permission Description
Employee Central OData API Access to Employee Central data
Time Management OData API Access to time tracking data
Compensation OData API Access to compensation data

Employee Data Permissions

Permission Description
Employee Data - View View employee profile information
Employment Details - View View employment history
Job Information - View View job and position data
Organizational Data - View View org structure
Personal Information - View View personal details
Compensation Information - View View salary and comp data

Note: Grant only the minimum permissions required for your process mining use case. The specific permissions needed depend on which SuccessFactors modules and data you need to analyze.

  1. Save the permission role

Step 6: Register OAuth2 Client Application

Register an OAuth2 client application for secure API authentication.

6.1 Generate X.509 Certificate

You need an X.509 certificate for OAuth authentication. You can either:

  • Use an existing enterprise certificate
  • Generate a self-signed certificate

To generate a self-signed certificate (using OpenSSL):

# Generate private key and certificate (valid for 2 years)
openssl req -newkey rsa:2048 -nodes -keyout private_key.pem -x509 -days 730 -out certificate.pem -subj "/CN=mindzie-sf-integration/O=Your Company/C=US"

Important: Keep the private key (private_key.pem) secure. This will be provided to mindzie.

6.2 Register the OAuth Application

  1. Go to Admin Center -> Manage OAuth2 Client Applications

  2. Click Register Client Application

  3. Configure the application:

    • Application Name: mindzie Process Mining Integration
    • Description: OAuth2 client for mindzie data extraction
    • Application URL: https://mindzie.com (or as provided by mindzie)

  4. Upload X.509 Certificate:

    • Upload the certificate.pem file generated above
    • The certificate is used to sign the SAML assertion

  5. API Access:

    • Select the APIs this application can access
    • At minimum, enable OData API access

  6. Click Register to complete the registration

  7. Record the API Key: After registration, the system displays an API Key (also called Client ID). Record this value - it will be provided to mindzie.

Step 7: Provide Credentials to mindzie

Securely transmit the following credentials to mindzie:

Credential Value
Company ID Your company identifier from Step 2
API Server URL Your data center URL from Step 1
Technical User ID Username from Step 3
API Key Client ID from Step 6
Private Key Contents of private_key.pem from Step 6.1

Security recommendations:

  • Use secure file transfer or encrypted email
  • Never send all credentials in a single message
  • Consider using a secure credential sharing service
  • Delete temporary copies after transmission

Required SuccessFactors Permissions Summary

The following permissions are required for the mindzie integration:

Minimum Required Permissions

  • Admin access to OData API
  • Employee Central OData API (for Employee Central data)
  • Employee Data - View
  • Employment Details - View
  • Job Information - View
  • Organizational Data - View
  • Personal Information - View
  • Compensation Information - View
  • Time Management OData API
  • Compensation OData API

Testing the Connection (Optional)

You can verify your API configuration using the SAP Business Accelerator Hub:

  1. Go to SAP Business Accelerator Hub
  2. Search for "SAP SuccessFactors" APIs
  3. Use the "Try Out" feature with your credentials
  4. Test a simple query like retrieving the company information entity

Alternative: Using cURL

# This is a simplified example - actual OAuth flow is more complex
curl -X GET "https://[your-api-server]/odata/v2/User?$top=1" \
  -H "Authorization: Bearer [your-oauth-token]" \
  -H "Accept: application/json"

Firewall Configuration

Outbound Access Required

mindzie servers need outbound HTTPS access to your SuccessFactors data center:

Port Protocol Destination Purpose
443 HTTPS Your API Server URL (from Step 1) OData API calls

No Inbound Ports Required

The mindzie integration is entirely outbound from mindzie to SuccessFactors. No inbound firewall rules are required on your network.

IP Whitelisting (Optional)

For enhanced security, you can restrict API access to mindzie IP addresses:

  1. Contact mindzie support to obtain the current IP addresses
  2. Configure IP restrictions in SuccessFactors Admin Center if supported
  3. Or configure your network firewall to allow only mindzie IPs to reach SuccessFactors

Revoking Access

If you need to disable the mindzie integration:

Immediate Revocation

  1. Go to Admin Center -> Manage OAuth2 Client Applications
  2. Find the mindzie application
  3. Click Revoke or Disable to immediately invalidate the OAuth credentials

Complete Removal

  1. Revoke the OAuth application (above)
  2. Delete or deactivate the technical API user created in Step 3
  3. Remove the permission role created in Step 5
  4. Remove the permission group created in Step 4

Troubleshooting

OAuth Authentication Errors

"Invalid client credentials"

  • Verify the API Key (Client ID) is correct
  • Ensure the OAuth application is not revoked or disabled
  • Check that the X.509 certificate has not expired

"SAML assertion failed"

  • Verify the private key matches the certificate registered in SuccessFactors
  • Ensure the Technical User ID is correct and the user is active
  • Check that the Company ID is correct

Permission Denied Errors

"Insufficient privileges"

  • Verify the technical user is assigned to the correct permission group
  • Check that the permission role has the required API permissions enabled
  • Ensure Admin access to OData API is granted

"Entity not accessible"

  • The specific entity may require additional permissions
  • Check RBP settings for the entity in question
  • Consult SAP documentation for entity-specific permissions

Certificate Issues

"Certificate expired"

  • Generate a new X.509 certificate
  • Update the certificate in the OAuth application registration
  • Provide the new private key to mindzie

"Certificate not trusted"

  • For self-signed certificates, ensure the certificate is properly uploaded
  • For enterprise certificates, verify the certificate chain

API Rate Limits

SAP SuccessFactors enforces API rate limits. If you encounter rate limiting:

  • mindzie implements appropriate throttling
  • Contact SAP support for rate limit increases if needed
  • Consider filtering data at the query level to reduce API calls

Connection Timeout

"Connection timed out"

  • Verify the API Server URL is correct for your data center
  • Check network connectivity and firewall rules
  • Ensure SuccessFactors is not experiencing an outage

Sources and References

This documentation is based on the following sources:

Official SAP Documentation

SAP Community Resources