Client onboarding from zero#

This is the complete journey for a brand-new workspace: you log in for the first time, the guided setup wizard walks you through 12 short steps, and you finish with a CRM that is connected to your Facebook Page and has proven it can catch a real lead.

Nothing here is technical. If you can use Facebook and WhatsApp, you can do this yourself.

Who this is for#

• Business owners doing their own setup (no technical knowledge needed).
• Workspace admins setting the CRM up on behalf of the business.
• Anyone re-checking what a skipped step means.

Difficulty: Easy · Time: 30–45 minutes · Prerequisites:

• Your login email and password (sent to you when your workspace was created).
• A Facebook account that can already manage the Facebook Page you advertise with, and access to the ad account that runs your campaigns.
• Email addresses of the team members you want to invite (optional — you can add them later).

The journey at a glance#

flowchart TD
    A[First login] --> B["Set up your workspace wizard"]
    B --> C["1 · Business details"]
    C --> D["2 · What type of business"]
    D --> E["3 · Connect Meta (Facebook)"]
    E --> F["4 · Choose Page & Ad Account"]
    F --> G["5 · Lead forms & mapping"]
    G --> H["6 · Sales process"]
    H --> I["7 · Lead assignment"]
    I --> J["8 · Follow-up setup"]
    J --> K["9 · Add team members"]
    K --> L["10 · Connect WhatsApp"]
    L --> M["11 · Mobile app"]
    M --> N["12 · Test your setup"]
    N --> O["Setup complete"]
    O --> P["Zodiac Tech team prepares your campaigns"]

Step by step#

1. First login#

1. Open your CRM web address (for this install: http://localhost/Lead%20Hub/, production: https://crm.zodiactechsoft.in) and log in with the email and password you were sent.
2. What happens: your first login as owner/admin lands on Set up your workspace and the 12 steps appear in order.
3. Expected result: the first step, Tell us about your business, is open and the top bar shows a Setup 0% chip (progress grows as steps settle).

2. Work through the steps#

Each step follows the same rhythm: you provide or confirm something real, and the CRM verifies it really happened before marking the step done. You cannot fake progress — which is exactly why the finished setup works.

• Steps 1–2 — who you are: business name, type, city, and your industry. Your industry choice installs a ready-made template (pipeline, stages, custom fields, tags, templates, automations, forms). See Business details.
• Steps 3–5 — connect your lead source: Facebook login (OAuth), Page + Ad Account selection, then tick the lead forms to import and confirm where each answer should land in the CRM. See Connect Meta, Choose your Page & Ad Account, Lead forms & mapping.
• Steps 6–8 — how work flows: sales process (pipeline + stages), assignment of new leads, and the default follow-up automation. See Set up your sales process and Lead assignment & follow-ups.
• Steps 9–11 — your people and channels (all optional): invite the team, connect WhatsApp, install the Android app. Skippable — you can finish these any time later. See Add team members, Connect WhatsApp, Mobile app setup.
• Step 12 — prove it works: Send test lead creates a real lead tagged Test Lead and runs five checks against your setup. See Test your setup.

3. Finish#

1. When every step is settled, the wizard shows Setup complete with a checklist of what you configured — skipped steps are marked "(skipped)".
2. What happens: the Setup chip disappears from the top bar, the CRM stops redirecting you to the wizard, and Zodiac Tech is notified that your workspace is ready. Our team then prepares your campaigns; you do not need to do anything until we tell you they are ready.
3. Expected result: clicking Go to Dashboard takes you to a working CRM with your process, leads area, and team in place. See Finish & go live.

Expected result#

• Your workspace has a business profile, an industry template, a working Meta connection with at least one lead form selected, a pipeline with 2+ stages, an assignment mode, a follow-up automation, and at least one successful test lead.
• The top-bar setup chip is gone and the dashboard is yours.

Common mistakes#

• Half-finishing a step and closing the browser. Not a problem — setup resumes at the first unsettled step. You never lose what you already completed.
• Logging in with the wrong Facebook account. During Meta connect, choose the Facebook account that manages your Page, not your personal one. See Connect Meta.
• Looking for a step that disappeared. If a step shows ✓ but the chip still shows progress, scroll the drawer — later required steps are still open.
• Confusing the two "Connect Meta" entries. The wizard and Settings → Connections → Lead Source Connections do the same thing; use whichever you prefer. They share one connection.
• Expecting skipped steps to count as done for us. Skips keep you moving, but Zodiac Tech's team still sees them marked "(skipped)" on the client onboarding dashboard.

Troubleshooting#

Technical details#

• Wizard: App\Filament\Pages\GuidedSetup at /admin/guided-setup; step UI under resources/views/filament/pages/guided-setup/steps/; top-bar chip + drawer: App\Livewire\GuidedSetupChip, resources/views/filament/guided-setup/chip.blade.php and drawer.blade.php.
• State: business_onboarding + business_onboarding_steps tables, driven by App\Support\OnboardingSteps (frozen 12-step map) and App\Services\GuidedOnboarding\OnboardingStateResolver (real-state conditions). OnboardingService::sync() re-derives every client step in a transaction and audits changes (guided_onboarding.step_status, guided_onboarding.completed).
• Status vocabulary: NOT_STARTED → IN_PROGRESS → COMPLETED, plus SKIPPED (explicit skip) and BLOCKED (Meta needs attention). A skipped step auto-upgrades to COMPLETED once its real condition is met.
• Redirect: App\Http\Middleware\RedirectToOnboarding sends owner/admins to the wizard until completion; members are never redirected.
• For the full life of the state machine see How guided onboarding works.

Related guides#

• Business details · Connect Meta · Choose your Page & Ad Account · Lead forms & mapping
• Set up your sales process · Lead assignment & follow-ups · Add team members
• Connect WhatsApp · Mobile app setup · Test your setup · Finish & go live
• Quick start (15 minutes) · Your first login · How guided onboarding works