Custom Field Mapping Guide

Standard fields like name, email, and phone cover the basics, but most businesses rely on custom fields for data unique to their workflows. This guide covers how to sync custom properties between platforms in FluxCascade.

What Are Custom Fields?

Custom fields are user-defined properties that extend a platform's default data model:

• HubSpot: Custom contact/deal properties
• Jobber: Custom fields on clients, jobs, and quotes
• Pipedrive: Custom person/deal fields
• Salesforce: Custom fields on any object

Examples: lead source, service type, equipment model, preferred contact method, contract number.

Step 1: Inventory Your Custom Fields

Before mapping, list the custom fields on both sides:

Finding Custom Fields

HubSpot:

1. Settings → Properties → Contact (or Deal) properties
2. Filter to "Custom properties"
3. Note the internal name (e.g., service_type)

Jobber:

1. Settings → Custom Fields
2. Note the field key and type (text, dropdown, etc.)

Pipedrive:

1. Settings → Data Fields → Person (or Deal)
2. Note the API key (e.g., abc123_service_type)

Salesforce:

1. Setup → Object Manager → [Object] → Fields
2. Custom fields end with __c (e.g., Service_Type__c)

Create a Mapping Plan

Step 2: Map Text Fields

Text-to-text mappings are straightforward:

1. In your mapping's Field Pairs, click Add Field Pair
2. Select the custom source field from the dropdown
3. Select the custom target field
4. Optionally add transforms (trim, uppercase, etc.)

FluxCascade auto-discovers custom fields from both platforms when you load the mapping editor. If a newly created field doesn't appear, click Refresh Fields to re-fetch the schema.

Step 3: Map Dropdown / Picklist Fields

Dropdowns require value mapping because option labels rarely match between platforms:

Example: Service Type

HubSpot options: "HVAC Install", "HVAC Repair", "Plumbing", "Electrical"

Jobber options: "Installation - HVAC", "Repair - HVAC", "Plumbing Service", "Electrical Service"

Configure a value_map transform:

Transform: value_map

Mappings:
  "HVAC Install"  → "Installation - HVAC"
  "HVAC Repair"   → "Repair - HVAC"
  "Plumbing"      → "Plumbing Service"
  "Electrical"    → "Electrical Service"

Default: "General Service"

Always set a default. New options added to the source after your mapping is configured will fall through to the default instead of causing errors.

Bidirectional Picklists

For bidirectional sync, you need value maps in both directions. FluxCascade automatically generates the reverse mapping when you configure the forward direction, but review it to make sure the reverse makes sense.

Step 4: Handle Multi-Select Fields

Multi-select fields (checkboxes, tag lists) need special handling because platforms store them differently:

HubSpot: Semicolon-separated string: "HVAC;Plumbing;Electrical"

Salesforce: Semicolon-separated string: "HVAC;Plumbing;Electrical"

Jobber: Stored as comma-separated text or individual fields

Same Delimiter → Direct Mapping

If both platforms use the same format, no transform is needed.

Different Delimiters

Use the value_map transform with the entire multi-select string, or map to a text field and accept the delimiter as-is.

Multi-Select to Text

When the target doesn't support multi-select, concatenate into a readable text field:

Source: "HVAC;Plumbing;Electrical"
Transform: replace(";", ", ")
Target: "HVAC, Plumbing, Electrical"

Step 5: Map Number and Currency Fields

Number fields are generally compatible across platforms, but watch for:

Currency Formatting

Source: "$1,500.00" (formatted string)
Target expects: 1500.00 (raw number)

Transform: number_parse

Units and Precision

Some platforms store values in cents, others in dollars:

Source (Stripe): 150000 (cents)
Target (HubSpot): 1500.00 (dollars)

Transform: divide(100)

Step 6: Map Date Fields

Custom date fields may use different formats:

Source: "03/22/2026" (US format)
Target: "2026-03-22" (ISO 8601)

Transform: date_iso

See Field Transformations for all date transforms.

Step 7: Map Boolean / Checkbox Fields

Different platforms represent true/false differently:

Use boolean_to_string or value_map to convert between representations.

Working with Cross-Reference Fields

A common pattern is storing external IDs as custom fields for reliable record matching:

Setup

1. Create a custom text field in both systems:

   • HubSpot: jobber_client_id (text property)
   • Jobber: hubspot_contact_id (custom text field)

2. Map the record ID to the custom field:

   • HubSpot vid → Jobber hubspot_contact_id
   • Jobber id → HubSpot jobber_client_id

3. Use these fields as secondary matching criteria

This is especially useful for multi-platform sync where email alone may not be sufficient.

Troubleshooting

Custom Field Not Appearing in Mapping Editor

Cause: Field was created after FluxCascade loaded the schema

Solution: Click Refresh Fields in the mapping editor to re-fetch available fields

Value Map Returns Default for Known Values

Cause: Source value doesn't exactly match the mapping (whitespace, case, encoding)

Solution: Add trim and lowercase transforms before the value_map, and ensure mapping keys match the trimmed/lowercased values

Multi-Select Values Partially Syncing

Cause: Delimiter mismatch or character limit on target field

Solution: Check the target field's maximum length. For long multi-select values, consider mapping to a text area or notes field instead

Custom Field Data Lost After Sync

Cause: Mapping direction is overwriting target data

Solution: For fields that should be independently maintained, use one-way sync or exclude the field from the mapping

Best Practices

1. Document your custom field mappings — Use mapping descriptions to note why each custom field is mapped

2. Start with essential custom fields — Add more after verifying the basics work

3. Always set value_map defaults — Source systems evolve; new dropdown options shouldn't break syncs

4. Test with real data — Custom fields often have inconsistent data quality; run a test sync first

5. Keep field names consistent — When creating new custom fields for cross-referencing, use a naming convention like {platform}_id

6. Review after platform updates — When you add new custom fields or options in a source system, update your FluxCascade mappings accordingly

Next Steps

• Field Transformations — All available transforms including value_map details
• Creating Mappings — Mapping fundamentals
• Bidirectional Sync — Handle two-way custom field sync