Data Sources & Connectors

Data Sources connect external HR and directory systems as master sources to roleALPHA. Once a connector claims a target module, its entities are synchronized automatically — creating, editing and deleting these entities is locked for everyone, as the external system has sole data ownership. The lock applies to manual editing in the UI, to administrators and to the AI assistant rAlph (it cannot create drafts on synced entities). Only the sync system itself keeps writing.

What changes with a connector?

Property	Without connector	With connector
Create entities	Manually / via rAlph	External system only (🔒 manual + rAlph locked)
Edit entities	Manually / via rAlph	Locked (🔒 external system)
Delete entities	Manually	Locked (🔒 source system only)
JSON schema	Freely configurable	Determined by connector
Sync source	—	External service (e.g. Entra ID)
Sign-in address	Maintained explicitly only	Follows the person record automatically (🔒 manual editing locked)

Entities synchronized via connector show a cloud badge with the external system’s name in the list view.

The sign-in address follows. If a data source syncs people, it also owns the sign-in address (Manage sign-in in user management): the field is locked there, and after every sync the address is taken from the person record. Without that, an address change in the source system would mean a permanent lockout — the lock prevents the repair too. Remove the data source and the field is editable again straight away; the last address taken over stays.

One data source per target module: Each target module (People, Organigramm, Cost centers, …) may be served by at most one data source. Once, say, Entra ID syncs People, SuccessFactors (or SAP FI) cannot additionally be set up for People — that target is disabled in the setup dialog and saving is rejected with a notice. To switch the master, first remove the existing data source or adjust its targets. This guarantees two systems never compete over the same entities.

Setting up Microsoft Entra ID

Entra ID (formerly Azure Active Directory) syncs employees as Persons and groups as Organigramm entries.

Prerequisites

1. Create an App Registration in Azure Portal
2. Grant User.Read.All (Application) + GroupMember.Read.All permissions and provide admin consent
3. Create a client secret

How Entra ID recognizes and maps entities

On the first sync, ra-connect stores the AAD Object ID as _syncId in each entity’s descJsonb data. On every subsequent sync, ra-connect loads all existing roleALPHA entities with _syncSource = "EntraID" and builds a map AAD-ID → roleALPHA-UUID — identical to the CSV importer pattern. For each record, ra-connect then decides:

Condition	Action
AAD ID not known in roleALPHA	CREATE draft with new UUID
AAD ID already exists	UPDATE draft with known UUID
@removed in delta + known	DELETE draft → cascades all relationships
@removed + not known	Skipped (already deleted)

On full syncs, entities that exist in roleALPHA but are no longer in Entra ID are also deleted.

No separate mapping table: The mapping comes directly from descJsonb._syncId in the entity data — no additional storage, no synchronisation problem.

Steps

1. Navigate to Settings → Data & Structure → Data Sources
2. Click Connect next to Microsoft Entra ID
3. Fill in the setup dialog:
   • Step 1 – Credentials: Enter Directory ID (Tenant), Application ID (Client), and Client Secret
   • Step 2 – Sync Targets: Select People and/or Organigramm
   • Step 3 – Options: Configure sync interval, conflict strategy, and auto-approval
4. Save — the first sync starts automatically

Sync behavior

• First sync: All users and groups are imported as drafts.
• Subsequent syncs (delta): Only changes since the last sync are transferred.
• Fields: Default mapping imports name, email, title, department, phone, and office location.

Setting up SAP SuccessFactors

SAP SuccessFactors (Employee Central) syncs employees as Persons, departments (FODepartment) as Organigramm entries, and the managerId as a manager relationship (EXECUTES) between persons.

Prerequisites

