Datenquellen & Connectoren

Mit Datenquellen verbindest du externe HR- und Verzeichnis-Systeme als Master-Quellen mit roleALPHA. Sobald ein Connector ein Ziel-Modul beansprucht, werden dessen Entitäten automatisch synchronisiert — Anlegen, Bearbeiten und Löschen dieser Entitäten wird für alle gesperrt, da das externe System die alleinige Datenhoheit besitzt. Die Sperre gilt für die manuelle Bearbeitung in der Oberfläche, für Administratoren und für den KI-Assistenten rAlph (er kann keine Entwürfe auf gesynchten Entitäten anlegen). Nur das Sync-System selbst schreibt weiter.

Was ändert sich mit einem Connector?

Eigenschaft	Ohne Connector	Mit Connector
Entitäten anlegen	Manuell / per rAlph	Nur externes System (🔒 manuell + rAlph gesperrt)
Entitäten bearbeiten	Manuell / per rAlph	Gesperrt (🔒 externes System)
Entitäten löschen	Manuell	Gesperrt (🔒 nur über Quellsystem)
JSON-Schema	Frei konfigurierbar	Durch Connector bestimmt
Sync-Quelle	—	Externer Dienst (z.B. EntraID)
Anmeldeadresse	Nur ausdrücklich pflegbar	Folgt dem Personendatensatz automatisch (🔒 manuell gesperrt)

Entitäten, die per Connector synchronisiert wurden, tragen in der Listenansicht ein Cloud-Badge mit dem Namen des externen Systems.

Die Anmeldeadresse zieht mit. Synchronisiert eine Datenquelle die Personen, gilt sie auch als Eigentümerin der Anmeldeadresse (Anmeldung verwalten in der Benutzerverwaltung): das Feld ist dort gesperrt, und nach jedem Abgleich wird die Adresse aus dem Personendatensatz übernommen. Ohne dieses Mitziehen wäre eine Adressänderung im Quellsystem eine dauerhafte Aussperrung — die Sperre verhindert ja auch die Reparatur. Wird die Datenquelle wieder entfernt, ist das Feld sofort wieder pflegbar; die zuletzt übernommene Adresse bleibt stehen.

Eine Datenquelle pro Ziel-Modul: Jedes Ziel-Modul (Personen, Organigramm, Kostenstellen, …) darf von höchstens einer Datenquelle bespielt werden. Sobald z.B. EntraID die Personen synchronisiert, lässt sich SuccessFactors (oder SAP FI) nicht zusätzlich für Personen einrichten — das jeweilige Ziel ist im Setup-Dialog gesperrt und ein Speichern wird mit einem Hinweis abgelehnt. Um den Master zu wechseln, entferne zuerst die bestehende Datenquelle oder passe deren Ziele an. So konkurrieren nie zwei Systeme um dieselben Entitäten.

Microsoft Entra ID einrichten

Entra ID (ehemals Azure Active Directory) synchronisiert Mitarbeiter als Personen und Gruppen als Organigramm-Einträge.

Voraussetzungen

1. Im Azure-Portal eine App-Registrierung anlegen
2. API-Berechtigung User.Read.All (Application) + GroupMember.Read.All vergeben und Admin-Zustimmung erteilen
3. Ein Client-Geheimnis erstellen

Wie EntraID Entitäten erkennt und zuordnet

Beim ersten Sync legt ra-connect für jede importierte Entität die AAD Object ID als _syncId in den descJsonb-Daten ab. Bei jedem weiteren Sync lädt ra-connect alle vorhandenen roleALPHA-Entitäten mit _syncSource = "EntraID" und baut daraus eine Map AAD-ID → roleALPHA-UUID — identisch zum Muster des CSV-Importers. Dann entscheidet ra-connect pro Datensatz:

Bedingung	Aktion
AAD-ID nicht in roleALPHA bekannt	CREATE-Draft mit neuer UUID
AAD-ID bereits vorhanden	UPDATE-Draft mit bekannter UUID
@removed in Delta + bekannt	DELETE-Draft → cascadiert alle Beziehungen
@removed + nicht bekannt	Übersprungen (bereits gelöscht)

Beim Full-Sync werden zusätzlich Entitäten gelöscht, die zwar in roleALPHA existieren, aber nicht mehr in EntraID vorhanden sind.

