Onboarding Wizard | One to One Hundred

The Onboarding Wizard is a core feature of Baseplate designed to simplify, unify, and accelerate the process of setting up a newly created customer. By guiding users through a series of clear, step-by-step screens, the framework ensures that all critical configurations—such as customer settings, branding, and any application-specific parameters—are properly established from the start. This addresses a key business problem: new customers and administrative users often struggle with scattered settings pages, incomplete configurations, or a slow, manual approach to customer setup. By reducing this complexity, the Onboarding Framework helps new customers become productive much faster.

The first user who creates an customer for a specific customer is led through a wizard-like flow. This flow may include steps like confirming company information, defining customer-level preferences, adding core user roles, and specifying essential workflows. By providing validation checks and context-aware suggestions, the framework prevents incomplete or invalid information from slipping through. For instance, if a certain step requires an integration with an external service, the wizard prompts the user for relevant credentials or configuration keys. This design reduces confusion and ensures every customer starts off aligned with best practices.

Beyond initial creation, the Onboarding Framework can be re-run or accessed at any time by users with the appropriate roles—System Administrators, Customer Success, or customer Administrators. This allows for quick reconfiguration if the company changes its branding, modifies subscription tiers, or wants to introduce new team members under specific roles. Instead of digging through multiple settings screens, administrators simply launch the onboarding wizard again to adjust configurations in a structured, user-friendly way. This ability to “reset” or “re-run” also helps with training or re-training new administrators by letting them walk through each step methodically.

The onboarding wizard will be extensively built out for each application and the logic highly application specific. To that end we’re building a basic framework that will be extended and customized by each application built on the Stock SaaS platform framework. By building a modular architecture, the Onboarding Framework serves as a solid foundation that product teams can adapt to their specific domain, ensuring consistency of user experience without sacrificing customization.

Developers looking for inspiration can examine popular SaaS platforms that offer a unified onboarding process, such as Stripe’s “Quick Start” wizard or Shopify’s store setup workflow. These solutions employ guided steps, embedded tooltips, and integrated validation to keep users on track. The key takeaway is that a well-designed onboarding experience reduces user friction, promotes confidence in the software, and leads to higher long-term engagement and customer satisfaction.

Role Access and User Stories

System Administrator

System Administrators can initiate or reset the onboarding process across any customer in the system. They can also do this on behalf of a specific customer or proactively setup a customer for the purposes and support a customer specific demonstration. The wizard’s global settings — for example, enabling or disabling certain steps for all customers — will be handled via Firebase Remote config and do not require a UI for interaction.

Reset customer Onboarding – As a System Administrator, I want to reset the onboarding wizard for a specific customer so that any configuration errors can be corrected through a guided process rather than manual changes scattered across different settings pages.
Force customer Re-Onboarding – As a System Administrator, I want to require a customer to re-complete the onboarding process as new regulatory requirements arise, ensuring that all customers remain compliant.
View Onboarding Progress – As a System Administrator, I want to see how far along each customer is in their onboarding process so that I can proactively provide help or escalate issues as needed.”
Troubleshoot Onboarding Errors – As a System Administrator, I want to access logs for any errors encountered during the onboarding flow so that I can diagnose issues and improve the system’s reliability.
1. Note that this would be aligned with the “View Onboarding Progress” screens pulling all the data for customer specific onboarding into one view

Customer Success

Customer Success representatives use the Onboarding Framework primarily as a support tool. They need to walk new customers through the wizard if they get stuck or have questions about configuration. They may also re-run the wizard on behalf of the customer to adjust settings related to subscription tiers, user role assignments, or other setup details that the customer might not fully understand.

Guide customer Through Setup – As a Customer Success representative, I want to walk a new customer step-by-step through the onboarding wizard so that they can configure their customer seamlessly and start using the platform quickly.
Answer Onboarding Questions – As a Customer Success representative, I want to access the customer’s current onboarding step and see any relevant data so that I can answer questions about required fields or available configuration options.
Re-Run Onboarding for Issue Resolution – As a Customer Success representative, I want to initiate the wizard again if a customer discovers they’ve configured something incorrectly, enabling them to fix errors easily.”
Provide Contextual Tips – As a Customer Success representative, I want to add custom tooltips or help text for a specific customer’s onboarding steps so that unique use cases are addressed without code changes.”
Track Onboarding Completion – As a Customer Success representative, I want to monitor whether the customer has finished all the steps in the wizard so that I know when they are fully set up and ready to use the product.
Receive Alerts for Stalled Onboarding – As a Customer Success representative, I want to be alerted if a customer hasn’t progressed in the wizard for more than a week so that I can proactively reach out and offer assistance.
Record Feedback in Wizard – As a Customer Success representative, I want to capture customer feedback about each onboarding step so that we can refine the framework and reduce common confusion points.
Customize Client-Specific Steps – As a Customer Success representative, I may want to add or remove certain optional steps for a premium client based on their contract terms, ensuring they see only relevant choices.
1. A common example of this would be the “Accept MSA” step. Enterprise customers typically accept an MSA once, centrally and don’t want to prompt users or customer administrators to accept an MSA.

