# Field Mapping

Field mappings define how data flows between the Onboarded™ API and Salesforce fields. The application comes with pre-configured mappings that you can customize.

## Field Mapping Properties

Each field mapping defines:

| Property | Purpose | Example |
|  --- | --- | --- |
| Onboarded™ Object | The entity type in Onboarded™ | Employee, Employer, Task |
| Onboarded™ API Field | The field name in Onboarded's API | `first_name`, `email`, `ssn` |
| Salesforce Field | The target field in Salesforce | `FirstName`, `Email__c`, `SSN__c` |
| Field Type | Data type for proper conversion | Text, Date, Boolean, Number |
| Sync Direction | Which direction data flows | Inbound, Outbound, Bidirectional |
| Data Authority | Conflict resolution rule | See below |


## Sync Direction Options

### Inbound

Data flows from Onboarded™ to Salesforce only. This mapping is used during GET operations when fetching data from the Onboarded™ API.

**Use Case:** Most standard sync scenarios where Onboarded™ is the source of truth.

### Outbound

Data flows from Salesforce to Onboarded™ only. This mapping is used during POST/PUT/PATCH operations.

**Use Case:** When you want to push Salesforce data changes back to Onboarded™.

### Bidirectional

Data can flow in both directions. The mapping is used for both inbound and outbound operations.

**Use Case:** Fields that should stay synchronized regardless of where changes originate.

## Data Authority Rules

### Salesforce Controlled

Onboarded™ can only populate this field on initial record creation. Subsequent updates from Onboarded™ are blocked. Salesforce is the authoritative source.

**Use Case:** Fields you want to manage exclusively in Salesforce after initial sync.

### Onboarded™ Controlled

Onboarded™ always wins. Every sync will overwrite the Salesforce value, including setting it to null if Onboarded™ sends null.

**Use Case:** Fields where Onboarded™ is the system of record (e.g., task status, form completion).

### Salesforce Wins by Default

If the Salesforce field already has a value, it's preserved. Onboarded™ can only populate empty/null fields.

**Use Case:** Fields where you may have enriched data in Salesforce that shouldn't be overwritten.

### Onboarded™ Wins by Default

If Onboarded™ sends a non-null value, it overwrites Salesforce. Onboarded null values do NOT clear Salesforce data.

**Use Case:** Most standard data fields where Onboarded™ should update but not delete existing data.

## Field Writeability Errors and Warnings

The Field Mapper displays all Salesforce fields in the dropdown, including fields that are not writeable (such as formula fields, auto-number fields, and read-only fields). This is intentional — these fields may play a key role in **Outbound** sync operations where data is sent from Salesforce to your Onboarded™ account.

When mapping Onboarded™ fields to Salesforce for **Inbound** or **Bidirectional** sync operations, the application automatically checks whether the selected Salesforce field can receive data. Error and warning prompts are displayed to ensure you are aware when a mapping configuration will be problematic.

### Errors vs. Warnings

- **Error:** Indicates a configuration that would cause data loss or sync failures. **The mapping cannot be saved** until the configuration is changed.
- **Warning:** Indicates a configuration that may have limitations but is allowed. The mapping can be saved after acknowledging the limitation.


| Field Type | Indicator | Field Characteristic | Impact |
|  --- | --- | --- | --- |
| **Formula Field** | Error | Field value is calculated by a formula | Cannot receive inbound data; formula overwrites any value. *Save is blocked.* |
| **Auto-Number Field** | Error | Field value is system-generated | Cannot receive inbound data; system assigns value automatically. *Save is blocked.* |
| **Read-Only Field** | Error | Field is not createable or updateable | Cannot be written to by the application. *Save is blocked.* |
| **Create-Only Field** | Warning | Field can only be set during record creation | Works for new records, but updates will not modify this field. *Save is allowed.* |


> **Why are non-writeable fields available?** Fields like formula fields and auto-number fields are included in the dropdown because they may contain valuable data for **Outbound** sync operations. For example, you might want to send a calculated commission amount or an auto-generated employee ID to your Onboarded™ account.


