# 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                     |
