Guided Setup

Overview

Guided Setup is Upvendo's interactive onboarding wizard that walks new merchants through the essential configuration steps needed to get their business operational. It organizes setup tasks into service-specific paths (Self-Service, Online Ordering, QR Code), tracks completion progress per task, and provides instructional video content for each step. The system uses event-driven progress tracking that automatically marks tasks as completed when the corresponding entities are created elsewhere in the backoffice.

The wizard is presented as a dialog overlay that can appear on any backoffice page, with dedicated video content that provides contextual guidance for each configuration step. Progress is persisted per vendor, per location, and per task in the GuidedSetupProgress model, allowing users to resume setup across sessions.

Purpose

This page lets you follow a structured onboarding flow to configure your Upvendo business, tracking progress across multiple service paths and setup categories, with video tutorials guiding you through each step.

Key Concepts

• Service Path: A top-level grouping of setup tasks organized by business channel. The three supported paths are self-service (kiosk setup), online-ordering (web ordering setup), and qr-code (table QR ordering setup). Each path has its own categories and tasks defined in the config/guided-setup.php configuration file under the paths key. Valid service paths are dynamically resolved from array_keys(config('guided-setup.paths')).
• Setup Category: A group of related tasks within a service path (e.g., initial_setup, build_menu). Each category has an id, title, description, order (for sorting), and a tasks array of task IDs. The initial_setup category has special significance -- its required tasks must all be completed before other categories are enabled.
• Task: An individual setup step defined in config('guided-setup.tasks') with fields: id, title, description, url (the backoffice page where the action is performed), required (boolean), global (boolean, whether the task is location-independent), and video (containing url, description, duration, and thumbnail). Tasks are referenced by ID from within categories.
• Progress Tracking: Per-task completion is stored in GuidedSetupProgress documents in the settings MongoDB collection (model type guided_setup_task_progress). Each record tracks vendor_id, setup_id (category ID), task_id, location_id (null for global tasks), is_completed, video_watched, and video_marked fields. The getOrCreateTaskProgress method handles idempotent creation of progress records.
• Event-Driven Completion: Tasks are automatically marked as completed when the corresponding entity is created anywhere in the backoffice. The GuidedSetupTaskListener handles over 20 event types including ItemCreated, MenuCreated, DisplayGroupCreated, LocationCreated, LanguageCreated, PaymentProfileCreated, BillingProfileCreated, BrandingProfileCreated, ReceiptSettingCreated, PrinterDeviceCreated, PrinterProfileCreated, KdsDeviceCreated, KdsProfileCreated, CustomerCreated, OfferCreated, ModifierGroupCreated, TaxRateCreated, TaxCategoriesCreated, CategoryCreated, TranslationsCreated, LoyaltyCreated, GiftCardsCreated, OnlineOrderingCreated, InHouseSettingCreated, and TableQrCodeCreated. Each event implements the GuidedSetupTaskEventInterface and carries the vendor database, location ID, service path, and setup category ID.

Route

