[$250] Onboarding - User starts the onboarding from the beginning after redirected from OD

[nlemma]

If you haven’t already, check out our contributing guidelines for onboarding and email contributors@expensify.com to request to join our Slack channel!

---

Version Number: v9.1.63-0
Reproducible in staging?: Yes
Reproducible in production?: Yes
If this was caught during regression testing, add the test name, ID and link from TestRail: #63330
Email or phone of affected tester (no customers): N/A
Issue reported by: Applause Internal Team
Device used: Windows 10 / Chrome, Samsung Galaxy A12 / Android 13
App Component: Other

Action Performed:

1. Go to staging oldDot, staging.expensify.com
2. Select signup option "Control expense for...", enter a new email. Click "Get Started"

Expected Result:

User should be redirected to NewDot, and presented with the company size selection onboarding.

Actual Result:

User is redirected to NewDot, but is not immediately presented with the company size selection onboarding.

Workaround:

Unknown

Platforms:

• Android: App
• Android: mWeb Chrome
• iOS: App
• iOS: mWeb Safari
• iOS: mWeb Chrome
• Windows: Chrome
• MacOS: Chrome / Safari
• MacOS: Desktop

Screenshots/Videos

bandicam.2025-06-10.00-42-14-388.mp4

View all open jobs on GitHub

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~021932369240424300617
• Upwork Job ID: 1932369240424300617
• Last Price Increase: 2025-06-24
• Automatic offers:
• QichenZhu | Reviewer | 107801560
• linhvovan29546 | Contributor | 107801561

Issue Owner

Current Issue Owner: @robertjchen

[melvin-bot]

Triggered auto assignment to @laurenreidexpensify (Bug), see https://stackoverflow.com/c/expensify/questions/14418 for more details. Please add this bug to a GH project, as outlined in the SO.

[melvin-bot]

Job added to Upwork: https://www.upwork.com/jobs/~021932369240424300617

[melvin-bot]

Triggered auto assignment to Contributor-plus team member for initial proposal review - @QichenZhu (External)

[Nick4dawin]

Proposal

Please re-state the problem that we are trying to solve in this issue.

When users go to staging.expensify.com, select "Control expense for...", enter a new email, and click "Get Started", they are redirected to NewDot but are not immediately presented with the company size selection onboarding. Instead, users get stuck without proper onboarding flow starting.

Expected Behavior: User should be redirected to NewDot and immediately see the company size selection screen.
Actual Behavior: User is redirected to NewDot but onboarding doesn't start immediately.

What is the root cause of that problem?

The issue is in the hybrid app onboarding flow logic where:

1. Priority Issues: In useOnboardingFlow.ts, the logic for showing explanation modal vs. starting onboarding was not prioritized correctly for new signups. The existing code checked for hybrid app onboarding completion first, which caused new signups to not start the onboarding flow immediately.

2. Missing Signup Qualifier: Users coming from OldDot "Control expense for..." signup didn't have a proper signupQualifier set, causing them to fall through to the default onboarding root instead of being directed to the appropriate business onboarding screen.

3. State Timing: The onboarding flow check wasn't properly handling the case where users are new signups from OldDot vs. existing users transitioning between platforms.

What changes do you think we should make in order to solve the problem?

1. Fix Hybrid App Onboarding Flow Priority Logic in App/src/hooks/useOnboardingFlow.ts:

// Priority 1: New signups from OldDot should immediately start onboarding flow
if (isOnboardingCompleted === false && !startedOnboardingFlowRef.current) {
    startedOnboardingFlowRef.current = true;
    startOnboardingFlow({
        onboardingValuesParam: onboardingValues,
        isUserFromPublicDomain: !!account?.isFromPublicDomain,
        hasAccessiblePolicies: !!account?.hasAccessibleDomainPolicies,
    });
    return;
}

// Priority 2: Existing users transitioning from OldDot to NewDot should see the explanation modal
if (isHybridAppOnboardingCompleted === false && isOnboardingCompleted === true) {
    Navigation.navigate(ROUTES.EXPLANATION_MODAL_ROOT);
    return;
}

2. Enhanced Onboarding Path Logic in App/src/libs/actions/Welcome/OnboardingFlow.ts:

// For users coming from OldDot business signup without a signupQualifier, default to SMB
const hasNoSignupQualifier = !isVsb && !isSmb && !isIndividual;
const shouldDefaultToSmb = hasNoSignupQualifier && !isUserFromPublicDomain;

if (isSmb || shouldDefaultToSmb) {
    Onyx.set(ONYXKEYS.ONBOARDING_PURPOSE_SELECTED, CONST.ONBOARDING_CHOICES.MANAGE_TEAM);
    // Set SMB qualifier for users who should default to SMB but don't have it set
    if (shouldDefaultToSmb) {
        Onyx.set(ONYXKEYS.NVP_ONBOARDING, {
            ...currentOnboardingValues,
            signupQualifier: CONST.ONBOARDING_SIGNUP_QUALIFIERS.SMB,
        });
    }
}

// SMB users (including defaulted ones) go to company size selection
if (isSmb || shouldDefaultToSmb) {
    return `/${ROUTES.ONBOARDING_EMPLOYEES.route}`;
}

What specific scenarios should we cover in automated tests to prevent reintroducing this issue in the future?

1. Test that unqualified business users (no signupQualifier) from OldDot are defaulted to SMB and directed to company size selection
2. Test that new signups (isOnboardingCompleted === false) are prioritized over existing user transitions in hybrid app flow
3. Test that existing users transitioning from OldDot still see the explanation modal when appropriate
4. Test that VSB, SMB, and Individual users continue to be directed to their correct onboarding screens
5. Test that public domain users and users with accessible policies follow their existing flows

What alternative solutions did you explore? (Optional)

1. Filter Out Unqualified Users: We could have filtered out users without signupQualifiers entirely, but this would prevent legitimate business signups from completing onboarding.

2. Default to Individual Instead of SMB: We could have defaulted unqualified users to individual signup, but business users from "Control expense for..." flow are clearly indicating business intent.

3. Add New Signup Parameter: We could have added a new parameter to track OldDot business signups specifically, but this would require changes to both OldDot and NewDot and increase complexity.

4. Delay Onboarding Start: We could have added a delay before starting onboarding to ensure all state is loaded, but this would worsen user experience and not address the root cause.

The chosen solution is the most targeted approach that fixes the priority logic issue while maintaining backward compatibility and properly handling the unqualified business user case.

[QichenZhu]

@laurenreidexpensify, should we skip the work email form, the purpose selector, or both?

[laurenreidexpensify]

@danielrvidal @trjExpensify can you advise ^^

[trjExpensify]

Following this one, using the exact conditions of the video in the OP.

• Signs-up on expensify.com using a gmail account (with a + operator in the email).
• Choose the "Manage my team" 10+ signUpQualifier option on expensify.com
• Gets redirected to NewDot on clicking "Get started"
• We ask for their WorkEmail in the onboarding modal, as we do all public domain sign-ups.
• They skip that, and we proceed to ask what their purpose is despite telling us already by the virtue of completing step (2) above.
• If they choose "manage my team" again, the employee count step is shown and correctly hides the 1-10 option becomes of the action in step (2) above to tell us that already.

2025-06-17_15-40-29.mp4

IMO, we should skip the purpose step in this flow as we have that from the signUpQualifier selection that happened earlier, making it redundant to ask again. Prompting a public domain sign-up for the WorkEmail as the first step is fine. Curious for @danielrvidal take as well. 👍