Field mapping

> Requires: Fundations Pro

Field mapping connects Fundations data to external integration fields. When you configure an automation rule or integration, you define pairs of source values (using merge tags) and destination field names in the external service.

Why use this

Every CRM and marketing tool uses different field names. Field mapping lets you control exactly which Fundations data gets sent where, regardless of naming differences between systems.

What it does

The field mapper (Get_Fund_Field_Mapper) processes merge tags at the moment a trigger fires. It replaces each {tag_name} placeholder in a mapping source with the actual value from the current event context, then sends the resolved values to the target integration.

Merge tags use single curly braces: {tag_name}. This is different from some templating systems that use double braces.

Value handling

• Booleans are converted to '0' or '1'.
• Arrays are joined with commas.
• Numeric values are cast to strings.
• Empty values pass through as empty strings.

There is no currency formatting, date conversion, or field-combining transformation layer. If you need formatted values, process them in the receiving system.

How to use it

Field mappings are configured inside each automation rule or integration.

1. Open a rule in Fundations → Integrations.
2. In the field mapping section, add a row for each field you want to send.
3. In the Source column, enter a merge tag such as {donor_email} or a combination like {donor_first_name} {donor_last_name}.
4. In the Destination column, enter the field name used by the external service (for example EMAIL for Mailchimp or email for a webhook payload).
5. Repeat for all fields you need.
6. Save the rule.

Settings & options

Each mapping row has two fields:

Field	Description
Source	Merge tag(s) or static text to send. You can combine multiple tags: {donor_first_name} {donor_last_name}
Destination	The field name in the target system

What you can and cannot do

• You can combine multiple merge tags in a single source field.
• You can mix static text with merge tags: Donation from {action_title}.
• You cannot apply transformations such as currency formatting or date reformatting in the mapper itself.
• Not all merge tags are available for all triggers. Using a tag that is not available for the chosen trigger results in an empty value being sent. See the Merge Tags reference for trigger availability.
• Custom donation form fields are available as merge tags when using the donation_received trigger, provided the Form Builder class has registered them.

Troubleshooting

A mapped field arrives empty at the CRM. The merge tag may not be available for the trigger you are using. Check the trigger-to-group availability table in Merge Tags. Also confirm the data actually exists on the donation or action (for example, {message} is empty if the donor left the message field blank).

Tags are not being replaced. Confirm you are using single curly braces {tag_name}, not double braces {{tag_name}}. Tags with typos or unsupported names are left as-is (no replacement occurs).

Developer reference

Adding custom merge tags

// Register additional merge tags available in the field mapper
add_filter( 'get_fund_integration_merge_tags', function( $merge_tags ) {
    $merge_tags['custom']['fields'][] = array(
        'key'   => 'my_custom_field',
        'label' => 'My Custom Field',
    );
    return $merge_tags;
} );

The get_fund_integration_merge_tags filter is also used by the Form Builder class to register custom donation form field values as merge tags automatically.

Modifying trigger data before mapping

// Add data to the payload before the field mapper processes it
add_filter( 'get_fund_integration_trigger_data', function( $data, $trigger, $object_id ) {
    $data['my_custom_value'] = get_option( 'my_option' );
    return $data;
}, 10, 3 );

See Merge Tags for the complete list of built-in tags and their groups.