After this article
- You will understand what Source of Truth means in Lumos and how the User Source priority system works
- You will know how to safely switch from one identity source to another (e.g., from an IDP like Okta or Entra ID to an HRIS like Workday or UKG, and vice versa)
- You will know how to verify the switch was successful and how to avoid common pitfalls like duplicate identities
Overview
In Lumos, your Source of Truth (SoT) is the integration that Lumos treats as the authoritative source for user identity data. It determines which system “owns” each user record, which controls what name, email, manager, team, title, and other attributes appear on the identity in Lumos. Lumos supports multiple User Sources, ranked by priority. The highest-priority source claims ownership of each user record and its core attributes. Lower-priority sources can supplement data (e.g., manager from Workday, team from Okta) but cannot overwrite data owned by a higher-priority source.Common Source of Truth systems
Why you might switch your SoT
- Your organization adopted a new HRIS and wants it to be the master employee record
- You’re replacing your IDP and want identities to continue resolving correctly
- You want employee lifecycle events (new hires, terminations, role changes) driven by your HRIS rather than your IDP
Before You Switch (Pre-Switch Checklist)
Switching your Source of Truth affects every user in Lumos on the next sync. Skipping preparation can result in duplicate identities or incorrect attribute data, so complete these steps before making any changes.1. Confirm both integrations are connected
The new SoT must already be connected as an integration in Lumos before you can set it as a User Source. Navigate to Settings → Integrations and confirm the new source is actively syncing.2. Verify email alignment between systems
Lumos matches user identities across sources by email address. If users have different email addresses in your current SoT versus your new SoT, Lumos will create duplicate identities instead of recognizing them as the same person. Before switching:- Export a sample of user emails from both systems and compare them
- Ensure the email format is consistent (e.g.,
first.last@company.comin both) - If emails differ, work with your IT team to align them before proceeding
jane.doe@company.com, but Workday has jdoe@company.com. Without alignment, the switch will create a second identity for Jane Doe in Lumos.
3. Review your attribute source configuration
When you change your top-priority source, the new source becomes the owner of matched user records, and its core user attributes (name, email, manager, team, title) overwrite the existing values on the next sync, except any attribute that has its own attribute source configured. Check that your new SoT has accurate data for:- Legal name
- Work email
- Manager hierarchy
- Department / team
- Job title
- Employee start/end dates (if applicable)
4. Note your current User Source configuration
In Settings → Source of Truth, note the current order of your User Sources so you can reference it if you need to roll back. If you restore the previous order, the old source takes back the users it has on its next sync and overwrites their attributes with its values. Lumos doesn’t keep a copy of the earlier values, so users who exist only in the new source, and any title, team, or manager the old source leaves blank, keep the new source’s values.How to Switch Your Source of Truth
Step 1: Navigate to Source of Truth settings
Go to Settings → Source of Truth in the Lumos admin portal. To change these settings, you need the Admin role, or a custom role with the Source Of Truth permission under Org Settings set to both View and Manage. A Read Only Admin can view them but not change them.Step 2: Edit your User Sources
In the User Sources section, click Edit. You will see a prioritized list of your current sources. Priority 1 is your current Source of Truth.Step 3: Update the priority order
To promote a new source to top priority:- If the new source is already in the list, drag it to position 1 (the top)
- If the new source is not yet in the list, click Add Source, select it from the dropdown, then drag it to position 1
- You can have multiple sources in the list. Lower-priority sources act as fallbacks for any data not found in higher-priority sources
Step 4: Save and sync
Click Save. Lumos starts a sync of your User Sources in the new priority order. If a banner about un-synced changes appears, click Sync, then Sync All User Sources. You can also manually trigger a re-sync by clicking Sync on the Source of Truth settings page if needed.Step 5: What happens during the sync
When the sync runs with your updated priority order:- Lumos processes your highest-priority source first
- Each user record found in that source is matched against existing identities by email address
- Lumos updates matched identities: it sets that source as the owner of the record and overwrites core attributes from it
- Users found in lower-priority sources are synced next; if they were already claimed by the top source, lower sources only fill in unconfigured attributes
- Users not found in the new SoT remain in Lumos with their existing data until resolved
Configuring Attribute Sources
You can configure Lumos to pull individual attributes from different sources, independent of the overall User Source priority. In Settings → Source of Truth, you can configure per-attribute sources for:- Manager — e.g., pull manager hierarchy from Workday even if Okta is the top-level SoT
- Team / Department — e.g., pull department from BambooHR
- Title — e.g., pull job title from your HRIS
- Custom attributes — any custom schema field can be mapped to a specific source
Post-Switch Verification
After the sync completes, verify the following:Check identity counts
- Navigate to People (or Users) in Lumos
- Confirm the total number of active users matches your expected headcount
- Look for unexpected spikes in user count, which may indicate duplicate identities were created
Spot-check user records
- Search for several known users and confirm their name, email, manager, team, and title are correct
- Check a recently onboarded employee and a recently offboarded employee to validate lifecycle data is coming through correctly
Check for duplicate identities
If you see the same person appearing twice:- This typically means their email address differs between the old and new SoT
- Contact Lumos Support to merge or resolve duplicate identities. Do not manually delete identities, as this may affect Access Review history and other audit records
Troubleshooting
Users are missing after the switch
If users that exist in your new SoT are not appearing in Lumos:- Confirm the integration is actively syncing (Settings → Integrations)
- Verify those users are included in the sync scope (some integrations support filtering by group or attribute)
- Trigger a manual sync from the Source of Truth settings page
User attributes are not updating
If attributes like manager or title are not reflecting the new source:- Check whether those attributes have a separate attribute source configured. An individual attribute source overrides the top-level User Source priority for that specific field
- Trigger a manual sync after saving your configuration changes