Before you start

Things you need to know:

You must first understand how to import basic person data.
Learn more in Import person data.

Extended person data sets

You can import any fields you want into person.extend along with the following top-level person fields:

person.n - full name
person.fn - first name
person.ln - last name

For example, you could import something that you know about the individual to person.extend.favorite_color:

email                                firstname   lastname   favorite_color
test.test@triggeredmessaging.com     Joe         Bloggs     orange

To make this import correctly, you must use a channel with a field mapping like this:

{
  "email": {
    "ftp_field_name": "email"
  },
  "person.fn": {
    "ftp_field_name": "firstname"
  },
  "person.ln": {
    "ftp_field_name": "lastname"
  },
  "person.extend.favorite_color": {
    "ftp_field_name": "favorite_color"
  }
}

As a more sophisticated import example, you can also import JSON structures, for example:

A list of values within a field

email                                 my_field
test.test@triggeredmessaging.com      ["cars","bikes"]

A dictionary of fields and values within a field

email                                 my_field
test.test@triggeredmessaging.com      {"cars":"two","bikes":"three"}

To make this import correctly, you would need to use a channel with a field mapping like this:

{
  "email": {
    "ftp_field_name": "email"
  },
  "person.extend.my_field": {
    "ftp_field_name": "my_field",
    "field_type": "json"
  }
}

Customer groups for multiple price books

Requires the B2B module.

A customer group is a code which defines which set of prices are seen by each person.

Several prices are imported for the products, for example:

Base price:£26.99
- groupA: £23.99
- groupB: £24.99
- groupC: £25.99

These prices are imported into the product, and a corresponding code is imported to the field person.cg, to tell the system that that person should see the price for their customer group.

For example:

email                  firstname  lastname  favorite_color  customer_group
test.test@example.com  Joe        Bloggs    orange          VIP

To make this import correctly, you must use a channel with a field mapping like this:

{
    "email":{"ftp_field_name":"email"},
    "person.fn":{"ftp_field_name":"firstname"},
    "person.ln":{"ftp_field_name":"lastname"},
    "person.extend.favorite_color":{"ftp_field_name":"favorite_color"}
    "person.cg":{"ftp_field_name":"customer_group"}
}

Assign a SmartBlock to imported people records

To use the Show Assigned SmartBlock rule in Slots, you must upload SmartBlock IDs formatted like this:

EmailAddress               test-slot-1    test-slot-2
test.test@example.com      xlkjl3         oiuklj3

To make this import correctly, you must use a channel with a field mapping like this:

{
  "email": {
    "ftp_field_name": "EmailAddress"
  },
  "person.content.keys.test-slot-1": {
    "ftp_field_name": "test-slot-1"
  },
  "person.content.keys.test-slot-2": {
    "ftp_field_name": "test-slot-2"
  }
}

Import a fixed value for every person

Fixed values can be imported using the val attribute in the field mapping.

Here’s an example of a field mapping which sets every imported person to have ex.imported set to yes:

{
  "email": {
    "ftp_field_name": "EmailAddress"
  },
  "person.extend.imported": {
    "val": "yes"
  }
}

Import location data

You can upload a visitor’s location for use by location-based Slot rules. This can provide more accurate locations for your known customers.

Location upload requires either:

The postal / zip code and the country code.
The country code must be a two letter upper case ISO 3166-1 Alpha-2 country code, for example GB, FR, US, AU.

The visitor's latitude and longitude.

Example CSV file

EmailAddress,Country,Postcode
test_uk@example.com,GB,SW1A 1AA
test_us@example.com,US,20500

To make this import correctly, you must set the channel's import field mapping to:

{
  "email": {
    "ftp_field_name": "EmailAddress"
  },
  "location": {
    "location_type": "postcode",
    "country_code_field_name": "Country",
    "postcode_field_name": "Postcode"
  }
}

Example CSV file that would import the location for two shoppers using latitude and longitude

EmailAddress,latitude,longitude
test_uk@example.com,-1.4304542541503906,50.962339396267446
test_us@example.com,-0.07894277572631836,51.50027116593512

To make this import correctly, you must set the channel's import field mapping to:

{
  "email": {
    "ftp_field_name": "EmailAddress"
  },
  "location": {
    "location_type": "latlng",
    "latitude_field_name": "latitude",
    "longitude_field_name": "longitude"
  }
}

By default, the imported location data is used by Slot rules for 1,000 days. You can use IP-based geolocation, when available, in Slot rules, or change how long the imported location can be used, under Location Settings.

