Assist_Design/docs/uat/appendix-cross-reference.md

Cross-Reference Appendix

Quick-reference tables mapping Customer Portal features to their corresponding records in WHMCS and Salesforce. Use this when you need to quickly look up where to verify something.

How the Systems Link Together

Understanding how WHMCS and Salesforce are connected is essential for UAT. Here is the linking chain:

Customer Linking (established during signup)

Portal User ID  ←→  WHMCS Client ID  ←→  Salesforce Account ID
     (portal database stores this three-way mapping)

System	Field	What It Stores
WHMCS Client	Custom Field #198 ("Customer Number")	The Salesforce Account Number (SF_Account_No__c)
Salesforce Account	WH_Account__c	The WHMCS Client ID in format "#1234 - Customer Name"
Salesforce Account	SF_Account_No__c	The Customer Number (same value as WHMCS field #198)

To verify the link: Open the WHMCS Client's custom fields and find the Customer Number. Then search Salesforce for an Account with that same SF_Account_No__c. The Account's WH_Account__c field should contain the WHMCS Client ID.

Subscription / Opportunity Linking (established during provisioning)

WHMCS Service  ←→  Salesforce Opportunity

System	Field	What It Stores
WHMCS Service	Custom Field "OpportunityId"	The Salesforce Opportunity ID
Salesforce Opportunity	WHMCS_Service_ID__c	The WHMCS Service/Product ID

To verify the link: Open a WHMCS Service's custom fields and find the OpportunityId. Then open that Opportunity in Salesforce and check WHMCS_Service_ID__c matches the WHMCS Service ID.

This bidirectional link is what makes cancellation work -- the portal uses it to find the right Opportunity to update.

Order Linking (established during provisioning)

Salesforce Order  →  WHMCS Order
Salesforce OrderItem  →  WHMCS Service

System	Field	What It Stores
Salesforce Order	WHMCS_Order_ID__c	The WHMCS Order ID
Salesforce OrderItem	WHMCS_Service_ID__c	The WHMCS Service ID for each line item

---

Salesforce Account Fields Reference

These are the key fields on the Salesforce Account record that the portal reads and writes:

Portal-Specific Fields

Field Label	API Name	Set By	When	Values
Customer Number	SF_Account_No__c	Salesforce	Account creation	Unique identifier (matches WHMCS field #198)
Portal Status	Portal_Status__c	Portal	Signup	"Active"
Portal Registration Source	Portal_Registration_Source__c	Portal	Signup	"New Signup" or "Migrated"
Portal Last Sign-In	Portal_Last_SignIn__c	Portal	Each login	Timestamp
WHMCS Account	WH_Account__c	Portal	Signup	"#1234 - Customer Name" format

Internet Eligibility Fields

Field Label	API Name	Set By	When	Values
Internet Eligibility	Internet_Eligibility__c	SF Agent	After manual NTT check	Speed value (e.g., "Cross 10G", "Hikari 1G") or empty
Eligibility Status	Internet_Eligibility_Status__c	SF Agent	After review	Status of the check
Request Date	Internet_Eligibility_Request_Date_Time__c	Portal	When customer requests check	Timestamp
Checked Date	Internet_Eligibility_Checked_Date_Time__c	SF Agent	When agent completes review	Timestamp

ID Verification Fields

Field Label	API Name	Set By	When	Values
Verification Status	Id_Verification_Status__c	Portal / SF Agent	Upload / Review	"Not Submitted", "Submitted", "Verified", "Rejected"
Submitted Date	Id_Verification_Submitted_Date_Time__c	Portal	On document upload	Timestamp
Verified Date	Id_Verification_Verified_Date_Time__c	SF Agent	After approval	Timestamp
Note	Id_Verification_Note__c	SF Agent	After review	Internal notes
Rejection Message	Id_Verification_Rejection_Message__c	SF Agent	If rejected	Reason shown to customer

Standard Fields

Field Label	API Name	Description
Email	PersonEmail	Customer email address
Phone	Phone	Customer phone number
Billing Address	BillingStreet, BillingCity, BillingState, BillingPostalCode, BillingCountry	Customer address (snapshot at order time)

---

WHMCS Client Custom Fields Reference

Field ID	Field Name	What It Stores	Where to Find It
198	Customer Number	Salesforce Account Number (SF_Account_No__c) -- the critical cross-system link	Client > Profile > Custom Fields
200	Gender	Customer gender (Male, Female, Other)	Client > Profile > Custom Fields
201	Date of Birth	Customer DOB	Client > Profile > Custom Fields

---

Salesforce Opportunity Stage Reference

Stage	Display	Meaning
Introduction	Introduction	Initial interest (e.g., eligibility check requested)
WIKI	WIKI	Low-priority lead
Ready	Ready	Customer is eligible and ready to order
Post Processing	Post Processing	Order has been placed, being reviewed
Active	Active	Service is live
△Cancelling	Cancelling	Cancellation requested, service still running until end of billing cycle
〇Cancelled	Cancelled	Service has been cancelled
Completed	Completed	Service lifecycle complete
Void	Void	Lost or not eligible
Pending	Pending	On hold

---

Salesforce Case Origin Reference

Origin Value	Created By	Visible to Customer?	When Created
Portal Support	Customer (via support page)	Yes -- appears in customer's cases list	Customer creates a support ticket
Portal Notification	Portal (automatic)	No -- internal only	Order placed, eligibility requested, cancellation requested, ID verification uploaded
Web	Public contact form	No -- unlinked to account	Guest submits contact form

---

Portal Action → WHMCS Records

Portal Action	WHMCS Object	Where to Find It	Key Fields to Check
Sign up (new customer)	Client	Clients > Client List > search by email	First Name, Last Name, Email, Phone, Address, Custom Fields (#198 Customer Number, #200 Gender, #201 DOB)
Sign up (migrate WHMCS account)	Client (existing)	Clients > Client List > search by email	Confirm no duplicate created; Custom Field #198 now has Salesforce Account Number
Edit profile (email/phone)	Client	Clients > Client List > open client	Email Address, Phone Number updated
Edit address	Client	Clients > Client List > open client	Address 1, Address 2, City, State, Postcode, Country
Order provisioned	Product/Service	Client > Products/Services tab	Product name, Status (Active), Billing Cycle, Amount, Custom Field "OpportunityId" = SF Opportunity ID
Order provisioned	Order	Client > Orders tab	WHMCS Order created with line items
SIM plan change	Product/Service	Client > Products/Services tab	Product name updated to new plan, Amount updated (takes effect 1st of next month)
SIM data top-up	Invoice	Billing > Invoices > search by client	New invoice for top-up amount (500 JPY per GB), Status Paid
SIM reissue	Product/Service	Client > Products/Services tab	Same WHMCS service ID -- no new service created
Voice feature toggle	Add-on Services	Client > Products/Services tab	Voice Mail (pid 119), Call Waiting (pid 123) updated
View invoices	Invoices	Billing > Invoices > search by client	Invoice Number, Status, Amount, Due Date match portal
Pay invoice	Invoice + Transaction	Billing > Invoices > open invoice	Status changes to Paid; Transaction record created
Cancel subscription	Product/Service	Client > Products/Services tab	Status changes to Cancelled at end of billing cycle

Portal Action → Salesforce Records

Portal Action	Salesforce Object	Where to Find It	Key Fields to Check
Sign up	Account	Search by email or SF_Account_No__c	Portal_Status__c = Active, Portal_Registration_Source__c, WH_Account__c contains WHMCS Client ID
Sign up	Contact	Under the Account record	Email, First Name, Last Name
Place an order	Order	Account > Related > Orders	Status, Type, OpportunityId, service-specific fields (see doc 05 for full field list)
Place an order	Opportunity	Account > Related > Opportunities	StageName = "Post Processing", CommodityType__c, Opportunity_Source__c contains "Portal"
Place an order	OrderItem	Under the Order	Product2Id, UnitPrice, Quantity, Billing_Cycle__c
Place an order	Case	Cases tab (not visible to customer)	Origin = "Portal Notification", Subject contains order info
Order provisioned	Order	Same Order	WHMCS_Order_ID__c populated, Activation_Status__c = "Activated"
Order provisioned	OrderItem	Under the Order	WHMCS_Service_ID__c populated for each item
Order provisioned	Opportunity	Same Opportunity	WHMCS_Service_ID__c populated, StageName = "Active"
Create support case	Case	Cases tab > search by Account	Origin = "Portal Support", Subject, Priority, Status
Reply to support case	CaseComment	Under the Case	Comment body, Created Date
Upload residence card	Account	Search by SF_Account_No__c	Id_Verification_Status__c = "Submitted"
Upload residence card	ContentVersion	Account > Related > Files	Uploaded document file
ID approved by agent	Account	Same Account	Id_Verification_Status__c = "Verified", Id_Verification_Verified_Date_Time__c set
ID rejected by agent	Account	Same Account	Id_Verification_Status__c = "Rejected", Id_Verification_Rejection_Message__c has reason
Internet eligibility request	Account	Search by SF_Account_No__c	Internet_Eligibility_Request_Date_Time__c set
Internet eligibility request	Case	Cases tab	Origin = "Portal Notification", new Case created each time
Eligibility checked by agent	Account	Same Account	Internet_Eligibility__c populated with speed value, Internet_Eligibility_Checked_Date_Time__c set
Cancel SIM	Opportunity	Account > Opportunities	StageName = "△Cancelling", SIMScheduledCancellationDateAndTime__c set, WHMCS_Service_ID__c matches WHMCS service
Cancel SIM	Case	Cases tab (not visible to customer)	Origin = "Portal Notification"
Cancel Internet	Opportunity	Account > Opportunities	StageName = "△Cancelling", ScheduledCancellationDateAndTime__c set, CancellationNotice__c, LineReturn__c for equipment
Cancel Internet	Case	Cases tab (not visible to customer)	Origin = "Portal Notification"

Portal Feature → Data Source

This table shows where each portal feature gets its data from. Useful for understanding which system to check when something looks wrong.

Portal Feature	Primary Data Source	Secondary Source
Dashboard - Active Services count	WHMCS (subscriptions)	--
Dashboard - Open Cases count	Salesforce (cases)	--
Dashboard - Recent Orders	Salesforce (orders)	--
Dashboard - Recent Activity	Portal database (aggregated)	WHMCS + Salesforce
Dashboard - Task Cards	Portal (computed from multiple sources)	WHMCS + Salesforce
Service Catalog / Plans	Salesforce (Product2, PricebookEntry)	--
Eligibility Status	Salesforce (Account fields)	--
Checkout / Order Submission	Salesforce (Order, Opportunity)	--
Order Real-time Tracking	Salesforce Platform Events → Portal SSE	--
Subscription List	WHMCS (Products/Services)	--
SIM Management (usage, voice)	Freebit (via portal backend)	WHMCS for billing
SIM Plan Change	Freebit (execution)	WHMCS (billing update)
SIM Data Top-up	Freebit (execution)	WHMCS (invoice creation)
Invoices	WHMCS (Invoices)	--
Payments	WHMCS (Transactions)	--
Support Cases	Salesforce (Cases)	--
Identity Verification	Salesforce (Account + ContentVersion)	--
Notifications	Portal database	Triggered by Salesforce Platform Events
Address	WHMCS (Client record)	Japan Post API (for lookup)
Profile (name, DOB, gender)	WHMCS (Client record)	--
Profile (Customer Number)	Salesforce (Account SF_Account_No__c)	--

WHMCS Navigation Quick Reference

What You're Looking For	Where to Go in WHMCS
A customer's record	Clients > Client List > search by name or email
A customer's services	Open Client > Products/Services tab
Service custom fields (OpportunityId)	Open Client > Products/Services > click service > Custom Fields
A customer's invoices	Open Client > Invoices tab, or Billing > Invoices
A specific invoice	Billing > Invoices > search by invoice number
Payment transactions	Open an Invoice > Transactions section
Client custom fields (#198, #200, #201)	Open Client > Profile > Custom Fields section
Payment methods	Open Client > Pay Methods tab

Salesforce Navigation Quick Reference

What You're Looking For	Where to Go in Salesforce
A customer's account	Search globally by email or Customer Number (SF_Account_No__c), or Accounts tab
Portal status fields	Open Account > check Portal_Status__c, Portal_Registration_Source__c, WH_Account__c
WHMCS link verification	Open Account > check WH_Account__c contains WHMCS Client ID
Internet eligibility	Open Account > check Internet_Eligibility__c and related date fields
ID verification status	Open Account > check Id_Verification_Status__c and related fields
Orders for a customer	Open Account > Related > Orders
Opportunities for a customer	Open Account > Related > Opportunities
Opportunity → WHMCS link	Open Opportunity > check WHMCS_Service_ID__c
Cancellation status	Open Opportunity > check StageName for "△Cancelling" or "〇Cancelled"
Support cases (customer-visible)	Cases tab > filter Origin = "Portal Support"
Internal notification cases	Cases tab > filter Origin = "Portal Notification"
Case comments/replies	Open a Case > Related > Case Comments or Email Messages
Uploaded documents	Open Account > Related > Files (ContentVersion)
Product catalog	Products tab (Product2 records) > check Portal_Accessible__c = true