SAP SuccessFactors Connector

Kategorie: API-Connectoren

Einführung

Dieses Dokument hilft Ihnen, einen mindzieDataDesigner-Connector für SAP SuccessFactors einzurichten. Der mindzieDataDesigner ist das ETL-Tool, das von mindzieStudio verwendet wird, um Daten in Process Mining Ereignisprotokolle umzuwandeln. SAP SuccessFactors ist eine cloudbasierte Human Experience Management (HXM)-Suite, die HR-, Gehalts-, Talentmanagement- und Workforce-Analytics-Funktionen bietet. Dieser Connector verwendet die SuccessFactors OData API mit OAuth 2.0-Authentifizierung zur Extraktion von HR-Daten für Process Mining.

Überblick

Der SAP SuccessFactors Connector verwendet die OData v2 API, um sicheren, schreibgeschützten Zugriff auf SuccessFactors-Daten zu bieten. Dieser Connector unterstützt OAuth 2.0-Authentifizierung mit SAML 2.0-Bearer-Assertion unter Verwendung von X.509-Zertifikaten, was die empfohlene Authentifizierungsmethode für Server-zu-Server-Integrationen ist.

Wesentliche Funktionen:

  • Extraktion von Employee Central-Daten (Mitarbeiterprofile, Beschäftigungsverlauf, Organisationsstruktur)
  • Zugriff auf Zeitmanagement-, Gehalts- und Talentdaten
  • Schreibgeschützter Zugriff zur Wahrung der Datenintegrität
  • Sichere OAuth 2.0-Authentifizierung mit X.509-Zertifikaten

Systemanforderungen

  • SAP SuccessFactors-Instanz mit aktiviertem API-Zugriff
  • Administratorzugang zum SuccessFactors Admin Center
  • Möglichkeit zur Erstellung und Verwaltung von API-Benutzern und OAuth-Anwendungen

Voraussetzungen

Bevor Sie den Connector konfigurieren, stellen Sie sicher, dass Sie über folgende Berechtigungen verfügen:

  • Admin Center Zugriff: Berechtigung zum Zugriff auf das SuccessFactors Admin Center
  • Benutzerverwaltung: Berechtigung zur Erstellung technischer/API-Benutzer
  • OAuth-Konfiguration: Berechtigung zur Registrierung von OAuth2-Client-Anwendungen
  • Rollenbasierte Berechtigungen (RBP): Berechtigung zur Erstellung und Zuweisung von Berechtigungsgruppen und Rollen
  • Zertifikatsverwaltung: Fähigkeit, X.509-Zertifikate zu erstellen oder zu erhalten

Von mindzie benötigte Zugangsdaten

Nach Abschluss der Einrichtung stellen Sie bitte mindzie die folgenden Zugangsdaten zur Verfügung:

Zugangsdaten Beschreibung Beispiel
Company ID Ihre SuccessFactors Firmenkennung mycompanyPROD
API Server URL OData API-Endpunkt für Ihr Datenzentrum https://api15.sapsf.com
Technical User ID Benutzername des API-Dienstkontos mindzie_api_user
API Key Client ID aus der OAuth-Anwendungsregistrierung NGYzNzg1YjctZDM4...
Private Key Privater Schlüssel aus dem X.509-Zertifikat (Certificate.pem) (PEM-Datei Inhalt)

Schritt 1: Bestimmen Sie Ihre API Server URL

SAP SuccessFactors verwendet verschiedene Rechenzentren. Ihre API Server-URL hängt davon ab, welches Rechenzentrum Ihre Instanz hostet.

Zuordnung Rechenzentrum zu API URL

Rechenzentrum Standort 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 Moskau https://api23.sapsf.com
DC24 Frankfurt https://api24.sapsf.eu
DC25 VAE https://api25.sapsf.com
DC26 Singapur https://api26.sapsf.com
DC27 Mumbai https://api27.sapsf.com
DC28 Kanada https://api28.sapsf.com

So finden Sie Ihr Rechenzentrum:

  1. Melden Sie sich bei SuccessFactors an
  2. Schauen Sie sich die URL im Browser an – das Rechenzentrum ist meist im Domainnamen enthalten (z.B. zeigt performancemanager4.successfactors.com auf DC4)
  3. Oder kontaktieren Sie Ihren SuccessFactors Administrator

