# Person Accounts

The Onboarded™ application supports Salesforce Person Accounts for organizations that use them. Person Accounts merge the Account and Contact objects into a single record type stored in the Account object.

> **What Are Person Accounts?** Person Accounts are a Salesforce feature (enabled via B2C license) where individual people are represented as Account records with `IsPersonAccount = true`. Fields like FirstName, LastName, and PersonEmail are available directly on the Account object.


## Person Account Detection

When you open the Onboarded™ Setup tab and navigate to Object Configuration, the application automatically checks if Person Accounts are enabled in your org using the following process:

1. **Schema Inspection:** The application uses `Schema.getGlobalDescribe()` to inspect the Account object's field metadata
2. **Field Check:** It looks for the `IsPersonAccount` field on the Account object. This field only exists when Person Accounts are enabled in the org
3. **Result:**
  - If `IsPersonAccount` field exists → Person Accounts are enabled → "Person Account" option appears in Employee object dropdown
  - If `IsPersonAccount` field does NOT exist → Person Accounts are disabled → "Person Account" option does NOT appear


> **Important:** The detection happens dynamically each time you load the Object Configuration tab. If you enable Person Accounts in your org after installing the Onboarded™ app, simply refresh the Onboarded™ Setup tab to see the "Person Account" option appear.


## Person Account Mapping Setup

1. **Navigate to Onboarded™ Setup.** From the Salesforce App Launcher, select **Onboarded™ Setup** tab. *Note: You must have the "Onboarded™ Admin" permission set assigned to see this tab.*
2. **Click Object Configuration Tab.** In the Onboarded™ Setup interface, click the **Object Configuration** tab (second tab from left). *This tab displays a list of Onboarded™ entities (Employee, Employer, Client, etc.) with object selectors for each.*
3. **Locate the Employee Entity Row.** Find the row labeled **"Employee"** in the entity list. This is typically the first row in the Object Configuration table.
4. **Click Edit Button.** Click the **Edit** button (pencil icon) next to the Employee object dropdown. This unlocks the dropdown for editing.
5. **Select "Account" from Dropdown.** Click the Salesforce Object dropdown (now enabled) and select **"Account"** from the list of available objects.
> **Why Account?** Person Accounts are stored in the Account object with `IsPersonAccount = true`. Selecting "Account" tells the application to query Account records for Employee data.
6. **Person Account Detection Modal Appears.** After selecting "Account", the application automatically detects that Person Accounts are enabled in your org and displays a modal dialog asking:
> "Person Accounts are available in your org. Would you like to map Employees to Person Accounts?"
  - **Yes:** Configure Employee to use Person Account fields (PersonEmail, PersonPhone, etc.)
  - **No:** Keep Employee mapped to standard Business Account fields
**What This Modal Means:**
  - The application detected `IsPersonAccount` field exists on Account object
  - You selected "Account" for Employee, which could mean either Business Accounts or Person Accounts
  - This modal clarifies which type of Account records you want to use for Employees
7. **Click "Yes" to Enable Person Account Mode.** Click the **"Yes"** button in the modal to confirm you want to use Person Accounts for Employees.
**What Happens When You Click Yes:**
  1. The application saves `Employee Object = "Person Account"` in `OnboardedSettings__c`
  2. The dropdown display changes to show **"Person Account"** (not "Account")
  3. When querying Employees, the application adds `WHERE IsPersonAccount = true` to filter only Person Account records
  4. Field mappings now expect Person Account field names (`PersonEmail`, `PersonPhone`, etc.)
