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 (always KaptioTravel__Trip__c) |
recordType | The RecordType DeveloperName to assign to the created Trip |
defaultStatus | The Trip status to set on creation (e.g. Enquiry) |
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.