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.

Each field mapping defines:

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.

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™.

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.

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™ 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).

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.

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.

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.

• 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.

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.

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.

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.

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)

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:

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:

    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™.

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:

   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™.

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

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)

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

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.

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.

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

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)

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

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.

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:

   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.

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

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:

   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.

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

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

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:

For a complete list, refer to the ISO 3166-1 standard.

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.