• Backoffice Route: /guided-setup (accessed via dialog overlay on any page)
• Backend Controller: app/Http/Controllers/Api/BackOffice/GuidedSetupController.php
• Orchestrator: app/Services/Orchestrators/BackOffice/Settings/GuidedSetupOrchestrator.php
• Service: app/Services/BackOffice/Settings/GuidedSetupService.php
• Model: app/RawModels/GuidedSetupProgress.php
• Repository: app/Repositories/GuidedSetupProgressRepository.php
• Factory: app/RawFactories/GuidedSetupProgressFactory.php
• Listener: app/Listeners/GuidedSetupTaskListener.php
• Events: app/Events/GuidedSetup/*.php (20+ event classes)
• Request Validators: app/Http/Requests/BackOffice/Settings/GuidedSetup/GuidedSetupRequest.php, UpdateProgressRequest.php, VideoRequest.php, StatusRequest.php
• Resource: app/Http/Resources/BackOffice/Settings/GuidedSetup/GuidedSetupResource.php
• Vue Components: src/components/dialogs/GuidedSetupDialog.vue, src/components/dialogs/guided-setup/SelectGuidedSetup.vue, src/components/dialogs/guided-setup/GuidedSetupItems.vue, src/components/dialogs/guided-setup/GuidedSetupVideo.vue, src/components/dialogs/guided-setup/GuidedSetupVideoContentDialog.vue, src/components/dialogs/guided-setup/GuidedSetupItemIcon.vue
• Store Module: src/store/modules/guidedSetup.ts
• CLI Command: app/Console/Commands/UpdateGuidedSetupProgress.php

Actions

View All Service Paths

Retrieve guided setup data for all service paths in a single request. Iterates through all paths defined in the config, returning for each one the setup categories with task lists, completion status, and overall progress. When no location is selected (location_id is null), only self-service returns data; online-ordering and qr-code return empty results with zero progress.

• Endpoint: GET /api/back-office/guided-setup?location_id={locationId}
• Response: JSON object keyed by service path, each containing data (array of GuidedSetupResource), overall_progress ({total_setups, completed_setups, progress}), and enable flag

View Service Path Details

Retrieve detailed setup information for a specific service path. Returns all categories with their tasks, individual task completion status (completed_tasks array), progress percentage, is_completed flag, and enable flag (dependent on initial_setup completion).

• Endpoint: GET /api/back-office/guided-setup/{service}?location_id={locationId}
• Response: JSON with data (array of GuidedSetupResource), overall_progress, and enable flag

View Setup Category

Retrieve a specific setup category within a service path, including all tasks and their individual completion and video status.

• Endpoint: GET /api/back-office/guided-setup/{service}/{setupId}?location_id={locationId}
• Response: JSON GuidedSetupResource or null if not found

Update Task Progress

Manually mark a specific task as completed within a setup category. The system validates that both the setup and task exist in the configuration. Determines the correct location_id based on whether the task has global: true (global tasks use null for location). Creates or updates the GuidedSetupProgress record via getOrCreateTaskProgress.

• Endpoint: POST /api/back-office/guided-setup/{service}/{setupId}/progress
• Request Body: task_id (required, string), location_id (optional, string)
• Response: Success response

Complete Entire Setup

Mark all tasks within a setup category as completed at once. Iterates through every task in the specified setup and calls updateProgress for each one. Useful for bulk-completing a category after manual configuration.

• Endpoint: POST /api/back-office/guided-setup/{service}/{setupId}/complete
• Response: Success response

Reset Setup Category

Clear all progress records for a specific setup category, resetting it to an incomplete state. Deletes matching GuidedSetupProgress documents using a filter that matches the vendor_id, setup_id, and uses an $or condition to match both the specific location_id and null (for global tasks).

• Endpoint: POST /api/back-office/guided-setup/{service}/{setupId}/reset
• Response: Success response

Reset All Setups for a Service

Clear all progress records for all setup categories within a service path. Iterates through each setup in the service path's configuration and calls resetSetup for each one.

• Endpoint: POST /api/back-office/guided-setup/{service}/reset
• Response: Success response

Get Video for Page

Retrieve the guided setup video associated with a specific backoffice page URL. Searches through all tasks in the service path to find one with a matching url field. Returns comprehensive video metadata including completion status and navigation info. Special handling exists for payment_profile and billing_profile tasks: if one is completed but the other is not, the "next task" points to the incomplete sibling rather than the sequential next task.

• Endpoint: GET /api/back-office/guided-setup/{service}/video?url={pageUrl}&location_id={locationId}
• Response: JSON with id, title, description, is_completed, is_video_played, required, video_url, video_title, video_description, video_duration, video_thumbnail, next_task_title, next_task_url, is_last_task; or null if no matching task found

Mark Video Status

Mark a video as watched (watched: true) or unwatched (watched: false) for a specific task. Searches across all service paths and categories to find the task by ID, then creates or updates the GuidedSetupProgress record's video_marked field. The unmarkVideo method finds existing progress and sets video_marked to false.

• Endpoint: POST /api/back-office/guided-setup/{service}/video/status
• Request Body: task_id (required, string), watched (optional, boolean, defaults to true), location_id (optional, string)
• Response: Success response

Fields

Field	ID	Type	Required	Validation
Location ID	location_id	String	No	sometimes|string|nullable -- optional location scope
Task ID	task_id	String	Yes (progress/status)	required|string -- must match a task ID in the config
URL	url	String	Yes (video lookup)	required|string -- backoffice page path to match against task URLs
Watched	watched	Boolean	No (status)	boolean -- defaults to true; false unmarks the video

Business Rules

• The initial_setup category must have all its required tasks (where required: true) completed before other categories within the same service path are enabled. This is checked by the isInitialSetupCompleted method, which iterates through required tasks and verifies each has a completed progress record. If no initial_setup category exists, other categories are considered unlocked.
• Global tasks (where global: true in the task configuration) track progress without a location ID (location_id: null), meaning their completion applies across all locations for the vendor. Location-specific tasks track progress per location, so completing a task in one location does not affect another.
• Progress is calculated as (completed_tasks / total_tasks) * 100 and cast to an integer. A setup category is considered complete when progress reaches exactly 100%. Overall progress across a service path is calculated as (completed_setups / total_setups) * 100.
• Special navigation handling exists for payment_profile and billing_profile tasks in the video endpoint: when viewing one and the other is not yet completed, the "next task" navigation redirects to the incomplete sibling task rather than following the sequential task order.
• When no location is selected (null location_id), only the self-service path returns data. The online-ordering and qr-code paths return empty collections with zero progress, as they require a location context.
• The resetSetup method uses a MongoDB $or query to delete progress records for both the specific location and global (null) tasks simultaneously, ensuring a complete reset.
• Progress records are idempotent -- getOrCreateTaskProgress checks for an existing record before creating a new one, and only updates is_completed to true if the record exists but is not yet completed.

Customer Impact

• Kiosk: Guided Setup for the self-service path walks merchants through all steps needed to deploy a functional kiosk, including location setup, language configuration, menu and item creation, display group organization, device profiles, branding, payment configuration, billing profiles, receipt settings, and more.
• Online Ordering: The online ordering path guides merchants through configuring their web ordering channel, ensuring menus, delivery settings, online ordering configuration, and payment options are properly set up before going live.
• QR Ordering: The QR code path ensures table ordering is correctly configured with in-house settings, QR code generation, menu assignments, and other dine-in specific configurations.
• Time to First Order: Guided Setup is the primary mechanism for reducing time-to-first-order for new merchants, providing a clear path from registration to operational readiness.

FAQs

Is Guided Setup mandatory?

No. Guided Setup is a helpful onboarding tool but can be dismissed at any time. Merchants can configure their business manually through the standard backoffice pages. The guided setup dialog visibility is controlled by the show_guided_setup_dialog state in the store module.

Can I reset my progress and start over?

Yes. You can reset individual setup categories via POST /{service}/{setupId}/reset, all setups within a service via POST /{service}/reset, or all services at once via the resetAllServices method. Resetting clears all GuidedSetupProgress records for the specified scope.

Do tasks complete automatically?

Yes. Most tasks are marked as completed automatically when you create the corresponding entity elsewhere in the backoffice. For example, creating a menu item dispatches an ItemCreated event that the GuidedSetupTaskListener processes to update the relevant task progress. You can also manually mark tasks as completed through the update progress endpoint.

What are the three service paths?

The paths are self-service (kiosk configuration, always available), online-ordering (web ordering setup, requires location), and qr-code (table QR ordering setup, requires location). Each contains specific setup categories and tasks relevant to that channel.

Can I access Guided Setup later after initial onboarding?

Yes. The Guided Setup dialog can be opened from any backoffice page. The system persists your progress in GuidedSetupProgress documents and shows your current completion status whenever you return.

How are videos associated with setup tasks?

Each task in the config has a video object with url, description, duration, and thumbnail fields. The video endpoint matches the current page URL against task URLs to find and return the relevant video. The video_marked field on the progress record tracks whether the user has watched the video.

Troubleshooting

Guided Setup shows 0% progress even though I have configured items

Progress is tracked per vendor, per location, and per service path. Ensure you are viewing the correct location and service path. If entities were created before guided setup tracking was implemented, run the UpdateGuidedSetupProgress artisan command to retroactively sync progress records.

"Invalid service type" error

The service path parameter must be one of the valid values defined in config('guided-setup.paths'). The standard values are self-service, online-ordering, and qr-code. Check the URL for typos. The controller validates the service against array_keys(config('guided-setup.paths')) and throws a NotFoundHttpException for invalid values.

Setup categories other than "Initial Setup" are disabled

Other categories are locked until all required tasks in initial_setup are completed. Check the initial setup category's progress and complete any remaining required tasks (those with required: true in the config). Once all required initial setup tasks show as completed, the other categories will be enabled.

Video content is not loading

Verify the video URL is accessible and the config/guided-setup.php file contains valid video entries for the requested task. Check that the url parameter in the video request matches the url field defined in the task configuration exactly. The system uses strict string comparison ($task['url'] === $url).

Task shows as incomplete after creating the entity

Ensure the correct event is being dispatched. For example, creating a display group should dispatch DisplayGroupCreated with the correct vendor database, location ID, service path, and setup category ID. Check the GuidedSetupTaskListener to verify it handles the relevant event type. Also verify the event's location ID matches the location context of the guided setup view.

Global task completion does not appear across locations

Global tasks (where global: true) store progress with location_id: null. The getCompletedTasksForSetup method correctly resolves the location ID for each task based on its global flag. If the task shows as incomplete, verify the progress record exists with location_id: null rather than a specific location ID.

Technical Details

Configuration Structure

The guided setup system is entirely configuration-driven via config/guided-setup.php. The configuration has two main sections:

• tasks: A flat array of all task definitions, each with id, title, description, url, required, global, and video (with url, description, duration, thumbnail). Tasks are shared across service paths.
• paths: A nested structure keyed by service path name (e.g., self-service), containing categories. Each category has a title, description, order, and tasks array of task IDs referencing the flat task list.

Backoffice Store Module Types

The frontend store module defines several TypeScript types for guided setup data:

• GuidedSetupDetail: Contains enable, data (array of items), and overall_progress with total_setups, completed_setups, and progress
• GuidedSetupItemDetail: Contains id, title, description, order, tasks, progress, is_completed, completed_tasks, and enable
• GuidedSetupTaskItem: Contains id, title, description, is_completed, required, and url
• GuidedSetupVideoItem: Contains video metadata and navigation info including next_task_title, next_task_url, and is_last_task

Event System Architecture

Each GuidedSetup\*Created event implements the GuidedSetupTaskEventInterface which requires methods to provide the vendor database name, location ID, service path, and setup category ID. The base class GuidedSetupTaskEvent provides the common implementation. The GuidedSetupTaskListener receives these events and delegates to the GuidedSetupService.updateProgress method. This decoupled architecture allows any part of the application to trigger guided setup progress updates by dispatching the appropriate event.

CLI Command

The UpdateGuidedSetupProgress artisan command provides a way to retroactively sync guided setup progress for vendors who configured entities before the guided setup tracking system was in place. This is useful during migrations or when the configuration is updated with new tasks.

Assistant Guidance

When users ask about Guided Setup, explain it as a structured onboarding wizard with three service paths organized into categories with individual tasks. Help users understand the prerequisite flow: the initial_setup category's required tasks must be completed before other categories are unlocked. If users are confused about why a task is not marked as complete, explain the event-driven completion system -- tasks auto-complete when the corresponding entity is created. Suggest they check whether the entity was created in the correct location context. For users who want to skip the wizard, reassure them that all configuration can be done manually through the standard backoffice pages. When discussing videos, explain that each setup task has an associated tutorial video that provides step-by-step guidance for that specific configuration page.

Relations

Depends On

• Vendor: Guided setup progress is scoped to the vendor ID, which is resolved via the VendorTrait.
• Locations: Location-specific tasks track progress per location. When no location is selected, only self-service data is returned.
• Config File: All task definitions, categories, paths, and video metadata are loaded from the config/guided-setup.php configuration file. Changes to this file immediately affect the guided setup behavior.
• Event System: Auto-completion relies on Laravel's event system. Each entity creation must dispatch the appropriate GuidedSetup\*Created event for tasks to be automatically marked complete.

Affects

• All Feature Areas: Guided Setup references tasks spanning the entire platform: menus, items, display groups, categories, locations, languages, payment profiles, billing profiles, branding profiles, receipt settings, printer devices and profiles, KDS devices and profiles, customers, offers, modifier groups, tax rates, tax categories, translations, loyalty, gift cards, online ordering, in-house settings, and table QR codes.
• Onboarding Experience: Guided Setup is the primary onboarding tool for new merchants, directly affecting time-to-first-order and merchant activation rates.
• Video Content: Provides contextual video tutorials for each backoffice page via the video endpoint, enhancing the learning experience throughout the platform.
• Backoffice Navigation: The guided setup dialog and video overlay components appear across all backoffice pages, providing persistent onboarding context.