Learn more in Use Geotargeting.

Import location data from your location sets

Location IDs, for example, a store, region or airport, from within a location set can be associated with a visitor based on an import.

The nearest location within the set is picked, up to a configurable maximum distance, or based on a defined region around the location. This could be useful to pick, for example, the nearest store to each shopper, unless they are more than 20km away from a store.

Supplying the location you want to add from a location set allows you to import a fixed location ID for customers, for example, if you know which their preferred store is - even if it’s not the geographically nearest location.

Example CSV file

EmailAddress,Country,Postcode,local_store_country,local_store_postcode
test_uk@example.com,GB,SW1A 1AA,GB,SE1 3JB

To make this import correctly, you must set the channel's import field mapping to:

{
  "email": {
    "ftp_field_name": "EmailAddress"
  },
  "location_ids": {
    "location_type": "postcode",
    "country_code_field_name": "local_store_country",
    "postcode_field_name": "local_store_postcode",
    "location_sets": "template:uk-cities|mystores",
    "list_separator": "|",
    "max_distance": 10000
  },
  "location": {
    "location_type": "postcode",
    "country_code_field_name": "Country",
    "postcode_field_name": "Postcode"
  }
}

Example CSV file that would import additional location IDs as well as the visitor's location for using latitude and longitude

EmailAddress,latitude,longitude,local_store_latitude,local_store_longitude
test_uk@example.com,-1.4304542541503906,50.962339396267446,-0.07894277572631836,51.50027116593512

To make this import correctly, you must set the channel's import field mapping to:

{
  "email": {
    "ftp_field_name": "EmailAddress"
  },
  "location_ids": {
    "location_type": "latlng",
    "latitude_field_name": "local_store_latitude",
    "longitude_field_name": "local_store_longitude",
    "location_sets": "template:uk-cities|mystores",
    "list_separator": "|",
    "max_distance": 10000
  },
  "location": {
    "location_type": "latlng",
    "country_code_field_name": "latitude",
    "postcode_field_name": "longitude"
  }
}

Example CSV file that would import additional locations by providing the location IDs

email,id,first_name,gender,discounted,store
test17815a@example.com,11111,Jim,m,20%,southampton

To make this import correctly, you must set the channel's import field mapping to:

{
  "email": {
    "ftp_field_name": "EmailAddress"
  },
  "location_ids": {
    "mapped_location_sets": {
      "mystores": "store"
    }
  },
  "location": {
    "location_type": "latlng",
    "country_code_field_name": "latitude",
    "postcode_field_name": "longitude"
  }
}

Using mapped_location_sets takes preference and overwrites any resolved values; latLng or postcode.

Import a wishlist with a person import

The wishlist data source shows products that the current person has added to their wishlist on another system. The wishlist is then imported into Fresh Relevance and is stored in the field person.extend.wishlist.

The import is driven by a person import file which contains a JSON structure containing product IDs along with quantities and date added.

Here's an example of a wishlist structure for one person, containing two products that they have on their wishlist. It must be imported into the field person.extend.wishlist, and the product IDs must match with the product IDs in the Fresh Relevance database.

{
  "product_id1": {
    "qty": 1,
    "dt": "2014-01-01T12:13:14Z"
  },
  "product_id2": {
    "qty": 1,
    "dt": "2014-01-01T12:13:14Z"
  }
}

An example field mapping for import might be:

{
  "email": {
    "ftp_field_name": "email"
  },
  "person.extend.wishlist": {
    "ftp_field_name": "wishlist_data"
  }
}

An example CSV import file, for one person, might look something like this:

email                         wishlist_data
first.last@example.com        {"prid1": {"qty": 1, "dt": "2014-01-01T12:13:14Z"},"prid2": {"qty": 1, "dt": "2014-01-01T12:13:14Z"}}

Wishlist structure with variants

It’s also possible to import an SKU-level product variant into a wishlist by adding the variant's ID in the vid field:

{
  "product_id1": {
    "vid": "small",
    "qty": 1,
    "dt": "2014-01-01T12:13:14Z"
  },
  "product_id2": {
    "vid": "medium",
    "qty": 2,
    "dt": "2014-01-01T12:15:14Z"
  }
}

To add multiple variants of the same product you can also include an array of different variants to add:

{
  "product_id1": [
    {
      "vid": "small",
      "qty": 1,
      "dt": "2014-01-01T12:13:14Z"
    },
    {
      "vid": "medium",
      "qty": 2,
      "dt": "2014-01-01T12:15:14Z"
    }
  ]
}