Schritt 2: Finden Sie Ihre Company ID

  1. Melden Sie sich beim SAP SuccessFactors Admin Center an
  2. Navigieren Sie zu Company Settings oder Company System and Logo Settings
  3. Die Company ID wird auf dieser Seite angezeigt
  4. Dies ist normalerweise ein String wie mycompanyPROD oder ACME_Corp_Production

Alternative Methode:

  • Prüfen Sie Ihre SuccessFactors Login-URL - die Company ID ist oft Teil der URL
  • Kontaktieren Sie Ihren SuccessFactors Administrator

Schritt 3: Erstellen Sie einen technischen API-Benutzer

Erstellen Sie ein dediziertes Service-Konto für die mindzie-Integration. Dieser Benutzer sollte niemals für interaktive Logins verwendet werden.

  1. Gehen Sie zu Admin Center -> Manage Employees
  2. Klicken Sie auf Add New Employee oder Add New User
  3. Füllen Sie die erforderlichen Felder aus:
    • Benutzername: mindzie_api_user (oder Ihre bevorzugte Namenskonvention)
    • Vorname: mindzie
    • Nachname: API Service
    • E-Mail: Eine überwachte Service-Account-E-Mail-Adresse
  4. Setzen Sie ein sicheres Passwort (dies wird nur für die anfängliche Einrichtung verwendet)
  5. Wichtig: Dieser Benutzer sollte als "technischer Benutzer" oder "Servicekonto" markiert werden, falls Ihre Instanz diese Unterscheidung unterstützt
  6. Speichern Sie den Benutzer

Hinweis: Notieren Sie den Benutzernamen – dieser wird mindzie als Technical User ID übermittelt.

Schritt 4: Erstellen Sie eine Berechtigungsgruppe

Erstellen Sie eine Berechtigungsgruppe zur Verwaltung der API-Zugriffsrechte.

  1. Gehen Sie zu Admin Center -> Manage Permission Groups
  2. Klicken Sie auf Create New, um eine neue Berechtigungsgruppe zu erstellen
  3. Konfigurieren Sie die Gruppe:
    • Gruppenname: mindzie_API_Access (oder ähnlich)
    • Beschreibung: Berechtigungsgruppe für mindzie Process Mining API Zugriff
  4. Fügen Sie den technischen Benutzer aus Schritt 3 dieser Gruppe hinzu
  5. Speichern Sie die Berechtigungsgruppe

Schritt 5: Erstellen Sie eine schreibgeschützte Berechtigungsrolle

Erstellen Sie eine Rolle, die schreibgeschützten Zugriff auf die für das Process Mining benötigten Daten gewährt.

  1. Gehen Sie zu Admin Center -> Manage Permission Roles

  2. Klicken Sie auf Create New, um eine neue Rolle zu erstellen

  3. Konfigurieren Sie die Rolle:

    • Rollenname: mindzie_ReadOnly_Role
    • Beschreibung: Schreibgeschützter Zugriff für mindzie Process Mining Integration

  4. Berechtigungsgruppe zuweisen: Weisen Sie die in Schritt 4 erstellte Berechtigungsgruppe zu

  5. Berechtigungen konfigurieren: Aktivieren Sie folgende Berechtigungen entsprechend Ihrem Datenbedarf:

Administrator-Berechtigungen

Berechtigung Beschreibung
Adminzugang zur OData API Erforderlich für API-Zugriff
Adminzugang zum Metadata Framework Zugriff auf Entitätsmetadaten

Benutzerberechtigungen

Berechtigung Beschreibung
Employee Central OData API Zugriff auf Employee Central-Daten
Time Management OData API Zugriff auf Zeitmanagement-Daten
Compensation OData API Zugriff auf Vergütungsdaten

Mitarbeiterdaten-Berechtigungen

Berechtigung Beschreibung
Employee Data - View Anzeige von Mitarbeiterprofilinformationen
Employment Details - View Anzeige des Beschäftigungsverlaufs
Job Information - View Anzeige von Job- und Positionsdaten
Organizational Data - View Anzeige der Organisationsstruktur
Personal Information - View Anzeige persönlicher Details
Compensation Information - View Anzeige von Gehalts- und Vergütungsdaten

Hinweis: Gewähren Sie nur die minimal erforderlichen Berechtigungen für Ihren Process Mining Anwendungsfall. Die benötigten Berechtigungen hängen davon ab, welche SuccessFactors-Module und Daten Sie analysieren möchten.

  1. Speichern Sie die Berechtigungsrolle