8. **Click Save Button.** Click the **Save** button (checkmark icon) next to the Employee dropdown to persist your Person Account configuration.
9. **Update Field Mappings for Person Account Fields.** Navigate to the **Field Mapping** tab and update Employee field mappings to use Person Account field names:
| Onboarded™ Field | Person Account Field (Use This) | Contact Field (Don't Use) |
|  --- | --- | --- |
| `first_name` | `FirstName` | `Contact.FirstName` |
| `last_name` | `LastName` | `Contact.LastName` |
| `email` | `PersonEmail` | `Contact.Email` |
| `phone` | `Phone` or `PersonMobilePhone` | `Contact.Phone` |
| `updated_at` | `Account.Last_Onboarded_Sync__c` | N/A |
> **Field Name Differences:** Person Account fields are on the Account object, not Contact. Key differences:
  - `PersonEmail` (not `Email`)
  - `PersonMobilePhone` (not `MobilePhone`)
  - `PersonMailingStreet` (not `MailingStreet`)
  - All person-specific fields have "Person" prefix


## Person Account Query Behavior

When you configure Employee to use Person Accounts, the application adjusts its SOQL queries as follows:

**Standard Contact Query (NOT Person Account Mode):**


```sql
SELECT FirstName, LastName, Email
FROM Contact
WHERE Onboarded_Id__c = '123'
```

**Person Account Query (Person Account Mode Enabled):**


```sql
SELECT FirstName, LastName, PersonEmail
FROM Account
WHERE Onboarded_Id__c = '123' AND IsPersonAccount = true
```

**Key Differences:**

- Query targets `Account` object (not Contact)
- Uses Person Account field names (`PersonEmail` not `Email`)
- Includes `IsPersonAccount = true` filter to exclude Business Accounts
- Returns only Person Account records, not Business Accounts


## Person Account Scenarios

### Person Accounts Disabled in Org

**What Happens:**

- The `IsPersonAccount` field does not exist on Account object
- Application detection method returns `false`
- "Person Account" option does NOT appear in Employee object dropdown
- Selecting "Account" for Employee maps to Business Accounts only
- No Person Account modal will appear


**Recommended Action:** Use Contact object for Employees instead of Account.

### Person Accounts Enabled, Employees on Contact

**What Happens:**

- Application detects Person Accounts are enabled (option available)
- You choose to map Employee to `Contact` object instead of Account
- No Person Account modal appears (only triggers when Account is selected)
- Employee data syncs to/from Contact records as normal


**Use This When:** Your org has Person Accounts enabled, but you want to keep employee data in Contact records separate from Account structure.

### Account Mapping with "No" Selected

**What Happens:**

- Application detects Person Accounts and shows modal
- You click "No" in the Person Account modal
- Employee object saved as `"Account"` (not "Person Account")
- Queries will include ALL Account records (Business + Person)
- You must manually filter Person Accounts if needed


**Use This When:** You want to use Business Accounts for Employees (uncommon scenario).

### Account Mapping with "Yes" Selected

**What Happens:**

- Application detects Person Accounts and shows modal
- You click "Yes" in the Person Account modal
- Employee object saved as `"Person Account"`
- Queries automatically filter `IsPersonAccount = true`
- Only Person Account records are synced for Employees
- You must use Person Account field names in field mappings


**Use This When:** Your org uses Person Accounts to represent individual employees (most common Person Account scenario).

## Person Account Troubleshooting

### "Person Account" Option Missing from Dropdown

**Cause:** Person Accounts are not enabled in your Salesforce org, or the application cannot detect the `IsPersonAccount` field.

**Solutions:**

1. Verify Person Accounts are enabled: Setup → Account Settings → Enable Person Accounts
2. Confirm you have a B2C or Person Account license
3. Refresh the Onboarded™ Setup tab after enabling Person Accounts
4. Check user permissions: Ensure Onboarded™ Admin permission set is assigned


### Business Accounts for Employees

**Cause:** Application detected Person Accounts but you want to use Business Accounts for Employee records (uncommon use case).

**Solutions:**

- Click "No" in the Person Account modal
- Use standard Account field names (no "Person" prefix)
- Be aware that queries will return ALL Account records unless filtered manually


**Better Alternative:** Use Contact object for Employees instead of Account to avoid confusion.

### "Field Not Found" Errors After Enabling Person Account Mode

**Cause:** Field mappings still reference Contact field names instead of Person Account field names.

**Solutions:**

1. Navigate to Field Mapping tab
2. Update all Employee field mappings to use Person Account field names:
  - Change `Email` to `PersonEmail`
  - Change `MobilePhone` to `PersonMobilePhone`
  - Change `MailingStreet` to `PersonMailingStreet`
  - Use `FirstName` and `LastName` (no Person prefix needed)
3. Save field mappings
4. Test sync with "Sync Now" button


> **Pro Tip:** After configuring Person Account mode, always test with a single record first. Use the "Sync Now" button on an Employee record page to validate field mappings before running scheduled sync jobs. This helps catch field name mismatches early.