Customer Administrator

customer Administrators are the primary beneficiaries of the Onboarding Framework. They use it to perform the initial setup of their customer’s environment, but they can also re-run the wizard at any time to adjust organizational settings, roles, branding, or feature toggles. Because they have autonomy over their own customer, they need a straightforward, foolproof method for making changes as their organization evolves.

Initial customer Setup – As a customer Administrator, I want to be guided through essential steps like branding, domain settings, and user roles so that my organization is ready for immediate use of the product.
Invite Team Members – As a customer Administrator, I want to invite other team members to use and interact with the application from the onboarding wizard so that I’m not the only one responsible for these configurations.
Review Mandatory Steps – As a customer Administrator, I want to see which steps are mandatory versus optional so I can skip steps that aren’t relevant to my organization’s needs.
Validate External Integrations – As a customer Administrator, I want the wizard to prompt me for API keys or credentials for connected services (e.g., CRM, HRIS) so that these integrations are set up correctly from day one.”
Update customer Branding – As a customer Administrator, I want to quickly revise logos and color schemes supported in the app so that my user’s see an application that “looks” like our standard corporate branding.
Set Notification Preferences – As a customer Administrator, I want to define how users in my customer receive notifications (email, in-app, Slack integration, etc.) during the onboarding flow, making sure they receive critical updates.”
Configure customer-Level Security – As a customer Administrator, I want to define default security settings (e.g., password complexity, or sign-in methods) during the onboarding wizard so that I comply with my organization’s policies.
Re-Test Configuration – As a customer Administrator, I want the system to test or validate new settings right within the wizard so that I can confirm everything is working before finalizing the step.
Simplify Feature Discovery – As a customer Administrator, I want to see brief descriptions or tutorials for advanced features during onboarding so that I don’t miss out on capabilities that could benefit my team.”
Adjust Role-Based Access – As a customer Administrator, I want to re-run the wizard to update role definitions or permissions if the structure of my organization changes, ensuring the platform always reflects our internal hierarchy.”

Manager

Managers typically won’t set up the entire customer, but they may be involved in inviting their direct reports and ensuring they have access to the correct features. They might not frequently use the Onboarding Framework, but they benefit from a partial view that helps them configure team settings or check if certain steps are relevant to their department’s tasks.

Invite Direct Reports – As a Manager, I want to access a quick onboarding step that lets me invite my direct reports immediately, ensuring that the team gets started without having to wait for the customer Administrator.
Set Department Preferences – As a Manager, I want to configure department-specific preferences (e.g., data labeling, reporting frequencies) during an onboarding re-run so that my team’s experience is tailored to our workflows.
Review Notification Settings – As a Manager, I want to ensure that my direct reports receive the correct notifications or alerts set up during onboarding so that no critical updates go unnoticed.

Standard User

Standard Users are provided a vary narrow Onboarding Framework primarily focused on linking relevant customers and building out any system specific data they might need. Ideally this occurs after a customer Administrator and Manager have completed all necessary configurations. In practice, though, if a Standard User is the first to login for a given customer they’ll first need to complete the customer Admistrator and Manager setup before completing their personal setup process.

User Stories

Complete Personal Setup – As a Standard User, I want to be guided through a short setup wizard (if enabled) that includes tasks like updating my profile, configuring notifications and connecting to relevant tools.”
Acknowledge Training Resources – As a Standard User, I want to see a brief overview of the platform’s key features during onboarding so that I can quickly learn how to navigate and use them effectively.”
Add Basic Info – As a Standard User, I want to be able to review my department, role, and project details in an optional onboarding step so that the system can surface personalized content or tasks to me.
License Accept – As a Standard User, I want to accept the system wide MSA so I can access the tool.

Page and Screens

Onboarding Wizard Dialog

