Onboarding Wizard
After your organization is provisioned on Waqti, the onboarding wizard walks you through the minimum structure needed to run procurement safely: who you are, how you are organized, who can log in, how spend is approved, what budgets exist, who you buy from, and (optionally) which projects capture spend.
The wizard is designed to be flexible: you can skip individual steps, jump to any step you are allowed to reach, skip the entire flow, or come back later from the app when you need to add or adjust setup data.
Overview: seven steps (0–6)
The experience is organized as seven primary steps, indexed 0 through 6, plus a finish state that marks onboarding complete and sends you to the dashboard.
| Step | Focus |
|---|---|
| 0 | Company information and procurement preferences |
| 1 | Departments |
| 2 | Inviting users |
| 3 | Approval workflows |
| 4 | Budgets |
| 5 | Vendors |
| 6 | Projects (optional) |
Completing the wizard updates your tenant’s onboarding flags and redirects you to /admin (the main application dashboard). If you skip onboarding entirely, you are also marked complete for gating purposes and redirected to /admin, with the option to configure everything later.
Re-enter anytime
The onboarding UI remains available at /onboarding even after completion, so administrators can revisit the wizard to refine company data, add departments, or extend workflows without blocking day-to-day usage.
Step 0: Company information
This step captures your tenant’s public profile and several plan-gated procurement options.
Identity and contact
| Field | Notes |
|---|---|
| Company name (English) | Required. Primary display name. |
| Company name (Arabic) | Optional. Shown where bilingual labels are used. |
| Phone | Optional. |
| City | Optional. |
| Address | Optional; longer free text. |
Branding files
| Asset | Rules |
|---|---|
| Company logo | Optional image: PNG, JPG, JPEG, or SVG, up to 2 MB. Stored on your configured disk (e.g. cloud storage). |
| Signature image | Optional: PNG, JPG, or JPEG, up to 1 MB. Used where a visual signature is appropriate on documents. |
Uploads are checked against your tenant’s storage limits; if the limit would be exceeded, the request fails with a validation error on the logo field.
Procurement mode
You may select a procurement mode that applies preset behavior across the product:
simple— Streamlined flows for smaller teams.standard— Balanced defaults for typical mid-market procurement.enterprise— Richer structure for complex approvals and controls.
The list of modes presented in the wizard comes from ProcurementSettingsService (getAvailableModes / applyMode), so only modes valid for your build and plan appear.
Plan-gated options
Depending on subscription features:
- Three-way matching — Toggle enable three-way matching when your plan includes
three_way_matching. This aligns PO, receipt, and invoice before payment. - Budget alert thresholds — When
budget_alertsis available, you can provide threshold percentages (0–100) that drive warnings as budgets are consumed.
These fields are validated as optional booleans or integer arrays only when your tenant is entitled to them.
Progress
Saving company information advances the stored onboarding_step to 1.
Step 1: Create departments
Departments segment spend, ownership, and reporting.
| Field | Validation |
|---|---|
| Name | Required, up to 255 characters. |
| Code | Required, up to 10 characters, unique per tenant. |
| Description | Optional, up to 500 characters. |
New departments are created active by default. Duplicate codes return a friendly error (department_code_already_exists).
Successful creation moves onboarding_step to 2.
Step 2: Invite users
Add people who will sign in to Waqti. Each invite creates a full user record (this wizard path uses password creation rather than email-only invite).
| Field | Notes |
|---|---|
| Full name | Required. |
| Required; must be unique across all users. | |
| Password | Required with confirmation; must satisfy Laravel’s default password rules. |
| Department | Required; must reference an existing department in your tenant. |
| Role | Required; must be one of the slugs below. |
| Manager | Optional; if omitted, the system may infer a manager for certain roles (e.g. employee, procurement_officer) by looking for a manager or department_head in the same department. |
Available role slugs in the wizard
The onboarding API accepts exactly these role values:
admin, department_head, manager, employee, finance_viewer, cfo, finance_manager, procurement_manager, procurement_officer
If a slug does not yet exist as a Role row for your tenant, Waqti auto-creates a role with that slug and an empty permission set—you should refine permissions later under your security model.
The user is linked to the role in both role_id and the role_user pivot (with tenant context for row-level security).
Successful invites advance onboarding_step to 3.
Step 3: Set up approval workflows
Workflows route purchase orders through the right approvers based on department and amount.
| Field | Notes |
|---|---|
| Workflow name | Required. |
| Department | Required; scopes the workflow. |
| Minimum amount | Required; numeric, ≥ 0. |
| Maximum amount | Optional; if set, must be greater than the minimum (open-ended upper range is allowed when null). |
On create, Waqti also seeds a default first step titled “Department Head Approval” tied to the department_head role when that role exists.
Creating a workflow sets onboarding_step to 4.
::: note Custom workflows feature flag Tenants with the custom_workflows plan feature see richer workflow capabilities elsewhere in the product; the wizard still creates a baseline workflow you can extend later. :::
Step 4: Configure budgets
Budgets anchor CAPEX and OPEX envelopes per department and fiscal year.
| Field | Notes |
|---|---|
| Department | Required. |
| Year | Required integer between 2020 and 2100. |
| CAPEX total | Required; inclusive of VAT at the percentage you specify. |
| OPEX total | Required; same. |
| VAT percentage | Optional; defaults to 15 if omitted. |
The service derives ex-VAT amounts from your totals and the VAT rate, and initializes used and reserved counters to zero.
Saving a budget in the wizard currently sets onboarding_step to 4 (same milestone index as workflows in the backend counter—your furthest progress may already be step 4 or higher depending on actions taken).
Step 5: Add vendors
You need at least one vendor to raise POs in most processes.
| Field | Required | Notes |
|---|---|---|
| Vendor name | Yes | Up to 255 characters. |
| Contact email | Yes | Valid email. |
| Contact phone | Yes | Up to 20 characters. |
| VAT number | Yes | Up to 50 characters. |
| Commercial registration | No | Optional CR number. |
Waqti assigns a VEN-##### style vendor code automatically from the latest code in your tenant.
Vendor creation advances onboarding_step to 5.
Step 6: Create projects (optional)
If projects are part of your plan, this step lets you structure capital or operational initiatives.
| Field | Notes |
|---|---|
| Project name | Required. |
| Department | Required. |
| Budget | Required total budget, ≥ 0. |
| CAPEX / OPEX budget | Optional numeric splits; default 0 if omitted. |
| Start / end dates | Optional; end must be after start when both are provided. |
| Description | Optional narrative. |
Projects receive an auto-generated code such as PRJ-YYYY-##### for the current year sequence.
Creating a project moves onboarding_step to 6.
Milestones on Enterprise+
Tenants with the milestones feature may also see milestone templates in the wizard context for later use in PO structuring.
Navigation behavior
Skip forward one step
Skip / Next without filling optional data calls the nextStep endpoint, which increments onboarding_step by one up to a maximum of 7 (the terminal index used internally).
Jump to a specific step
Go to step accepts any integer 0–7, letting administrators move backward for corrections or forward to a screen they are ready to complete. The UI typically still enforces sensible UX limits, but the API allows direct navigation within that range.
Skip entire onboarding
Skip setup marks onboarding_skipped, onboarding_completed, and onboarding_completed_at, then redirects to /admin. Middleware that normally forces onboarding will no longer block you.
Finish
Complete sets onboarding_completed, onboarding_step = 7, onboarding_completed_at, and performs an Inertia location redirect to /admin.
After onboarding
- New users created in step 2 can sign in immediately with the credentials you chose (ensure you communicate passwords securely).
- Departments, workflows, budgets, vendors, and projects remain editable from their respective settings and master data areas— the wizard is a guided path, not the only entry point.
- If middleware still requires onboarding for some routes, completing or skipping clears that gate.
Tips
Do departments before users
Users must belong to a department. Create at least one department in step 1 before inviting people in step 2.
Start with one workflow band
Create a simple workflow covering your most common PO range, then add parallel workflows for higher thresholds once you see real traffic.
VAT defaults
If your statutory VAT rate differs from 15%, set VAT percentage explicitly on each budget row in step 4 so ex-VAT analytics stay accurate.
Vendor data quality
Phone, email, and VAT number are required in the wizard vendor form—keep them accurate for e-invoicing, matching, and vendor communications.
Projects can wait
Step 6 is optional for many tenants. Skip it during onboarding if project accounting is not live yet; you can add projects later when the feature is needed.
Related topics
- Quick Start — First PO and day-one checklist.
- First Steps — Deeper orientation after login.