Schritt 6: Registrieren Sie eine OAuth2-Clientanwendung

Registrieren Sie eine OAuth2-Clientanwendung für die sichere API-Authentifizierung.

6.1 Erstellen eines X.509-Zertifikats

Sie benötigen ein X.509-Zertifikat für die OAuth-Authentifizierung. Sie können entweder:

  • Ein bestehendes Unternehmenszertifikat verwenden
  • Ein selbstsigniertes Zertifikat generieren

Erzeugen eines selbstsignierten Zertifikats (mit OpenSSL):

# Erzeugt privaten Schlüssel und Zertifikat (gültig für 2 Jahre)
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"

Wichtig: Bewahren Sie den privaten Schlüssel (private_key.pem) sicher auf. Dieser wird an mindzie übergeben.

6.2 Registrieren der OAuth-Anwendung

  1. Gehen Sie zu Admin Center -> Manage OAuth2 Client Applications

  2. Klicken Sie auf Register Client Application

  3. Konfigurieren Sie die Anwendung:

    • Anwendungsname: mindzie Process Mining Integration
    • Beschreibung: OAuth2 Client für mindzie Datenextraktion
    • Anwendungs-URL: https://mindzie.com (oder wie von mindzie vorgegeben)

  4. X.509-Zertifikat hochladen:

    • Laden Sie die zuvor generierte Datei certificate.pem hoch
    • Das Zertifikat wird verwendet, um die SAML Assertion zu signieren

  5. API-Zugriff:

    • Wählen Sie die APIs aus, auf die diese Anwendung zugreifen kann
    • Aktivieren Sie mindestens den OData API Zugriff

  6. Klicken Sie auf Register, um die Registrierung abzuschließen

  7. API Key notieren: Nach der Registrierung zeigt das System einen API Key (auch Client ID genannt) an. Notieren Sie diesen Wert – er wird mindzie übergeben.

Schritt 7: Übermitteln Sie die Zugangsdaten an mindzie

Übermitteln Sie mindzie sicher folgende Zugangsdaten:

Zugangsdaten Wert
Company ID Firmenkennung aus Schritt 2
API Server URL URL Ihres Rechenzentrums aus Schritt 1
Technical User ID Benutzername aus Schritt 3
API Key Client ID aus Schritt 6
Private Key Inhalt von private_key.pem aus Schritt 6.1

Sicherheits-Empfehlungen:

  • Nutzen Sie sichere Dateiübertragung oder verschlüsselte E-Mail
  • Senden Sie niemals alle Zugangsdaten in einer einzigen Nachricht
  • Nutzen Sie ggf. einen sicheren Dienst zum Teilen von Zugangsdaten
  • Löschen Sie temporäre Kopien nach der Übertragung

Zusammenfassung der erforderlichen SuccessFactors-Berechtigungen

Folgende Berechtigungen sind für die mindzie-Integration erforderlich:

Mindestanforderungen

  • Adminzugang zur OData API
  • Employee Central OData API (für Employee Central-Daten)
  • Employee Data - View
  • Employment Details - View

Empfohlene Zusatzberechtigungen (je nach Anwendungsfall)

  • Job Information - View
  • Organizational Data - View
  • Personal Information - View
  • Compensation Information - View
  • Time Management OData API
  • Compensation OData API

Verbindungstest (optional)

Sie können Ihre API-Konfiguration mit dem SAP Business Accelerator Hub überprüfen:

  1. Gehen Sie zu SAP Business Accelerator Hub
  2. Suchen Sie nach "SAP SuccessFactors" APIs
  3. Nutzen Sie die Funktion „Try Out“ mit Ihren Zugangsdaten
  4. Testen Sie eine einfache Abfrage, z.B. zum Abrufen der Firmeninformationen-Entität

Alternativ: Verwendung von cURL

# Dies ist ein vereinfachtes Beispiel – der tatsächliche OAuth-Flow ist komplexer
curl -X GET "https://[your-api-server]/odata/v2/User?$top=1" \
  -H "Authorization: Bearer [your-oauth-token]" \
  -H "Accept: application/json"

Firewall-Konfiguration

Ausgehender Zugriff erforderlich

Die mindzie-Server benötigen ausgehenden HTTPS-Zugriff auf Ihr SuccessFactors-Rechenzentrum:

Port Protokoll Ziel Zweck
443 HTTPS Ihre API Server URL (aus Schritt 1) OData API-Anfragen

