Search documentation...

K

Overview

In Hightouch, Mapping refers to the establishment of a one-to-one relationship between a column or field in your model and a record's property or field in a destination. Depending on your sync’s destination, you can map your data with either the basic mapper, which does column-based mapping, or the advanced mapper, which gives the additional options of mapping with static values, with variables, or with Liquid templating.

Basic mapper

Column Mapping

Column in your sourceField in your destination
emailhs_email
first_namehs_firstName
last_namehs_lastName
company_namehs_company
With the basic mapper, you tell Hightouch which columns in your source should get fed into which fields in your destination. In column mapping, it is expected that every row has different values for each column.
Click ‘suggest mappings’ to auto-complete a column-based mapping based on column and field titles. Auto-completion works by searching for matching and near matching column and field titles. You should confirm that the auto-completion has made the correct selections:
Suggest Mappings

Advanced Mapper

For destinations where the Advanced Mapper is enabled, you have the additional capability to create mappings that include a static value, a sync-based variable value, or complex values using the Liquid templating language. We are in the process of rolling out our Advanced Mapper to all existing destinations, and any new destinations will automatically be released with this new capability. Please let our CS team know if there’s a specific destination or use case that is a high priority for you to leverage this!

Static Mapping

With static mapping, you can specify a constant value to include in the mapping. Select ‘static value’, the value’s data type, and enter the value in the field provided. Click ‘apply’.
Static Mapping
In this example, we are mapping the string ‘EMEA’ to the ‘region’ field in our destination. ‘EMEA’ will be inserted into every record’s ‘region’ field:
Static Mapping

Variable Mapping

With variable mapping, you can include a variable with meta-data about your sync and send it to a field in your destination. Select ‘variable value’, the variable you would like to include, and click ‘apply’:
Variable Mapping
In this example, we are mapping the current time to the ‘Time sent’ field in our destination. An ISO timestamp (YYYY-MM-DD) will be inserted into every record’s ‘Time sent’ field:
Variable Mapping

Template Mapping

With template mapping, you can create more complex mappings using our library of Liquid-inspired functions as well as standard functions of the Liquid templating language. Please visit Liquid's documentation for more information on usage.
Select ‘template’, then select a variable and a function. The function's code will automatically appear in the editor window:
Template Mapping
In this example, we are checking if a row’s ‘last_name’ column includes the string ‘Stark’. If it does, the row is processed. If it doesn’t, the row is rejected.

Liquid Templating

The template mapper can also implement all of Liquid’s regular functionality (see the Liquid Reference), beyond the Liquid-inspired functions we have provided for you in the UI.
Variables follow this format:
{{ row['company'] }}
The double-handlebars enclose a Liquid snippet that is generating output. The name of the column should go in between the single quotes inside the square brackets (akin to array field notation).
Functions follow this format:
{{ row['last_name'] | includes : 'Stark' }}
A single pipe comes after the variable, then the name of the function and any necessary parameters. See the Liquid Reference or Liquid Cheatsheet for a full list of available functions.

Liquid Variables in the Advanced Mapper

$ <column_name>
$ Model Name
$ Timestamp
All of the model’s column names will have a corresponding variable. You also have access to a variable for the name of the model and the timestamp for the sync’s run:
Template Mapping

Liquid-Inspired Functions in the Advanced Mapper

FunctionSyntaxDescription
base64_decoderow['email']|b64_decodeBase64 decode input
base64_encoderow['email']|b64_encodeBase64 encode input
castrow['phone']|cast:'string'Cast input to specified type. Allowable types are ‘string’, ‘number’, ‘boolean’
includesrow[‘last_name’]|includes:‘Stark’Check input for a substring. Row will be rejected if substring is not found
parserow['first_name']|parseParse input and construct JSON object
regex_replacerow['last_name']|regex_replace: '<[a-zA-Z]>', '<replacement>'Search and replace substrings of input using RegEx
regex_testrow['last_name']|regex_test: '<[a-zA-Z]>'Check input for a RegEx match. Row will be rejected if no match is found using RegEx
sha256row['email']|sha256Hash input using SHA-256
sha512row['email']|sha512Hash input using SHA-512
to_daterow[‘dob’]|to_dateParse input and return a Date object (ISO 8601 format)
to_unixrow[‘date_sent’]|to_unixConvert input to Unix time
validate_emailrow['email']|validate_emailReject emails that are not RFC 2822 compliant email addresses

Liquid Function Chaining

More than one Liquid function can be called on one input. Separate the functions with a single pipe:
Examples:
{{ row[‘full_name’] | camelcase | sha256 }}
{{ row['email'] | downcase | validate_email | sha256 }}

Extended Liquid and Use Cases

See the Liquid Reference or Liquid Cheatsheet for a full list of available functions.
Conditional Output
Use Liquid conditionals to specify output based on input. For example, this Liquid snippet
{% if row['title'] == "Awesome Shoes" %}
  These are awesome shoes!
{% elsif row['title'] == "Ugly Shoes" %}
  These are ugly shoes!
{% else %}
  No shoes selected!
{% endif %}
outputs the following result in the destination:
Liquid Conditional Output
Math Functions
Use the abs function to send an absolute value:
{{ row['value'] | abs }}
Use the round function to round a value to the nearest integer or specified number of decimals:
{{ row['value'] | round: 2 }}
String Functions
Use the capitalize function to capitalize the first letter of a string:
{{ row['title'] | capitalize }}
Use the strip function to remove all whitespace from the left and right sides of a string:
{{ row['title'] | strip }}
Use the append function to add a file extension to a string:
{{ row['file_name'] | append: '.png' }}

Template Mapping Use Cases

The Template Mapper is especially useful in situations where your chosen destination requires that your data be sent in a very specific format and you don't want to 'bake' this specificifity into your model.
  • Webflow requires slugs to not have any special characters. Use regex_replace to remove them.
  • Enable lead routing in your destination using Liquid conditionals without touching your central dbt model.
  • Validate emails for Mailchimp.

    Need help?

    Our team is relentlessly focused on your success. We're ready to jump on a call to help unblock you.

    • Connection issues with your data warehouse?
    • Confusing API responses from destination systems?
    • Unsupported destination objects or modes?
    • Help with complex SQL queries?

    or

    Feature Requests?

    If you see something that's missing from our app, let us know and we'll work with you to build it!

    We want to hear your suggestions for new sources, destinations, and other features that would help you activate your data.

On this page

OverviewBasic mapperColumn MappingAdvanced MapperStatic MappingVariable MappingTemplate MappingLiquid TemplatingLiquid Variables in the Advanced MapperLiquid-Inspired Functions in the Advanced MapperLiquid Function ChainingExtended Liquid and Use CasesTemplate Mapping Use Cases

Was this page helpful?