Syncing Connectors to User Profiles¶

This guide walks through configuring a connector to synchronize external records (such as users from an identity provider) into Floh, match them to existing user accounts, and keep profile data up to date.

For API-level details and database schema, see Connector Resource Sync.

Prerequisites¶

A connector with sync-capable commands (e.g. the Authifi or Google Workspace connector, which declare listUsers and listGroups). The Sync tab only appears on connectors that have at least one sync-capable command.
The connector:manage permission to configure and trigger syncs.
The connector must be working — test it from the connector detail page before configuring sync.

Quick start¶

Open the connector detail page and select the Sync tab.
Choose a resource type tab (e.g. Users).
Set the User match strategy and enable any User lifecycle options.
Click Save configuration, then Sync now.
Review the results under Synced resources and Match reconciliation review.

The sections below explain each configuration option in detail.

Sync configuration¶

Enabled¶

Turns scheduled sync on or off. When enabled together with a cron schedule, Floh registers a recurring background job that runs the sync automatically. When disabled, you can still trigger syncs manually.

Strategy¶

Strategy	Behavior
Full	Fetches all records from the upstream system. Records not seen during the pass are marked stale. Best for reference data that should always reflect the upstream truth.
Incremental	Fetches only records modified since the last successful sync. Does not mark missing records as stale — absence does not imply deletion. Best for large directories where full enumeration is expensive.

Cron schedule¶

A standard cron expression that controls how often the sync runs. Leave blank for manual-only sync.

Examples:

Expression	Schedule
`0 2 * * *`	Daily at 2 AM
`0 /6 * *`	Every 6 hours
`/30 * * *`	Every 30 minutes

All cron schedules run in UTC.

Stale retention¶

How long stale records are kept before being permanently deleted. Stale records are those that were not seen during the most recent full sync — they may have been removed upstream, or may be temporarily absent due to an API issue.

Format: a number followed by d (days), h (hours), or m (minutes). Default: 7d.

Examples: 7d, 24h, 30m

Keeping a retention window protects against transient upstream issues. If a group temporarily disappears from an API response, it won't be immediately deleted from Floh.

User match strategy¶

The match strategy controls how Floh links synced connector resources to existing user accounts. After each sync, Floh compares each resource against the user directory to find the corresponding Floh user.

Available strategies¶

Strategy	How it matches	When to use
Email	Compares the resource's email address against each Floh user's email (case-insensitive).	Default. Works well when email addresses are unique and consistent between systems.
Email + Issuer	Compares both the email and the identity issuer from the resource against the Floh user's email and `upstream_issuer`.	When users from multiple identity providers (e.g. NIH, Google, Azure AD) may share the same email address. The issuer disambiguates them.
Upstream identity	Compares the resource's `externalId` against the Floh user's `upstream_id`.	When the upstream system ID has been stored on the Floh user record during OIDC login.
External ID	Compares the resource's `externalId` against the Floh user's `sub` claim.	When the upstream system ID matches the OIDC subject claim.

Issuer source path (Email + Issuer only)¶

When using the Email + Issuer strategy, you must tell Floh where to find the issuer value on the synced resource. This is a dot-path into the resource's attributes.

Default: attributes.identityIssuer