Keine eingehenden Ports erforderlich

Die mindzie-Integration ist vollständig ausgehend von mindzie zu SuccessFactors. Es sind keine eingehenden Firewall-Regeln in Ihrem Netzwerk erforderlich.

IP-Whitelist (optional)

Für erhöhte Sicherheit können Sie den API-Zugriff auf mindzie IP-Adressen beschränken:

  1. Kontaktieren Sie den mindzie Support, um die aktuellen IP-Adressen zu erhalten
  2. Konfigurieren Sie IP-Beschränkungen im SuccessFactors Admin Center, falls unterstützt
  3. Alternativ konfigurieren Sie Ihre Netzwerkfirewall, um nur mindzie IPs Zugriff auf SuccessFactors zu erlauben

Zugang widerrufen

Wenn Sie die mindzie-Verbindung deaktivieren möchten:

Sofortiger Widerruf

  1. Gehen Sie zu Admin Center -> Manage OAuth2 Client Applications
  2. Finden Sie die mindzie-Anwendung
  3. Klicken Sie auf Revoke oder Disable, um die OAuth-Zugangsdaten sofort ungültig zu machen

Vollständige Entfernung

  1. Widerrufen Sie die OAuth-Anwendung (siehe oben)
  2. Löschen oder deaktivieren Sie den technischen API-Benutzer aus Schritt 3
  3. Entfernen Sie die Berechtigungsrolle aus Schritt 5
  4. Entfernen Sie die Berechtigungsgruppe aus Schritt 4

Fehlerbehebung

OAuth Authentifizierungsfehler

„Ungültige Client-Zugangsdaten“

  • Prüfen Sie, ob der API Key (Client ID) korrekt ist
  • Stellen Sie sicher, dass die OAuth-Anwendung nicht widerrufen oder deaktiviert ist
  • Prüfen Sie, ob das X.509-Zertifikat noch gültig ist

„SAML Assertion fehlgeschlagen“

  • Überprüfen Sie, ob der private Schlüssel zum registrierten Zertifikat passt
  • Stellen Sie sicher, dass die Technical User ID korrekt und der Benutzer aktiv ist
  • Prüfen Sie die Company ID auf Richtigkeit

Berechtigungsverweigerung

„Unzureichende Rechte“

  • Prüfen Sie, ob der technische Benutzer der korrekten Berechtigungsgruppe zugewiesen ist
  • Stellen Sie sicher, dass die Berechtigungsrolle die erforderlichen API-Berechtigungen aktiviert hat
  • Vergewissern Sie sich, dass Adminzugang zur OData API erteilt wurde

„Entität nicht zugänglich“

  • Die betroffene Entität benötigt möglicherweise zusätzliche Berechtigungen
  • Prüfen Sie die RBP-Einstellungen für die jeweilige Entität
  • Konsultieren Sie die SAP-Dokumentation zu entitätsspezifischen Berechtigungen

Zertifikatprobleme

„Zertifikat abgelaufen“

  • Erstellen Sie ein neues X.509-Zertifikat
  • Aktualisieren Sie das Zertifikat in der OAuth-Anwendungsregistrierung
  • Übermitteln Sie den neuen privaten Schlüssel an mindzie

„Zertifikat nicht vertrauenswürdig“

  • Bei selbstsignierten Zertifikaten stellen Sie sicher, dass das Zertifikat korrekt hochgeladen wurde
  • Bei Unternehmenszertifikaten überprüfen Sie die Zertifikatskette

API-Ratenlimits

SAP SuccessFactors setzt API-Ratenlimits durch. Wenn Sie Limits erreichen:

  • mindzie verwendet entsprechende Drosselungsmechanismen
  • Wenden Sie sich ggf. an den SAP-Support, um Ratenlimits zu erhöhen
  • Erwägen Sie, Daten auf Abfrageebene zu filtern, um API-Aufrufe zu reduzieren

Verbindungszeitüberschreitung

„Verbindung timeout“

  • Prüfen Sie, ob die API Server URL korrekt für Ihr Rechenzentrum ist
  • Überprüfen Sie die Netzwerkverbindung und Firewall-Regeln
  • Stellen Sie sicher, dass SuccessFactors keine Störung hat

Verwandte Informationen

Quellen und Referenzen

Diese Dokumentation basiert auf folgenden Quellen:

Offizielle SAP-Dokumentation

SAP Community Ressourcen