> **Note:** Errors and warnings only appear when the Sync Direction is set to **Inbound** or **Bidirectional**, as these are the operations that write to Salesforce. **Outbound** mappings only read from Salesforce fields, so no writeability validation is needed.


## Field Mapping Management

Use the **Onboarded™ Setup** interface to manage field mappings:

1. Navigate to the **Onboarded™ Setup** tab
2. Click on **Field Mappings**
3. Review existing mappings or create new ones
4. Configure the mapping properties as needed
5. Save your changes


> **Pro Tip:** Reference the Onboarded™ API documentation at `https://app.onboarded.com/api/v1/openapi.json` to see all available API fields for mapping.


## Create Mapping for Inbound Sync

> **Important:** The **Create Mapping** button is only visible when **Enable Salesforce Record Creation** is turned on for the Onboarded™ object. This feature is specifically designed for inbound API operations where Onboarded™ data is being created in Salesforce.


### Create Mapping Overview

The Create Mapping feature allows you to configure **preset inbound values** for Salesforce fields that are required for successful record creation but may not be provided by the Onboarded™ API. This is essential for satisfying:

- **Required Fields:** Salesforce fields marked as required that have no corresponding Onboarded™ field
- **Validation Rules:** Fields that must contain specific values to pass validation rules
- **Record Types:** Assigning specific record types to records created from Onboarded™ data
- **Picklist Values:** Setting default picklist selections for categorization
- **Lookup Fields:** Populating lookups to parent records (e.g., default Account for all Contacts)


### When to Use Create Mapping

**Use Create Mapping when:**

1. You've enabled Salesforce Record Creation for an Onboarded™ object
2. Your Salesforce object has required fields or validation rules
3. The Onboarded™ API does not provide all the data needed to satisfy your org's data requirements
4. You need to set constant values for categorization, routing, or business logic


**Common Scenarios:**

| Scenario | Field to Map | Value to Set | Reason |
|  --- | --- | --- | --- |
| Record Type Assignment | `RecordTypeId` | Employer Record Type Label | Ensure all Employer Accounts use the "Employer" record type |
| Validation Rule | `Account.Type` | "Customer" | Validation rule requires Type to be set on Account creation |
| Required Picklist | `Contact.LeadSource` | "Onboarded™ Integration" | LeadSource is required but not provided by Onboarded™ API |
| Checkbox Default | `Employee__c.Active__c` | TRUE | Mark all newly synced employees as active |
| Owner Assignment | `OwnerId` | Integration User ID | Assign all records to a specific user or queue |


### Walkthrough — Employer Account Record Type

**Business Requirement:** Your Salesforce org uses the standard Account object for both Customers and Employers. You have a custom "Employer" record type that must be assigned to all Accounts created from Onboarded™ Employer data to ensure the correct page layout, picklist values, and business processes are applied.

1. **Configure Object Mapping.** In **Onboarded™ Setup** → **Object Configuration**, map the Employer object to the standard `Account` object and save.
2. **Enable Salesforce Record Creation.** In the Employer configuration section, toggle **Enable Salesforce Record Creation** to **Enabled**. This will reveal the "Salesforce Inbound" accordion section in the Field Mappings area.
> **Why This Matters:** The Create Mapping button only appears within the "Salesforce Inbound" section, which is only visible when record creation is enabled. Without this setting, you won't see the option to create preset value mappings.
3. **Navigate to Field Mappings Tab.** Click the **Field Mappings** tab in the Onboarded™ Setup interface and locate the **Employer** section.
4. **Open the Salesforce Inbound Accordion.** Expand the **"Salesforce Inbound"** accordion section. You should see a **Create Mapping** button at the top of this section.
5. **Click Create Mapping.** A modal dialog will appear with the following options:
  - **Source Type:** Choose between "Map from Onboarded™ API Field" or "Set Constant Value"
  - **Salesforce Field:** Dropdown listing all available fields on the Account object
  - **Value Input:** Text input for entering the constant value (only visible when "Set Constant Value" is selected)
