Overview

You can map columns to CleverTap user profiles or event data. CleverTap supports the following two mapping options:

• User Profile Data: Map user attributes such as email, first_name, or any custom attribute to CleverTap user properties.
• Event Data: Map event columns such as amount, category, or coupon_code to CleverTap events and event properties.

Use the toggle to switch between User Profile Data and Event Data mapping options.

Identity Field Validation Rules

Identity and CleverTap ID values cannot be undefined, null, na, n/a, 0, nil, -1, infinity, -infinity, inf, -inf, nan, -nan, empty, or xxxxxx, and cannot exceed 1024 characters.

User Profile Data

This section explains how user data is mapped and imported from your file into CleverTap.

The mapping of user profile data consists of the following two steps:

1. Map Identity
2. Map User Profile Properties

Map Identity

This step determines how incoming records are matched to user profiles, using either a unique Identity field (such as email, phone number, or user ID) or the system-generated CleverTap ID.

• Identity: A unique identifier, such as email, phone number, or custom ID, used to match profiles in CleverTap. When using Identity:
  • If a profile with the same identity already exists, CleverTap updates or adds properties to it.
  • If a matching profile is not available, CleverTap creates a new profile and captures properties to that profile.
• CleverTap ID: A system-generated unique identifier assigned to each user profile in CleverTap. When using CleverTap ID, and if a profile with the same CleverTap ID exists, CleverTap updates or adds properties to that profile.

  📘

  Note

  Choose Identity when you have a unique identifier, such as email or customer ID, to identify your users. Choose CleverTap ID only when your source data already contains CleverTap-assigned IDs.

  For a list of values that are not allowed for Identity or CleverTap ID, refer to Identity Field Validation Rules.

Map User Properties

To map user profile properties, perform the following steps:

1. Select a Column from your file that contains user-related information, such as email, name, Customer Type, or Wallet Balance.

2. Assign a User Property: Map the column to a corresponding CleverTap user property.

   • Select from available system properties (for example, name maps to Name).
   • If the desired property is not listed, enter a new name to create a custom property.

3. Select a Data Type: Use the table below to determine when and how each type should be used.

4. (Optional) Click Add Mapping to add additional column mappings as needed.

Event Data

Configure how event data is mapped and imported from your file into CleverTap. This setup ensures event records are accurately linked to user profiles, timestamped correctly, and enriched with event-specific properties.

The mapping process consists of the following four steps:

1. Map Identity
2. Define When Each Event Occurred
3. Choose How Events Are Named
4. Map Columns to Event Properties

Map Identity

This step specifies how incoming records are matched to user profiles, using either a unique Identity field (such as email, phone number, or user ID) or the system-generated CleverTap ID.

• Identity: A unique identifier, such as email, phone number, or custom ID, used to match profiles in CleverTap. When using Identity:
  • If a profile with the same identity already exists, CleverTap captures the event against that profile.
  • If a matching profile is not available, CleverTap creates a new profile and captures the event against that profile.
• CleverTap ID: A system-generated unique identifier assigned to each user profile in CleverTap. When using CleverTap ID:

  • If a profile with the same CleverTap ID exists, CleverTap captures the event against that profile.

    📘

    Note

    Choose Identity when you have a unique identifier, such as email or customer ID, to identify your users. Choose CleverTap ID only when your source data already contains CleverTap-assigned IDs.

    For a list of values that are not allowed for Identity or CleverTap ID, refer to Identity Field Validation Rules.

Define When Each Event Occurred (Created On Timestamp)

Use this field to specify when the event occurred. Select the column from your file that contains the event timestamp, and then select the corresponding date format. For supported formats, refer to Supported Date Formats.

Choose How Events Are Named

Specify how CleverTap should import different types of events, such as Add to chart , Coupon redeem , Lead captured , and others.

• Events from Column: Import different events using a column from your file that contains event names. Ideal when your file contains multiple event types.
• Specific Event: Assign a single static event name to all imported records. Select from existing CleverTap events or create a new one. Best for importing a consistent event type.

Map Columns to Event Properties

This step maps file columns to CleverTap event properties, providing context and detail to each event.

1. Select a Column: Choose a column from your file with event-related details, such as category, price, or transactionID.

2. Enter Event Property: Assign a name for the corresponding event property. You can use existing property names or enter new ones to create custom event properties.

3. Select Data Type: Use the table below to determine when and how each type should be used.

4. (Optional) Click Add Mapping to add additional column mappings as needed.

Supported Date Formats

You can select from the following date format patterns when mapping Date-type fields and configuring the Created On timestamp for event data. These formats apply to date values inside your file columns, not the timestamp in the file name. For file-name timestamp formats, refer to the Review Supported Date-Time Formats section in Create Import.

Perform Dry Run (Recommended)

After completing the mapping step, click Perform Dry Run. The system validates your configuration against a random sample and displays detailed results.

Dry Run Results

After the dry run completes, your mapping validation results are displayed in two panels.

The left panel provides a detailed row-by-row breakdown of each mapped field and its validation status.

The right panel shows the overall validation summary and indicates whether the mapping is ready to proceed or requires corrections.

Validation Outcomes

After mapping data fields from your file to CleverTap, the system runs a validation check to assess configuration accuracy, data quality, and identity alignment. The outcomes are categorized as follows:

• Successful Validation (Green): Indicates that the mapping is correctly configured and ready for import.
• Error Detection (Red): Indicates that the mapping contains issues that must be resolved before proceeding. Common causes include:
  • Invalid data types or formatting issues.
  • Identity/CleverTap ID validation failures.
  • System property validation errors (for example, Email or Phone format issues).
  • Prohibited characters in property names or event names.
  • Date format mismatches.

Click Done to return to the mapping screen and fix the identified issues.

Sync User Profile and Event Data (Optional)

Syncing user profiles and event data lets you push a selected random sample of data from your file to CleverTap. This is useful when you want to verify that data will be correctly captured in your CleverTap instance.

What happens when you sync:

• User profiles: If a profile with the same identity exists, properties are updated. If not, a new profile is created.
• Events: Events are captured against matching user profiles.

After you complete the mapping and validate it with a Dry Run, your import job is ready to be scheduled. To continue setting up your import, refer to Schedule Import to configure repeat intervals, custom schedules, or manual triggering for the import job.

Best Practices for Mapping

When configuring import mapping in CleverTap, keep the following best practices in mind:

• Validate Data Upfront: Clean and verify your data before import. Ensure email addresses are well-formed, phone numbers are correctly formatted, and date values are consistent to avoid errors during the Dry Run.
• Consistent Formats: Keep date and time formats uniform across your files. Ensure the format of your date columns matches the format you select in CleverTap. Inconsistent formats will cause parsing errors.
• Leverage Dry Runs: Always run the Dry Run before the actual import. This catches mapping issues early so you can fix them without affecting live data.
• Limit Data to What Is Needed: Import only the columns you want in CleverTap. Avoid mapping extraneous fields or properties. This makes the process faster and reduces risk.
• Naming Conventions: Use consistent names for properties and events. Avoid special characters in property keys. CleverTap does not allow the characters in property names: %, <, >, !, |, &, :, ;, $, ', ", \, #.
• Segmentation of Data: Consider filtering your data to exclude obsolete or inactive users and events before import. This keeps your CleverTap instance clean and focused on relevant data.

Next Steps

After you configure the import, CleverTap saves the import job, and you can view and manage all import jobs from the Import Center.

• Schedule the import. For more information, refer to Schedule Import.