For Authifi connectors, each synced user has an identityIssuer attribute that contains the URL of the identity provider that originally authenticated them (e.g. https://auth.nih.gov/affwebservices/public/wsfeddispatcher). This value is compared against the Floh user's upstream_issuer field.

If your connector stores the issuer under a different attribute name, change this path accordingly (e.g. attributes.idpUrl, attributes.issuer).

Match outcomes¶

Outcome	Meaning
Matched (exact)	A single user was found using the primary strategy.
Matched (probable)	A single user was found using a fallback strategy.
Ambiguous	Multiple users matched the same key. Requires manual resolution.
Unmatched	No user was found after trying all strategies.
Skipped	The match was manually marked as skipped or overridden by an operator.

Fallback strategies¶

The API supports a userMatchFallbackStrategies field — an ordered list of additional strategies tried when the primary yields no result. This is not yet exposed in the UI but can be set via the API.

User lifecycle¶

Create users¶

When enabled, Floh automatically creates user accounts for synced records that do not match an existing user. Each auto-created user:

Is created as unconfirmed (they will be linked to a real identity on their first login).
Receives the resource's email and display name.
Has upstream_issuer and upstream_id populated from the resource attributes (so future compound matching works correctly).
Gets any create user defaults applied to their profile (configurable via the API's createUserDefaults field).

Records without an email address are skipped.

Deactivate users¶

When enabled, Floh can soft-delete users whose matched connector resource has gone stale (i.e., it was no longer seen during a full sync). This only applies when:

The user is matched through this connector and resource type.
The user has no other active (non-stale) match on any other connector.

This prevents accidental deactivation of users who appear in multiple sync sources.

Attribute mappings¶

Attribute mappings copy values from synced resources into Floh user profiles. Each mapping rule specifies:

Field	Description
Source path	Dot-path into the resource (e.g. `attributes.department`, `displayName`, `email`).
Target field	The profile field to write to. Options include standard fields (`title`, `department`, `location`, `costCenter`, `startDate`) and any custom profile attributes defined in your profile schema.
Write mode	Controls how existing profile values are handled.
Enabled	Toggle individual rules on/off without deleting them.

Write modes¶

Mode	Behavior
Overwrite always	Always writes the source value, replacing any existing profile value.
Overwrite if empty	Only writes when the current profile value is empty (null, undefined, or blank). Useful for seeding profiles without overwriting manual edits.
Never overwrite	Never writes. Useful for keeping a mapping rule defined but dormant.

Mappings run after user matching, so only resources linked to a Floh user (via matching or manual resolution) have their attributes applied. The profile's attributeSources map tracks which fields were last updated by a connector vs. manually or via OIDC.

Post-sync workflows¶

You can trigger a workflow after each sync completes. This is useful for actions like sending notifications, starting onboarding processes, or running provisioning steps for newly synced users.

Configuration¶

Select a published workflow from the Workflow dropdown.
Choose a Trigger mode:

Mode	Behavior
None	No workflow runs after sync.
Per changed record	Starts one workflow run per added or updated resource. Each run receives the changed records in its variables.
Summary	Starts a single workflow run that receives aggregate sync statistics.

Workflow variables¶

The triggered workflow receives these variables:

Variable	Description
`connectorId`	The connector that was synced.
`resourceType`	The resource type (e.g. `user`).
`workflowId`	The workflow definition ID.
`triggerMode`	The configured trigger mode.
`records`	Changed record details (per-record mode).
`stats`	Aggregate statistics (summary mode).

Reviewing matches¶

After a sync, navigate to the Match reconciliation review section at the bottom of the Sync tab. This shows how each synced resource was matched to a Floh user.

Filtering¶

Use the status dropdown to filter by match outcome: All, Matched, Unmatched, Ambiguous, Skipped, or Manual override.

Resolving matches¶

For unmatched or ambiguous records, you can:

Action	Description
Link	Manually link the resource to a specific Floh user by entering their user ID.
Skip	Mark the record as intentionally skipped. It will not be rematched in future syncs.
Create user	Create a new Floh user from the resource's email and link them.
Unlink	Remove an existing link so the resource can be rematched.

Manually resolved matches (Link, Skip) are preserved across future sync runs — the matcher will not overwrite them.

Bulk operations¶

Select multiple rows and use the Bulk skip action to skip several unmatched records at once.

Synced resources¶

The Synced resources table shows all records from the upstream system that are stored in the local cache. Each row displays:

Display name and Email from the upstream system.
External ID — the identifier in the upstream system.
Synced at — when the record was last confirmed during a sync.
Stale — whether the record was missing from the most recent full sync.

Use the search box to filter by display name, email, or external ID.

Example: syncing Authifi users with Email + Issuer matching¶

This example configures an Authifi connector to sync users and match them using both email and identity issuer.

Scenario¶

Your Authifi tenant has users from multiple identity providers (NIH, Google, Azure AD). Some users share the same email address across different IdPs. You want Floh to correctly distinguish them.

Steps¶

Open the connector — Navigate to the Authifi connector's detail page and select the Sync tab.
Select the Users tab — The Authifi connector declares listUsers as sync-capable, so a Users tab appears.
Configure matching:
Set User match strategy to Email + Issuer.
The Issuer source path defaults to attributes.identityIssuer, which is correct for Authifi. Each Authifi user record includes an identityIssuer attribute containing the IdP URL.
Enable user creation (optional):
Toggle Create users on if you want Floh to automatically create accounts for users that don't already exist.
Auto-created users will have their upstream_issuer set from the Authifi identityIssuer attribute, so future syncs will match them correctly.
Configure attribute mappings (optional):
Add mappings to copy Authifi user attributes into Floh profiles. For example:
- Source: attributes.department → Target: department (Overwrite if empty)
- Source: attributes.title → Target: title (Overwrite always)
Set a schedule:
Enter a cron expression like 0 */6 * * * (every 6 hours).
Toggle Enabled on.
Save and sync:
Click Save configuration.
Click Sync now to run the first sync immediately.
Review results:
Check the Sync status card for success/error and statistics.
Review the Match reconciliation review section for any ambiguous or unmatched records.
Resolve any ambiguous matches manually by linking them to the correct Floh user.

How compound matching works¶

When a resource is synced from Authifi:

Resource: email=keats@nih.gov, attributes.identityIssuer=https://auth.nih.gov/...
                                        ↓
Compound key: keats@nih.gov|https://auth.nih.gov/...
                                        ↓
Query Floh users: WHERE lower(email) = 'keats@nih.gov'
                  AND upstream_issuer = 'https://auth.nih.gov/...'
                                        ↓
                               Unique match? → Link
                               No match? → Unmatched (create if enabled)
                               Multiple? → Ambiguous (manual resolution)

This ensures that keats@nih.gov authenticated through NIH is treated as a different user than keats@nih.gov authenticated through Google.

Permissions reference¶

Action	Required permission
View sync config and resources	`connector:read`
Configure sync, trigger, resolve matches	`connector:manage`

Troubleshooting¶

"No sync resource types are declared for this connector type"¶

The Sync tab shows this message when the connector's schema does not include any sync-capable commands. Check that the connector type declares commands like listUsers or listGroups with syncCapable: true.

Sync completes but no resources appear¶

Check that the connector test succeeds (the connector must be able to authenticate and fetch data).
Verify filter rules aren't excluding all records (check emailDomains, maxRecords, etc. via the API).
If using incremental strategy, the first sync may need to be full to populate the initial cache.

Many "unmatched" records after sync¶

Check that the match strategy is appropriate. If users haven't logged in through OIDC yet, they may not have upstream_id or upstream_issuer set — use email matching instead.
Enable Create users to auto-create accounts for unmatched records.

Ambiguous matches¶

Multiple Floh users match the same resource key. This happens when:

Two users share the same email address (use Email + Issuer to disambiguate).
Duplicate user records exist in Floh.

Resolve ambiguous matches manually from the Match reconciliation review panel.

Auto-created users don't match on next sync¶

If using Email + Issuer strategy, ensure that the issuerSourcePath is correctly configured. Auto-created users receive upstream_issuer and upstream_id from the resource attributes, so the same path used for matching is used for populating the user record.