6. **Select "Set Constant Value".** Choose the **"Set Constant Value"** radio button. This tells the application that you want to hardcode a specific value for a Salesforce field rather than mapping it from an Onboarded™ API field.
7. **Select RecordTypeId Field.** In the **Salesforce Field** dropdown, select `RecordTypeId`.
> **Special Behavior for Record Types:** When you select `RecordTypeId`, a checkbox labeled **"Use Record Type Label Instead of ID"** appears. This is highly recommended because Record Type IDs differ between Salesforce orgs (sandbox vs production), but labels remain consistent.
8. **Enable "Use Record Type Label".** Check the **"Use Record Type Label Instead of ID"** checkbox. The value input field label changes to **"Record Type Label"**.
9. **Enter the Record Type Label.** In the **Record Type Label** field, type `Employer` (or whatever your record type is named).
> **Pro Tip:** Record Type Labels are case-sensitive and must match exactly. To verify your record type label:
  1. Go to Setup → Object Manager → Account → Record Types
  2. Find your Employer record type and copy the exact label
  3. Paste it into the field (do not type manually to avoid typos)
10. **Save the Mapping.** Click **Save**. The modal closes and your new inbound mapping appears in the "Salesforce Inbound" section with:
  - **Onboarded™ API Fields:** Shows "CONSTANT_VALUE" (no API field mapped)
  - **Sync Operation:** Automatically set to "Inbound"
  - **Salesforce Fields:** Shows "RecordTypeId"
  - **Data Authority:** Set to "Salesforce Controlled" (cannot be updated from Onboarded™)
11. **Test Record Creation.** Create a test Employer in Onboarded™ or trigger a manual sync. Verify that the newly created Account in Salesforce has the correct record type assigned by checking the Account detail page or running this SOQL query:

```sql
SELECT Id, Name, RecordType.Name
FROM Account
WHERE Onboarded_Employer_Id__c != null
LIMIT 10
```
The `RecordType.Name` field should display "Employer" for all Accounts synced from Onboarded™.


### How Create Mapping Works

When the Onboarded™ sync process encounters a Create operation for an Employer:

1. **Standard Field Mappings Applied:** The sync process maps Onboarded™ API fields (name, address, phone, etc.) to their corresponding Salesforce fields based on your Bidirectional and Inbound field mappings.
2. **Inbound-Only Mappings Applied:** The sync process applies any Create Mapping entries marked as "Salesforce Inbound".
3. **Record Type Resolution:** If you used "Record Type Label", the application queries Salesforce for the Record Type ID matching that label for the Account object:

```sql
SELECT Id FROM RecordType
WHERE SObjectType = 'Account'
AND DeveloperName = 'Employer'
LIMIT 1
```
4. **Record Created:** The Account record is inserted with all mapped fields AND the RecordTypeId populated.
5. **Data Authority Enforced:** Because the mapping is set to "Salesforce Controlled", future sync operations will NOT overwrite the RecordTypeId — it's set once on Create and never changed by Onboarded™.


### Create Mapping Troubleshooting

#### Create Mapping Button Not Visible

**Cause:** The "Enable Salesforce Record Creation" toggle is not turned on for this Onboarded™ object.

**Solution:**

1. Navigate to Onboarded™ Setup → Field Mappings
2. Find the Onboarded™ object you're configuring
3. Look for the "Enable Salesforce Record Creation" toggle above the field mapping accordions
4. Toggle it to "Enabled"
5. The "Salesforce Inbound" accordion section will appear with the "Create Mapping" button


#### Record Type Not Being Applied

**Possible Causes:**

- Record Type Label is misspelled or case doesn't match
- Record Type is not assigned to the integration user's profile
- Record Type has been deactivated


**Solution:**

1. Verify the exact Record Type Label in Setup → Object Manager → [Object] → Record Types
2. Check that the integration user's profile has access to the record type
3. Check sync error logs (`Onboarded_Error_Log__c`) for specific error messages
4. If using Record Type ID instead of Label, verify the ID is correct for this org (IDs differ between sandbox and production)


#### Validation Rule Still Failing

**Cause:** The constant value you set doesn't satisfy the validation rule's criteria.

**Solution:**

1. Review the validation rule in Setup → Object Manager → [Object] → Validation Rules
2. Understand the exact criteria (formula logic, picklist values accepted, etc.)
3. Update your Create Mapping constant value to satisfy the validation rule
4. Test with a manual sync to verify the rule passes


