Assist_Design/docs/uat/01-signup-and-account-creation.md

Signup and Account Creation

Overview

This journey covers how a new user creates an account on the Customer Portal. The process starts with email verification, then branches depending on whether the user is completely new, already exists in Salesforce, or already has a WHMCS billing account. By the end, the user has a portal login, a linked WHMCS Client record, and an updated Salesforce Account.

Portal Flow

Step 1: Enter Your Email

1. Go to the Get Started page at /auth/get-started. You can reach it from the Login page by clicking "Get started" or "Transfer your account."
2. You will see a simple form titled "Get Started" with the subtitle "Enter your email to begin."
3. Enter your email address in the Email Address field and click Send Verification Code.
4. The system sends a 6-digit one-time code to that email address.

Step 2: Verify Your Email

1. The page changes to "Verify Your Email" with the subtitle "Enter the code we sent to your email."
2. Your email address is shown on screen so you can confirm the right address was used.
3. Enter the 6-digit code. The code auto-submits once all 6 digits are entered, or you can click Verify Code manually.
4. The code expires after 10 minutes. If it expires, use the Resend code link to get a new one. Check your spam folder if it does not arrive.
5. If you entered the wrong email, click Change email to go back to the previous step.
6. You have a limited number of attempts. If you are running low, the portal shows a warning like "2 attempts remaining."

Step 3: Account Status (What Happens After Verification)

After your code is verified, the system checks whether your email is already known. You will see one of four outcomes:

Outcome A: New Customer (No Existing Records)

• The page shows "Email Verified!" with a green checkmark.
• The message says: "Let's set up your account so you can access all our services."
• Click Continue to proceed to the full account creation form.

Outcome B: Salesforce-Only Customer (Known From a Previous Inquiry)

• The page shows "Welcome back, [First Name]!" and explains that information was found from a previous inquiry.
• A summary card shows what data is already on file (name, email, address from a previous inquiry) and what still needs to be provided (phone number, date of birth, password).
• If an eligibility status was already determined, it is shown as well.
• Click Continue to proceed to the account creation form, which will have some fields pre-filled.

Outcome C: Existing WHMCS Billing Account (Not Yet Linked to the Portal)

• The page shows "Welcome Back!" (or "Welcome back, [First Name]!") and explains that an existing billing account was found.
• A summary card shows what data is already on file from WHMCS (email verified, name, phone number, address) and what you will need to provide (new portal password).
• Click Continue to proceed to the migration form.

Outcome D: Portal Account Already Exists

• The page shows "Account Found" with a message saying you already have a portal account.
• You are given a Go to Login button that takes you to the login page with your email pre-filled.

Step 4a: Complete Account Form (New Customer or Salesforce-Only)

This form collects the remaining information needed to create your account.

For brand-new customers, you fill in:

• First Name and Last Name
• Address (using a Japan-specific address form with postcode, prefecture/state, city, and street address fields)
• Phone Number
• Date of Birth (date picker)
• Gender (radio buttons: Male, Female, Other)
• Password and Confirm Password
• Accept Terms of Service and Privacy Policy checkbox (required)
• Marketing consent checkbox (optional)

For Salesforce-only customers, name and address are pre-filled from the Salesforce Account record. You see a summary of the pre-filled info at the top, and you fill in the remaining fields (phone, date of birth, gender, password, terms).

Password requirements are shown as you type, with real-time validation:

• At least 8 characters
• Contains an uppercase letter
• Contains a lowercase letter
• Contains a number

Click Create Account when everything is filled in.

Step 4b: Migrate Account Form (Existing WHMCS Customer)

This form is simpler because your billing information is already on file in WHMCS.

• Your name, email, phone, and address are shown in disabled (greyed-out) fields so you can see what is on file but cannot change them here.
• Date of birth and gender are not collected during migration — WHMCS already has this information.
• You fill in:
  • Password and Confirm Password (same requirements as above)
  • Accept Terms of Service and Privacy Policy (required)
  • Marketing consent (optional)

Click Set Up Account when ready.

Step 5: Success

• The page shows "Account Created!" with a green checkmark.
• The message says: "Your account has been set up successfully. You can now access all our services."
• You are given two options:
  • Go to Dashboard -- takes you to your new account dashboard.
  • Check Internet Availability -- takes you to the internet service page to check eligibility at your address.
• You are now logged in automatically and can start using the portal.

What Happens in WHMCS

After a successful signup, the following should be visible in WHMCS:

• A new Client record is created (for new and Salesforce-only customers) or the existing Client record is linked (for WHMCS migration).
• Navigate to Clients > Client List and search by the email address used during signup.
• Open the Client record and check:
  • First Name and Last Name match what was entered during signup.
  • Email Address matches the verified email.
  • Phone Number matches what was entered.
  • Address fields (Address 1, City, State, Postcode, Country) match what was entered.
  • Custom Fields (under the client profile or a Custom Fields tab):
    • Customer Number (custom field ID 198) -- this is the critical linking field. It stores the Salesforce Account Number (SF_Account_No__c) and is how the portal connects a WHMCS Client to a Salesforce Account.
    • Date of Birth (custom field ID 201) -- matches what was entered during signup.
    • Gender (custom field ID 200) -- matches what was selected during signup.
• For brand-new customers, the Client record should have an Active status.
• For WHMCS migration users, the existing Client record should now be linked -- no new Client should have been created. The Customer Number field (198) is populated with the Salesforce Account Number if it was not already set.

How WHMCS Links to Salesforce

The link between WHMCS and Salesforce is established through the Customer Number:

1. The Salesforce Account has a field SF_Account_No__c (the Customer Number).
2. The WHMCS Client stores this same value in custom field 198 (Customer Number).
3. The portal's internal database stores a mapping record linking: Portal User ID ↔ WHMCS Client ID ↔ Salesforce Account ID.

This three-way link is created during signup and is essential for all cross-system operations.

What Happens in Salesforce

After a successful signup, the following should be visible in Salesforce:

• Search for the Account record using the email address or Customer Number (SF_Account_No__c).
• Check these fields on the Account:

Field	API Name	Expected Value
Customer Number	SF_Account_No__c	The unique customer identifier (matches WHMCS custom field 198)
Portal Status	Portal_Status__c	Active
Portal Registration Source	Portal_Registration_Source__c	New Signup (new customers) or Migrated (WHMCS migration)
WHMCS Account	WH_Account__c	Format: "#1234 - Customer Name" (contains the WHMCS Client ID)
Portal Last Sign-In	Portal_Last_SignIn__c	Timestamp of the signup
Email	PersonEmail	The verified email address
Phone	Phone	The phone number entered

• The associated Contact record should have the correct email address and name.

Key Things to Verify

• Try signing up with an email that already has a portal account. You should see the "Account Found" message and be directed to log in.
• Try signing up with an email that exists in WHMCS but not the portal. You should see the WHMCS migration flow with pre-filled data.
• Try signing up with an email that exists only in Salesforce (from a previous inquiry). You should see pre-filled name and address data.
• Try signing up with a completely new email. You should get the full account creation form with no pre-filled data.
• Verify that password validation works: try a password shorter than 8 characters, one without uppercase, one without a number. Each should show an error.
• Verify the Terms of Service checkbox is required -- the form should not submit without it.
• Check that the verification code expires after 10 minutes and that the "Resend code" option works.
• After signup, check WHMCS and Salesforce to confirm the records were created or updated correctly.
• For WHMCS migration, confirm that no duplicate Client was created in WHMCS.
• Verify that after successful account creation, you are automatically logged in and can access the dashboard without needing to log in again.