trip-mapping.yaml reference

trip-mapping.yaml defines the contract between webform field keys and Salesforce field API names. It lives at tenants/{tenant}/webforms/trip-mapping.yaml in the configuration repository.

Structure

version: "1.0"

target:
  salesforceObject: KaptioTravel__Trip__c
  recordType: Qualification
  defaultStatus: Enquiry

mappings:
  - salesforceField: Ready_To_Book__c
    webformKey: readyToBook
    type: picklist

  - salesforceField: Best_Time_To_Call__c
    webformKey: bestTimeToCall
    type: picklist

  - salesforceField: Travel_Year_Other__c
    webformKey: travelYearOther
    type: text
    populateWhen: "travelYear == 'Other'"

Target

Field	Description
`salesforceObject`	The Salesforce object to create. Default `KaptioTravel__Trip__c` (Trip-direct intake); set to `Lead` or a custom object for two-stage intake — see Choosing your intake object
`recordType`	The RecordType DeveloperName to assign to the created record
`defaultStatus`	The status to set on creation (e.g. `Enquiry`)

Capturing to Lead or a custom object

For two-stage intake, point the target at your enquiry object and map form keys to its fields:

target:
  salesforceObject: Lead
  defaultStatus: New

mappings:
  - salesforceField: FirstName
    webformKey: firstName
    type: text
  - salesforceField: LastName
    webformKey: lastName
    type: text
  - salesforceField: Email
    webformKey: email
    type: text
  - salesforceField: Company
    webformKey: travelAgencyName    # empty for direct guests
    type: text

Validation, field mapping, and picklist resolution work identically for any target. The Trip-specific stages — dedup rules, capture-time Person Account matching, and scoring writeback — apply to Trip capture; in two-stage intake the equivalent protection happens at conversion time in the Trip conversion guide.

Mapping entries

Each entry maps one webform field to one Salesforce field.

Field	Description
`salesforceField`	The Salesforce field API name (e.g. `Ready_To_Book__c`)
`webformKey`	The key name in the webform JSON payload (e.g. `readyToBook`)
`type`	Field type: `text`, `picklist`, `checkbox`, `number`, `longText`
`valueMap`	Optional. A map of form values to Salesforce values for picklists (e.g. `{ "2-3-months": "2-3 months" }`)
`populateWhen`	Optional. A condition that must be true for this field to be populated (e.g. `"travelYear == 'Other'"`)
`source`	Optional. Set to `intelligence` for fields written by the scoring engine rather than the form

Picklist resolution

For type: picklist fields, the intake service fetches the Salesforce org's actual picklist values at runtime and matches the submitted value:

Exact match on picklist value
Exact match on picklist label
Fuzzy match (case-insensitive, underscore-to-space normalization)
If no match and the picklist is restricted, the submission proceeds but a warning is logged

Static valueMap overrides take precedence over dynamic picklist resolution.

Intelligence writeback fields

Fields with source: intelligence are not populated from the form. They are written by the scoring engine when intelligence.enabled: true:

  - salesforceField: Enquiry_Priority_Tier__c
    webformKey: _intelligence_tier
    type: text
    source: intelligence

These fields do not need to exist in the Salesforce org unless intelligence is enabled for the tenant.

Structure​

Target​

Capturing to Lead or a custom object​

Mapping entries​

Picklist resolution​

Intelligence writeback fields​