Introduction to field mapping

The field mapping API allows you to map fields between your product and ours and generate or update contact records without touching the database.

To retrieve all the fields which can be mapped by calling the following function.

<?php 
$fields = \Groundhogg\get_mappable_fields();

// Returns
// [
// 'first_name' => 'First Name',
// 'last_name' => 'Last Name',
// 'email' => 'Email',
// ...
// ]
?><br>

This will return a list of key => name pairs where the key is the field in Groundhogg and the value is the pretty name of the field, this makes it so you can use these keys in a select element.

Standard Meta Fields

List of standard meta fields.

lead_source
source_page
page_source
terms_agreement
terms_agreement_date
gdpr_consent
gdpr_consent_date
primary_phone
primary_phone_extension
street_address_1
street_address_2
time_zone
city
postal_zip
region
country
notes
files
company_name
company_address
job_title
ip_address
last_optin
last_sent
country_name
region_code<br>

Generate contacts with a mapping

You will want to generate or update contacts using the field mapping API for a variety of reasons to avoid unneeded code and extraneous time spent debugging.

Let’s say you have an array of data which the keys of which do not match up to any existing fields in Groundhogg.

<?php 
$data = [
  'fname' => 'John',
  'lname' => 'Doe',
  'email_address' => 'john.doe@gmail.com'
  'birthday' => '1997'
  'gender' => 'male'
];
?><br>

None of the above fields exist anywhere in Groundhogg, but we can map them to fields that do exist.

<?php 
$map = [
  'fname' => 'first_name',
  'lname' => 'last_name',
  'email' => 'email',
  'birthday' => 'meta'
  'gender' => 'tags'
];
?><br>

Above we mapped the generic details to the database fields we know exist, and we have also mapped birthday to the metadata and mapped their gender to a tag to be applied!

Now we actually have to generate our contact.

<?php 

$data = [
  'fname' => 'John',
  'lname' => 'Doe',
  'email_address' => 'john.doe@gmail.com'
  'birthday' => '1997'
  'gender' => 'male'
];

$map = [
  'fname' => 'first_name',
  'lname' => 'last_name',
  'email' => 'email',
  'birthday' => 'meta'
  'gender' => 'tags'
];

$contact = \Groundhogg\generate_contact_with_map( $data, $map );

if ( ! $contact ){
  return false;
}

?>