**Example:** If the validation rule requires `Account.Type` to be either "Customer" or "Partner", ensure your constant value exactly matches one of these picklist options (case-sensitive).

#### Inbound Mapping Cannot Be Deleted

Inbound-only mappings created via the "Create Mapping" button CAN be deleted (you'll see a delete icon next to the mapping row). If you don't see the delete button:

- The mapping might be in the wrong accordion section (Bidirectional or Outbound sections don't allow deletion)
- You might be trying to delete a standard mapping that came with the package (only custom inbound mappings can be deleted)


## Authorized Until Enrichment (I-9, Optional)

When an HR user clicks the Employer Task button on an I-9 task in the Employee Onboarded or Workflow Onboarded component, the application can opportunistically write the latest Work Authorization Expiration date from Onboarded™ to a Date field on your Task object.

To enable this enrichment, add a Field Mapping to your Task object with:

- **Onboarded API Field:** `authorized_until`
- **Salesforce Object:** your Task object
- **Salesforce Field:** a Date field on your Task object that will store the expiration date
- **Sync Direction:** Inbound (or Bidirectional)


If both Object and Field are populated, the application reads `form.alien_authorized_until` from the task's fields endpoint and writes it to your mapped Date field when the user opens an I-9 employer task. If either side is blank, the enrichment silently no-ops. Failures are recorded in the Onboarded™ Error Log.

## State and Country Code Handling

Salesforce and the Onboarded™ API use different standards for country codes. The Onboarded™ application automatically handles conversion between these formats to ensure seamless data synchronization.

| System | Standard | Format | Examples |
|  --- | --- | --- | --- |
| Salesforce | ISO 3166-1 alpha-2 | 2 characters | `US`, `CA`, `GB`, `DE`, `FR` |
| Onboarded™ API | ISO 3166-1 alpha-3 | 3 characters | `USA`, `CAN`, `GBR`, `DEU`, `FRA` |


### State and Country Picklists in Salesforce

Salesforce offers an optional feature called **State and Country/Territory Picklists** that restricts address fields to standardized ISO values. When enabled:

- Country fields only accept valid ISO 3166-1 alpha-2 codes (e.g., `US`, not `USA` or `United States`)
- State/Province fields only accept valid subdivision codes for the selected country
- Invalid values cause DML errors with the message: `INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST`


> **Auto-Detection:** During package installation, Onboarded™ automatically detects whether your org has State and Country Picklists enabled by checking for the `BillingCountryCode` field on the Account object. If detected, the `Country_Code_Enabled__c` setting is automatically set to `true`.


### Country Code Conversion

#### Inbound Sync (Onboarded™ → Salesforce)

Country code conversion is **always applied** for inbound data, regardless of the `Country_Code_Enabled__c` setting. This ensures that country codes from the Onboarded™ API are converted to the format Salesforce expects.

- `USA` → `US`
- `CAN` → `CA`
- `GBR` → `GB`
- Valid 2-character codes pass through unchanged
- Invalid/unrecognized codes are excluded from the update to prevent errors


#### Outbound Sync (Salesforce → Onboarded™)

Country code conversion for outbound data is controlled by the `Country_Code_Enabled__c` setting:

- **When enabled:** Salesforce alpha-2 codes are converted to alpha-3 for the API (`US` → `USA`)
- **When disabled:** Country codes are passed through as-is (for orgs not using State and Country Picklists)


### Address Field Requirements

When syncing address data to the Onboarded™ API, the following fields are recognized as address components and are automatically nested under the `address` object:

| API Field | Required for Outbound | Description |
|  --- | --- | --- |
| `street` | Required | Primary street address |
| `secondary` | Optional | Apartment, suite, unit number |
| `city` | Required | City name |
| `state` | Required | State or province code |
| `zip` | Required | Postal/ZIP code |
| `country` | Required | Country code (converted automatically) |
| `full_address` | Optional | Complete formatted address string |


> **Important:** For outbound API calls, if ANY of the required address fields (`street`, `city`, `state`, `zip`, `country`) are missing or blank, the entire address object is excluded from the request. This prevents partial address data from being sent to the API.


### Configuration Verification

1. **Check if State and Country Picklists are Enabled.** Navigate to **Setup** → search for **"State and Country/Territory Picklists"**. If enabled, you'll see configuration options for managing picklist values.
2. **Verify the Country Code Setting.** Check the `Country_Code_Enabled__c` value in your Onboarded Settings:

```sql
SELECT Country_Code_Enabled__c FROM OnboardedSettings__c
```
This should be `true` if your org has State and Country Picklists enabled.
3. **Test with a Sync Operation.** Perform a manual sync on a record with address data and verify the country codes are correctly converted in both directions.


### State and Country Code Q&A

#### `INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST` Error

**Cause:** Your Salesforce org has State and Country Picklists enabled, but an incoming country code from Onboarded™ couldn't be converted to a valid ISO alpha-2 format.

**Common Scenarios:**

- The Onboarded™ data contains a full country name (e.g., "United States") instead of a code
- The country code is misspelled or uses a non-standard format
- The country is not recognized in the ISO 3166-1 standard


**Solution:**

1. Check the error log (`Onboarded_Error_Log__c`) for the specific country value that failed
2. Correct the data in Onboarded™ to use a valid country code (e.g., `USA` or `US`)
3. Re-sync the record


#### Country Codes Not Being Converted

**Cause:** The `Country_Code_Enabled__c` setting may not be configured correctly.

**Solution:**

1. Query your settings: `SELECT Country_Code_Enabled__c FROM OnboardedSettings__c`
2. If the value is `false` but your org has State and Country Picklists enabled, update the setting:

```apex
OnboardedSettings__c settings = OnboardedSettings__c.getOrgDefaults();
settings.Country_Code_Enabled__c = true;
update settings;
```
3. Re-test your sync operations


**Note:** Inbound conversion (Onboarded™ → Salesforce) always applies regardless of this setting to prevent picklist errors.

#### Address Data Not Syncing to Onboarded™

**Cause:** One or more required address fields are missing or blank.

**Required Fields:** `street`, `city`, `state`, `zip`, `country`

**Solution:**

1. Verify all required address fields have values in the Salesforce record
2. Check your field mappings to ensure all address fields are mapped correctly
3. If partial addresses are intentional, note that the entire address object will be excluded from outbound API calls


#### State Codes Being Rejected

**Cause:** When State and Country Picklists are enabled, state/province values must match the configured picklist values for the selected country.

**Solution:**

1. Navigate to **Setup** → **State and Country/Territory Picklists**
2. Select the country in question
3. Verify the state/province code exists in the picklist (e.g., `CA` for California, `ON` for Ontario)
4. If the state code from Onboarded™ doesn't match, you may need to:
  - Add the missing state code to your Salesforce picklist, or
  - Correct the data in Onboarded™ to use the expected code


#### Supported Country Codes

The Onboarded™ application supports all countries defined in the **ISO 3166-1** standard. This includes:

- 249 countries and territories with alpha-2 codes (2 characters)
- 249 corresponding alpha-3 codes (3 characters)


**Common Examples:**

| Country | Alpha-2 (Salesforce) | Alpha-3 (Onboarded API) |
|  --- | --- | --- |
| United States | `US` | `USA` |
| Canada | `CA` | `CAN` |
| United Kingdom | `GB` | `GBR` |
| Germany | `DE` | `DEU` |
| France | `FR` | `FRA` |
| Australia | `AU` | `AUS` |
| Mexico | `MX` | `MEX` |
| Japan | `JP` | `JPN` |


For a complete list, refer to the [ISO 3166-1 standard](https://www.iso.org/iso-3166-country-codes.html).

#### Orgs Without State and Country Picklists

**Short Answer:** Mostly no, but inbound conversion still applies.

**Details:**

- If your org uses free-text address fields, country values like `USA`, `US`, or `United States` will all be accepted
- However, inbound sync will still convert `USA` to `US` for consistency
- Outbound sync will pass country values as-is (no conversion) when `Country_Code_Enabled__c` is `false`


**Recommendation:** Even without State and Country Picklists enabled, using standardized ISO codes provides cleaner data and ensures compatibility if you enable the feature in the future.