This dialog serves as the entry point and framework for the entire onboarding process. It briefly explains what the user is about to do, why it matters, and how many steps are involved. Users with that are re-running the wizard should see a message indicating that prior setting will be pre-populated. Users that are re-entering the wizard at a specific step should be automatically “forwarded” to that step. For new customers, this page automatically appears upon the user’s first login.

A clear, visually simple layout leveraging the Material UI wizard component should displays the status of each step—e.g., completed, in progress, or not started. There will be tooltips attached to each stage explaining each phase. An integrated progress bar helps reduce cognitive load by showing the user how far they’ve come and what remains. If the wizard is re-run for an existing customer, this page might also show a history of prior onboarding sessions for reference.

Error handling and role-based visibility are baked into this screen. For instance, if a Manager tries to launch steps restricted to the customer Administrator, the page will provide an explanation or disable those steps. This ensures that only authorized users can make critical changes, maintaining the integrity and security of the customer’s setup.

Onboarding Screens

These screens are the steps of the onboarding flow. Each screen focuses on a specific configuration category specific to the customer — such as “customer Branding,” “Billing Setup,” “User Invitations,” or “System Integrations.” Some steps are mandatory (e.g., specifying customer name), while others may be optional (like connecting a marketing automation tool). The UI encourages the user to save progress or move back and forth between steps as needed.

Contextual help and validation are crucial. If the user tries to proceed without providing required fields, the wizard highlights the missing or invalid entries. Pop-up help text, embedded videos, or short tutorials can be integrated for complex steps. This approach ensures even novice users can complete sophisticated configurations with minimal help from support teams.

An extensible architecture underpins these screens. Developers can insert custom steps for each application module—e.g., a step for configuring advanced analytics might appear for enterprise clients, but not for basic-tier customers. This design fosters a personalized onboarding experience that flexes according to the user’s subscription level, business needs, and internal policies.

Throughout these screens, any data entered is either saved automatically or when the user clicks “Next.” Error messages should be descriptive but concise, guiding users on how to correct issues. In some cases, the wizard may prompt the user to confirm integration details by making a test call to a third-party API or verifying domain ownership—whatever the use case demands.

Every screen will include a link to a standalone overview page of the onboarding process. This overlay can be accessed during any wizard step, providing on-demand guidance without forcing the user to exit the flow – i.e. it should open in a new window. This page will contain and overview of the onboarding process and any FAQs that may arise from the process.

User Configuration Onboarding Screen

The User Configuration Onboarding Screen is a standard step that allows individual users to personalize and secure their customers by adding secondary emails and linking relevant social or communication platforms. This configuration step typically appears after core customer-level onboarding steps, ensuring that once the customer is set up, each user can tailor their customer to their specific preferences.

By offering the option to attach secondary email addresses, users gain a safety net for customer recovery, critical notifications, or personal workflow conveniences. Similarly, linking social media or communication apps streamlines tasks like sharing updates and collaborating with other platforms—without having to switch interfaces or constantly re-authenticate.

To ensure a smooth experience, the screen walks the user through input fields and prompts. For secondary emails, users can simply enter the address and verify it with a one-time code or email link. For social media and communication customers, such as LinkedIn, Slack, or Teams, the system utilizes the standard User Authentication frameworks implemented for the system and here is simple “mapping” additional customers validated for the user.

When successfully configured, users can benefit from automated notifications, advanced collaboration features, and additional security measures. For example, if a user’s primary email is compromised or inaccessible, the secondary email can serve as a backup for password resets or multi-factor challenges. Additionally, linking social customers can enable features like unified messaging, simplified file sharing, or rich data exchange (e.g., importing contacts from LinkedIn). Administrators and the broader organization also benefit from heightened user engagement and reduced support overhead, as common customer issues—such as lost password retrieval or external collaboration—are handled more efficiently and securely through these integrated connections.

This screen should also be available as a standalone page in the Settings section of the application.

Onboarding Completion/Confirmation Page

Once all required steps are completed, users land on a confirmation page summarizing their onboarding choices. This page lists key configurations—like customer name, admin users, integrations enabled, and plan type—and might also generate a concise PDF or other exportable format for record-keeping. The primary goal is to reassure the user that the customer is now fully operational.

A successful completion message may also link to a knowledge base or a library of advanced training materials, inviting new users to learn more about optional features or best practices. This “Next Steps” approach fosters continuous learning and encourages customers to explore more of the platform’s capabilities once core setup is complete.

If re-running the wizard for updates, the confirmation page indicates which changes were made this session compared to the previous configuration. This “delta” view can be extremely valuable for auditing and compliance, allowing administrators to track how and when critical customer settings were adjusted.