Onboarding.

Use an onboarding checklist when a customer must reach a known sequence of milestones. The package derives progress from stored milestone rows, so there is no mutable checklist counter to keep synchronized.

Checklist declarations

A checklist extends Checklist and returns an ordered list of product event classes:

namespace App\CustomerHealth;

use App\CustomerHealth\Events\TeammateInvited;
use App\CustomerHealth\Events\WorkflowCreated;
use ByRcsc\LaravelCustomerHealth\Onboarding\Checklist;

final class Onboarding extends Checklist
{
    public function steps(): array
    {
        return [
            WorkflowCreated::class,
            TeammateInvited::class,
        ];
    }
}

Every step must be a registered event with $milestone = true. Steps must be unique and the checklist cannot be empty.

The default checklist name is the snake-cased class basename. Set a public static $name when stored completion identity must remain stable across a class rename.

Read progress

Register the checklist in customer-health.checklists, then read it by default:

$progress = CustomerHealth::onboarding($team);

$progress->completedSteps();
$progress->totalSteps();
$progress->percent();
$progress->currentStep();
$progress->isComplete();
$progress->stalledSince();

When no name is supplied, the first registered checklist is used. Pass a checklist name or class when the application registers more than one:

$progress = CustomerHealth::onboarding(
    subject: $team,
    checklist: Onboarding::class,
);

currentStep() returns the first incomplete event class in declaration order. Steps can arrive out of order, but the current step still follows the declared sequence.

stalledSince() returns the most recent completed step time while onboarding is partial. It returns null before the first step and after completion.

Completion records

When the final required milestone exists, the package creates another milestone named onboarding:<checklist-name>. A unique index keeps this completion record singular during concurrent event tracking.

The package dispatches OnboardingStepCompleted only when a step milestone is first inserted. It dispatches OnboardingCompleted only when the completion milestone is inserted.

Find stalled onboarding

$subjects = CustomerHealth::stalledInOnboarding(days: 14)->get();

foreach ($subjects as $identity) {
    $subject = $identity->resolve();
}

The result is a collection of MorphIdentity values. A subject is stalled when it has at least one but not every step in a registered checklist and its latest step occurred before the UTC cutoff.

The exact cutoff is active, not stalled. A step recorded exactly 14 days ago is excluded from stalledInOnboarding(14) until it becomes older than the cutoff.

What onboarding does not track

A subject with no completed step is absent from the package's milestone data, so it cannot appear in stalled-onboarding results. Track a starting milestone if the application needs to identify customers that began but made no further progress.

The query returns identities rather than loading application models. This avoids assuming that every subject type lives on the package connection.

What to read next

• Health scores to include onboarding percentage as a weighted signal.
• Events to listen for step and checklist completion.
• Querying customer health to resolve returned subject identities.