Kein separates Mapping-Table: Die Zuordnung ergibt sich direkt aus descJsonb._syncId in den Entitätsdaten — kein zusätzlicher Speicherort, kein Synchronisationsproblem.

Schritte

1. Navigiere zu Einstellungen → Daten & Struktur → Datenquellen
2. Klicke auf Verbinden bei Microsoft Entra ID
3. Fülle den Setup-Dialog aus:
   • Schritt 1 – Zugangsdaten: Verzeichnis-ID (Tenant), Anwendungs-ID (Client) und Client-Geheimnis eingeben
   • Schritt 2 – Sync-Ziele: Personen und/oder Organigramm auswählen
   • Schritt 3 – Optionen: Sync-Intervall, Konflikt-Strategie und Auto-Freigabe konfigurieren
4. Speichern — der erste Sync startet automatisch

Sync-Verhalten

• Erster Sync: Alle Benutzer und Gruppen werden als Drafts importiert.
• Folge-Syncs (Delta): Nur Änderungen seit dem letzten Sync werden übertragen.
• Felder: Standard-Mapping importiert Name, E-Mail, Titel, Abteilung, Telefon und Standort.

SAP SuccessFactors einrichten

SAP SuccessFactors (Employee Central) synchronisiert Mitarbeiter als Personen, Abteilungen (FODepartment) als Organigramm-Einträge und die managerId als Vorgesetzten-Beziehung (EXECUTES) zwischen Personen.

Voraussetzungen