1. The OData API v2 must be enabled in your SuccessFactors instance
2. An API user with read access to the User and FODepartment entities
3. The API server URL for your data center (e.g. https://api4.successfactors.com) and the Company ID

Authentication

The connector supports two methods — selectable in the setup dialog:

Method	Fields	When to use
Basic	API username + password	Quick start; SuccessFactors internally combines to user@CompanyID
OAuth2 (SAML assertion)	OAuth client ID (API key), OAuth user ID, private key (PEM)	Recommended for production; the connector automatically fetches a signed SAML assertion from the SF IdP and exchanges it for an access token

Password and private key are stored encrypted (AES-256-GCM) and are never returned to the UI in plaintext.

How SuccessFactors recognizes and maps entities

As with Entra ID, ra-connect stores the external ID as _syncId in the descJsonb data — the userId for persons and the externalCode for departments. The _syncSource is set to SuccessFactors. Before each sync, a map external ID → roleALPHA-UUID is built from this:

Condition	Action
ID not known in roleALPHA	CREATE draft with new UUID
ID already exists	UPDATE draft with known UUID
status = inactive/terminated + known	DELETE draft → cascades all relationships
Full sync: in roleALPHA but no longer in SuccessFactors	DELETE draft

Steps

1. Navigate to Settings → Data & Structure → Data Sources
2. Click Connect next to SAP SuccessFactors
3. Fill in the setup dialog:
   • Step 1 – Credentials: API server URL, Company ID, authentication method, and the corresponding fields
   • Step 2 – Sync Targets: Select People, Organigramm and/or Capacity & absences
   • Step 3 – Options: Configure sync interval, conflict strategy, and auto-approval
4. Save — the first sync starts automatically

Sync behavior

• First sync (full): All active employees and departments are imported as drafts, then manager relationships are created.
• Subsequent syncs (delta): Only records with a changed lastModifiedDateTime since the last sync are transferred.
• Fields: Default mapping imports name, email, title, department, division, phone, and office location — plus, when demand planning is active, weekly hours, employment rate and employment type.

Capacity & absences as a sync target

This is the one target that masters no entities: it delivers period-specific working time and absence periods to resource planning. Demands can therefore still be created and edited normally — nothing gets locked.

The absence type (leave, sickness, …) is discarded on import; roleALPHA has no field for it. What that means, and which rules apply to the nightly run, is described in Capacity from an HR system.

Setting up LDAP / Active Directory

Connects a classic Active Directory or an LDAP directory service (e.g. OpenLDAP): users are synced as Persons, groups as Organigramm entries, and the manager attribute as a manager relationship (EXECUTES).

Prerequisites

1. A service account (bind DN) with read access to the directory tree
2. The server URL — ldap://host:389 (plaintext) or ldaps://host:636 (TLS, recommended)
3. The search base (base DN) under which users and groups live (e.g. dc=company,dc=com)

Connection & filters

Field	Description	Default
Server URL	ldap:// or ldaps:// incl. port	—
Bind DN	Service account, e.g. cn=svc-readonly,ou=Service,dc=company,dc=com	—
Bind password	Service account password (stored encrypted)	—
Search base	Base DN for the search	—
User filter	LDAP filter for persons	(&(objectCategory=person)(objectClass=user))
Group filter	LDAP filter for groups	(objectClass=group)

For OpenLDAP instead of AD, adjust the filters, e.g. users (objectClass=inetOrgPerson) and groups (objectClass=groupOfNames).

For ldaps:// with a self-signed certificate, certificate verification can optionally be disabled (checkbox in the dialog).

How LDAP recognizes and maps entities

As the stable external ID, ra-connect uses objectGUID (Active Directory, binary → GUID string) or entryUUID (OpenLDAP), falling back to the DN. It is stored as _syncId with _syncSource = "LDAP" in the descJsonb data. Before each sync, a map objectGUID → roleALPHA-UUID is built from this:

Condition	Action
ID not known in roleALPHA	CREATE draft with new UUID
ID already exists	UPDATE draft with known UUID
Full sync: in roleALPHA but no longer in the directory	DELETE draft → cascades all relationships

The manager relationship comes from the manager attribute (a DN pointing to another user) — resolved to EXECUTES relationships within a sync run.

Steps

1. Navigate to Settings → Data & Structure → Data Sources
2. Click Connect next to LDAP / Active Directory
3. Fill in the setup dialog:
   • Step 1 – Credentials: Server URL, bind DN, bind password, search base, and optional filters
   • Step 2 – Sync Targets: Select People and/or Organigramm
   • Step 3 – Options: Configure sync interval, conflict strategy, and auto-approval
4. Save — the first sync starts automatically

Sync behavior

• First sync (full): All matching users and groups are imported as drafts, then manager relationships are created.
• Subsequent syncs (delta): Only entries with a changed whenChanged (Active Directory; OpenLDAP: modifyTimestamp) since the last sync.
• Fields: Default mapping imports name, email, title, department, phone, and office location.

Setting up SAP FI

SAP FI connects Financial Accounting/CO from SAP S/4HANA and primarily syncs cost centers. Optionally, people (business partners) and org units (cost center standard hierarchy) can be imported too. The connection uses the OData v2 standard APIs (e.g. API_COSTCENTER_SRV, API_BUSINESS_PARTNER).

Prerequisites

1. Reachable OData v2 endpoints of the S/4HANA instance
2. An API user with read access to cost center master data
3. The OData server URL and the company code

How SAP FI recognizes and maps cost centers

The external cost center number (CostCenter) is stored as _syncId with _syncSource = "SAP-FI" in the descJsonb data. Before each sync a map CostCenter → roleALPHA-UUID is built (CREATE when unknown, UPDATE when known, full-sync DELETE for removed records). Because the cost center schema requires the mandatory field costCenterType, the connector sets the default value “Hauptkostenstelle”; further fields (description, company code, responsible, parent hierarchy) also land in descJsonb.

Steps

1. Navigate to Settings → Data & Structure → Data Sources
2. Click Connect next to SAP FI
3. Fill in the setup dialog:
   • Step 1 – Credentials: OData server URL, company code, API username and password
   • Step 2 – Sync Targets: Cost centers (default) and optionally People/Organigramm
   • Step 3 – Options: Configure sync interval, conflict strategy, and auto-approval
4. Save — the first sync starts automatically

Setting up MS Dynamics

MS Dynamics connects Microsoft Dynamics 365 Finance & Operations and primarily syncs cost centers (the “CostCenter” financial dimension). Optionally also workers (Workers) and org units (OMOperatingUnits). The connection uses the OData v4 data entities and authenticates via the Azure AD client-credentials flow.

Prerequisites

1. An app registration in Azure AD with access to the Dynamics environment
2. Directory (tenant) ID, application (client) ID, and a client secret
3. The Dynamics environment URL (e.g. https://contoso.operations.dynamics.com)

How MS Dynamics recognizes and maps cost centers

The CostCenterId is stored as _syncId with _syncSource = "MS-Dynamics". Before each sync a map CostCenterId → roleALPHA-UUID is built (CREATE/UPDATE/DELETE as with SAP FI). Cost centers flagged as deactivated via IsSuspended produce a DELETE draft. Here too the connector sets the mandatory field costCenterType to “Hauptkostenstelle”.

Steps

1. Navigate to Settings → Data & Structure → Data Sources
2. Click Connect next to MS Dynamics
3. Fill in the setup dialog:
   • Step 1 – Credentials: Dynamics environment URL, directory ID, application ID, and client secret
   • Step 2 – Sync Targets: Cost centers (default) and optionally People/Organigramm
   • Step 3 – Options: Configure sync interval, conflict strategy, and auto-approval
4. Save — the first sync starts automatically

Auto-approve sync drafts

By default, imported data lands as drafts in the normal approval flow. With the “Auto-approve sync drafts” option, drafts are approved by ra-connect immediately after import — no manual step required.

Setting	Behavior
Disabled (default)	Drafts appear in the Drafts view for review
Enabled	Drafts are approved immediately after creation — data is visible right away

When to enable?

• The tenant uses liberal approval mode (any tenant user may approve) — only then does ra-connect have the necessary rights
• You fully trust the external system as the master source
• You want no manual review step between import and visibility

When to leave disabled?

• The tenant uses consensus, consent, or highlander mode — auto-approval would be rejected and logged as a warning
• You want to review imported data before publishing (e.g. on the first import)

Note: With auto-approval enabled, the sync log shows “Auto-approve complete: X/Y approved”. Failed individual approvals generate a warning log entry but do not abort the sync.

Required fields apply to syncs too

Since August 2026 the platform enforces the entity type schema’s required fields on publish (see JSON Schema for Entity Types). If the source does not supply a required field, the draft stays put — nothing is lost, but it is not approved.

Worth knowing: such a failure appears only as a warning in the sync log, while the job itself still reports success. If data is missing after a sync, that is the first place to look. The bundled connectors fill the required fields themselves (first and last name for people, organisation type for org units); what typically trips this up are custom field mappings that leave a required field unserved.

Sync history and logs

In the active connector’s tile you’ll find the Sync History (last 5 jobs with status and stats).

The Platform Admin can view detailed logs via Settings → Services → Data Sources → Logs — including live tail and download.

What happens when an entity is deleted?

When a person or department is deleted in Entra ID (delta sync: @removed), ra-connect creates a DELETE draft. After approval, roleALPHA automatically removes:

• The entity itself (person / organigramm entry)
• All relationships involving it (e.g. EXECUTES, MEMBER_OF)
• Visibility grants for the entity
• Open drafts of the entity
• @-mentions referencing the entity

The Orphan Reaper (runs automatically daily) cleans up any remaining orphans if a sync job is interrupted.

Removing a connector

Remove lifts the master binding. Existing entities are retained and become manually editable again. The JSON schema lock is lifted.

Troubleshooting

Issue	Solution
Connector auto-disabled	3 consecutive failures → check credentials, then re-enable
CONNECTOR_MANAGED_ENTITY when editing	Entity is managed by connector — make changes directly in the source system
No badge on entities	First sync not yet complete or drafts not yet approved
Auto-approval fails (in logs)	Approval mode is more restrictive than liberal — disable the option or check approval mode
Drafts appear despite auto-approval	Approval mode blocks it → approve drafts manually in the Drafts overview