1. Die OData API v2 muss im SuccessFactors-Mandanten freigeschaltet sein
2. Ein API-Benutzer mit Leseberechtigung auf die Entitäten User und FODepartment
3. Die API-Server-URL deines Rechenzentrums (z.B. https://api4.successfactors.com) sowie die Company-ID

Authentifizierung

Der Connector unterstützt zwei Methoden — wählbar im Setup-Dialog:

Methode	Felder	Wann nutzen
Basic	API-Benutzername + Passwort	Schneller Einstieg; SuccessFactors kombiniert intern zu benutzer@CompanyID
OAuth2 (SAML-Assertion)	OAuth-Client-ID (API-Key), OAuth-Benutzer-ID, privater Schlüssel (PEM)	Empfohlen für Produktion; der Connector holt automatisch eine signierte SAML-Assertion vom SF-IdP und tauscht sie gegen ein Access-Token

Passwort und privater Schlüssel werden verschlüsselt (AES-256-GCM) gespeichert und nie im Klartext an die Oberfläche zurückgegeben.

Wie SuccessFactors Entitäten erkennt und zuordnet

Wie bei EntraID legt ra-connect die externe ID als _syncId in den descJsonb-Daten ab — für Personen die userId, für Abteilungen den externalCode. Als _syncSource wird SuccessFactors gesetzt. Vor jedem Sync wird daraus eine Map externe ID → roleALPHA-UUID aufgebaut:

Bedingung	Aktion
ID nicht in roleALPHA bekannt	CREATE-Draft mit neuer UUID
ID bereits vorhanden	UPDATE-Draft mit bekannter UUID
status = inaktiv/ausgeschieden + bekannt	DELETE-Draft → cascadiert alle Beziehungen
Full-Sync: in roleALPHA, aber nicht mehr in SuccessFactors	DELETE-Draft

Schritte

1. Navigiere zu Einstellungen → Daten & Struktur → Datenquellen
2. Klicke auf Verbinden bei SAP SuccessFactors
3. Fülle den Setup-Dialog aus:
   • Schritt 1 – Zugangsdaten: API-Server-URL, Company-ID, Authentifizierungsmethode und die jeweiligen Felder
   • Schritt 2 – Sync-Ziele: Personen, Organigramm und/oder Kapazität & Abwesenheiten auswählen
   • Schritt 3 – Optionen: Sync-Intervall, Konflikt-Strategie und Auto-Freigabe konfigurieren
4. Speichern — der erste Sync startet automatisch

Sync-Verhalten

• Erster Sync (Full): Alle aktiven Mitarbeiter und Abteilungen werden als Drafts importiert, anschließend werden Vorgesetzten-Beziehungen erstellt.
• Folge-Syncs (Delta): Nur Datensätze mit geändertem lastModifiedDateTime seit dem letzten Sync werden übertragen.
• Felder: Standard-Mapping importiert Name, E-Mail, Titel, Abteilung, Bereich, Telefon und Standort — sowie, wenn die Bedarfsplanung aktiv ist, Wochenstunden, Beschäftigungsgrad und Beschäftigungsart.

Kapazität & Abwesenheiten als Sync-Ziel

Dieses Ziel ist der einzige, das keine Entitäten mastert: es liefert die periodengenaue Arbeitszeit und Abwesenheitszeiträume an die Ressourcenplanung. Bedarfe lassen sich also weiterhin ganz normal anlegen und ändern — gesperrt wird nichts.

Die Abwesenheitsart (Urlaub, Krankheit, …) wird beim Import verworfen; roleALPHA hat kein Feld dafür. Was das bedeutet und welche Regeln beim nächtlichen Lauf gelten, steht in Kapazität aus einem HR-System.

LDAP / Active Directory einrichten

Bindet ein klassisches Active Directory oder einen LDAP-Verzeichnisdienst (z.B. OpenLDAP) an: Benutzer werden als Personen, Gruppen als Organigramm-Einträge und das manager-Attribut als Vorgesetzten-Beziehung (EXECUTES) synchronisiert.

Voraussetzungen

1. Ein Dienstkonto (Bind-DN) mit Leseberechtigung auf den Verzeichnisbaum
2. Die Server-URL — ldap://host:389 (unverschlüsselt) oder ldaps://host:636 (TLS, empfohlen)
3. Die Such-Basis (Base DN), unter der Benutzer und Gruppen liegen (z.B. dc=firma,dc=de)

Verbindung & Filter

Feld	Beschreibung	Standard
Server-URL	ldap:// oder ldaps:// inkl. Port	—
Bind-DN	Dienstkonto, z.B. cn=svc-readonly,ou=Service,dc=firma,dc=de	—
Bind-Passwort	Passwort des Dienstkontos (verschlüsselt gespeichert)	—
Such-Basis	Base DN für die Suche	—
Benutzer-Filter	LDAP-Filter für Personen	(&(objectCategory=person)(objectClass=user))
Gruppen-Filter	LDAP-Filter für Gruppen	(objectClass=group)

Für OpenLDAP statt AD die Filter anpassen, z.B. Benutzer (objectClass=inetOrgPerson) und Gruppen (objectClass=groupOfNames).

Bei ldaps:// mit selbstsigniertem Zertifikat kann die Zertifikatsprüfung optional abgeschaltet werden (Checkbox im Dialog).

Wie LDAP Entitäten erkennt und zuordnet

Als stabile externe ID nutzt ra-connect das objectGUID (Active Directory, binär → GUID-String) bzw. entryUUID (OpenLDAP), als Fallback den DN. Diese wird als _syncId mit _syncSource = "LDAP" in den descJsonb-Daten abgelegt. Vor jedem Sync entsteht daraus eine Map objectGUID → roleALPHA-UUID:

Bedingung	Aktion
ID nicht in roleALPHA bekannt	CREATE-Draft mit neuer UUID
ID bereits vorhanden	UPDATE-Draft mit bekannter UUID
Full-Sync: in roleALPHA, aber nicht mehr im Verzeichnis	DELETE-Draft → cascadiert alle Beziehungen

Die Vorgesetzten-Beziehung entsteht aus dem manager-Attribut (ein DN, der auf einen anderen Benutzer zeigt) — innerhalb eines Sync-Laufs zu EXECUTES-Beziehungen aufgelöst.

Schritte

1. Navigiere zu Einstellungen → Daten & Struktur → Datenquellen
2. Klicke auf Verbinden bei LDAP / Active Directory
3. Fülle den Setup-Dialog aus:
   • Schritt 1 – Zugangsdaten: Server-URL, Bind-DN, Bind-Passwort, Such-Basis und ggf. Filter
   • Schritt 2 – Sync-Ziele: Personen und/oder Organigramm auswählen
   • Schritt 3 – Optionen: Sync-Intervall, Konflikt-Strategie und Auto-Freigabe konfigurieren
4. Speichern — der erste Sync startet automatisch

Sync-Verhalten

• Erster Sync (Full): Alle passenden Benutzer und Gruppen werden als Drafts importiert, anschließend Vorgesetzten-Beziehungen erstellt.
• Folge-Syncs (Delta): Nur Einträge mit geändertem whenChanged (Active Directory; OpenLDAP: modifyTimestamp) seit dem letzten Sync.
• Felder: Standard-Mapping importiert Name, E-Mail, Titel, Abteilung, Telefon und Standort.

SAP FI einrichten

SAP FI bindet die Finanzbuchhaltung/CO aus SAP S/4HANA an und synchronisiert primär Kostenstellen. Optional lassen sich auch Personen (Geschäftspartner) und Organisationseinheiten (Kostenstellen-Standardhierarchie) übernehmen. Die Anbindung erfolgt über die OData-v2-Standard-APIs (z.B. API_COSTCENTER_SRV, API_BUSINESS_PARTNER).

Voraussetzungen

1. Erreichbare OData-v2-Endpunkte der S/4HANA-Instanz
2. Ein API-Benutzer mit Lesezugriff auf die Kostenstellen-Stammdaten
3. Die OData-Server-URL und der Buchungskreis (Company Code)

Wie SAP FI Kostenstellen erkennt und zuordnet

Die externe Kostenstellen-Nummer (CostCenter) wird als _syncId mit _syncSource = "SAP-FI" in den descJsonb-Daten abgelegt. Vor jedem Sync entsteht daraus eine Map CostCenter → roleALPHA-UUID (CREATE bei unbekannt, UPDATE bei bekannt, Full-Sync-DELETE für entfallene Sätze). Da das Kostenstellen-Schema das Pflichtfeld costCenterType verlangt, setzt der Connector hierfür den Standardwert „Hauptkostenstelle”; weitere Felder (Beschreibung, Buchungskreis, Verantwortlich, übergeordnete Hierarchie) landen ebenfalls in descJsonb.

Schritte

1. Navigiere zu Einstellungen → Daten & Struktur → Datenquellen
2. Klicke auf Verbinden bei SAP FI
3. Fülle den Setup-Dialog aus:
   • Schritt 1 – Zugangsdaten: OData-Server-URL, Buchungskreis, API-Benutzername und Passwort
   • Schritt 2 – Sync-Ziele: Kostenstellen (Standard) und optional Personen/Organigramm
   • Schritt 3 – Optionen: Sync-Intervall, Konflikt-Strategie und Auto-Freigabe
4. Speichern — der erste Sync startet automatisch

MS Dynamics einrichten

MS Dynamics bindet Microsoft Dynamics 365 Finance & Operations an und synchronisiert primär Kostenstellen (Finanzdimension „CostCenter”). Optional auch Mitarbeiter (Workers) und Organisationseinheiten (OMOperatingUnits). Die Anbindung nutzt die OData-v4-Data-Entities und authentifiziert sich über den Azure-AD-Client-Credentials-Flow.

Voraussetzungen

1. Eine App-Registrierung in Azure AD mit Zugriff auf die Dynamics-Umgebung
2. Verzeichnis-ID (Tenant), Anwendungs-ID (Client) und ein Client-Geheimnis
3. Die Dynamics-Umgebungs-URL (z.B. https://contoso.operations.dynamics.com)

Wie MS Dynamics Kostenstellen erkennt und zuordnet

Die CostCenterId wird als _syncId mit _syncSource = "MS-Dynamics" gespeichert. Vor jedem Sync entsteht daraus eine Map CostCenterId → roleALPHA-UUID (CREATE/UPDATE/DELETE wie bei SAP FI). Über IsSuspended gekennzeichnete (deaktivierte) Kostenstellen erzeugen einen DELETE-Draft. Auch hier setzt der Connector das Pflichtfeld costCenterType auf „Hauptkostenstelle”.

Schritte

1. Navigiere zu Einstellungen → Daten & Struktur → Datenquellen
2. Klicke auf Verbinden bei MS Dynamics
3. Fülle den Setup-Dialog aus:
   • Schritt 1 – Zugangsdaten: Dynamics-Umgebungs-URL, Verzeichnis-ID, Anwendungs-ID und Client-Geheimnis
   • Schritt 2 – Sync-Ziele: Kostenstellen (Standard) und optional Personen/Organigramm
   • Schritt 3 – Optionen: Sync-Intervall, Konflikt-Strategie und Auto-Freigabe
4. Speichern — der erste Sync startet automatisch

Sync-Drafts automatisch freigeben

Standardmäßig landen importierte Daten als Drafts im normalen Freigabe-Flow. Mit der Option „Sync-Drafts automatisch freigeben” werden Drafts direkt nach dem Import von ra-connect selbst freigegeben — ohne manuellen Schritt.

Einstellung	Verhalten
Deaktiviert (Standard)	Drafts erscheinen in der Drafts-Übersicht zur Prüfung
Aktiviert	Drafts werden sofort nach Erstellung freigegeben — Daten sind direkt sichtbar

Wann aktivieren?

• Der Tenant nutzt den liberalen Freigabe-Modus (jeder Tenant-User darf freigeben) — nur dann hat ra-connect die nötigen Rechte
• Du vertraust dem externen System vollständig als Master-Quelle
• Du möchtest keinen manuellen Prüfschritt zwischen Import und Sichtbarkeit

Wann lieber deaktiviert lassen?

• Der Tenant nutzt Konsens-, Konsent- oder Highlander-Modus — die Auto-Freigabe würde abgelehnt und als Warnung geloggt
• Du möchtest importierte Daten vor der Veröffentlichung prüfen (z.B. beim ersten Import)

Hinweis: Im Freigabe-Log erscheint bei aktivierter Auto-Freigabe der Eintrag „Auto-Approve abgeschlossen: X/Y freigegeben”. Fehlgeschlagene Einzelfreigaben erzeugen einen Warn-Log-Eintrag, brechen den Sync aber nicht ab.

Pflichtfelder gelten auch beim Sync

Seit August 2026 setzt die Plattform die Pflichtfelder des Entitätstyp-Schemas beim Veröffentlichen durch (siehe JSON-Schema für Entitätstypen). Liefert die Quelle ein Pflichtfeld nicht, bleibt der Entwurf stehen — er geht nicht verloren, wird aber nicht freigegeben.

Wichtig zu wissen: Ein solcher Fehlschlag erscheint nur als Warnung im Sync-Log, der Job selbst meldet weiterhin Erfolg. Wenn nach einem Sync Daten fehlen, ist das die erste Stelle zum Nachsehen. Die mitgelieferten Konnektoren füllen die Pflichtfelder von sich aus (Vor- und Nachname bei Personen, Organisationstyp bei Org-Einheiten); betroffen sind vor allem eigene Feldzuordnungen, die ein Pflichtfeld nicht bedienen.

Sync-Verlauf und Logs

In der Kachel des aktiven Connectors findest du den Sync-Verlauf (letzte 5 Jobs mit Status und Statistik).

Der Platform Admin kann detaillierte Logs über Einstellungen → Dienste → Datenquellen → Logs einsehen — inklusive Live-Tail und Download.

Was passiert beim Löschen einer Entität?

Wenn eine Person oder Abteilung in EntraID gelöscht wird (Delta-Sync: @removed), erstellt ra-connect einen DELETE-Draft. Nach Freigabe löscht roleALPHA automatisch:

• Die Entität selbst (Person / Organigramm-Eintrag)
• Alle Beziehungen, in denen sie vorkommt (z.B. EXECUTES, MEMBER_OF)
• Sichtbarkeits-Grants für die Entität
• Offene Drafts der Entität
• @-Mentions auf die Entität

Der Orphan Reaper (täglich automatisch) räumt etwaige Überbleibsel auf, falls ein Sync-Job unterbrochen wird.

Connector entfernen

Über Entfernen wird die Master-Bindung aufgehoben. Bestehende Entitäten bleiben erhalten und sind wieder manuell bearbeitbar. Das JSON-Schema-Lock wird aufgehoben.

Fehlerbehebung

Problem	Lösung
Connector automatisch deaktiviert	3 aufeinanderfolgende Fehler → Zugangsdaten prüfen, dann reaktivieren
CONNECTOR_MANAGED_ENTITY beim Bearbeiten	Entität wird durch Connector verwaltet — Änderungen direkt im Quellsystem vornehmen
Kein Badge auf Entitäten	Erster Sync noch nicht abgeschlossen oder Drafts noch nicht freigegeben
Auto-Freigabe schlägt fehl (im Log)	Freigabe-Modus ist restriktiver als liberal — Option deaktivieren oder Freigabe-Modus prüfen
Drafts erscheinen trotz Auto-Freigabe	Freigabe-Modus blockiert → Drafts manuell in der Drafts-Übersicht freigeben