Preparing Your CSV/TSV File for GDI Import

Preparing Your CSV/TSV File for GDI Import

A correctly formatted data file is essential for successful data imports using the Generic Data Import (GDI) module. While GDI uses standard CSV (Comma-Separated Values) or TSV (Tab-Separated Values) formats, adhering to specific formatting rules and Clevr requirements is crucial to avoid errors and ensure data integrity.

General File Structure

  1. Format: Your file must be a plain text file saved in either CSV (using commas "," as delimiters) or TSV (using tabs "\t " as delimiters) format. Be consistent with the delimiter throughout the file.
  2. Header Row: The very first line of your file must be a header row. Each column header name needs to be unique. These headers are used by GDI to map data, particularly the identifier column specified in your GDI configuration.
  3. Encoding: Use standard file encoding, preferably UTF-8, to ensure proper handling of all characters.
Identifier (ID) Column
  1. One column in your file must be designated as the identifier for matching records to people in Clevr (as defined in the ID Column Name and Match On settings of your GDI configuration).
  2. Crucially, the value in this ID column must be unique for each row in the file. Duplicate IDs will cause matching issues.

Data Formatting for Specific Field Types

Pay close attention to how data is formatted for import into different types of Clevr form fields:
  1. Date Fields (Datepickers):
    1. Dates in your file must exactly match the format specified in the Date Format setting of the corresponding GDI configuration. For instance, if the configured format is YYYY-MM-DD, your file must use values like 2025-04-15.
    2. Any date value that does not strictly adhere to the configured format will likely cause an error and fail to import for that field or record.
  2. Checkboxes:
    1. Importing into checkbox fields requires a specific structure: each individual checkbox option needs its own corresponding column in your CSV/TSV file.
    2. The only valid values for these checkbox columns are:
      1. "true" (if the box should be checked)
      2. "false" (if the box should be explicitly unchecked)
      3. "" (blank/empty string, typically interpreted as unchecked)
  3. Radio Button Groups:
    1. Similar to checkboxes, importing into radio button groups requires one column for each option within that radio button group.
    2. The key rule is that for any single record (row), only one of the columns corresponding to the options in a specific radio group can contain the value "true".
    3. All other columns for that same radio group in that same row must contain a blank value (""). Setting more than one option to "true" for the same group in a single row will likely result in an error.

Value Length Limit

Ensure that the data value within any single cell (intended for import into a form field) does not exceed 4000 characters in length. Values longer than this limit may be truncated or cause import errors.

Final Checks and Next Steps

Investing time to validate your prepared file against these requirements can prevent many common import errors, such as those related to matching or data processing that appear on the Import Dashboard. Consider using spreadsheet functions to verify unique IDs or opening the file in a basic text editor to spot any inconsistencies with delimiters or quoting, especially for CSV files. Testing with a small subset of your data first, perhaps using a manual One-Time Run, can also help confirm your formatting before processing a large file. Once you are confident in the file's integrity and adherence to these GDI-specific rules, you are ready to proceed to the next stage: Creating a New Generic Data Import (GDI) Configuration.

    • Related Articles

    • Generic Data Import - Resource List

      To help you get started and make the most of Generic Data Import (GDI), we offer a comprehensive set of resources. These articles cover everything from preparing your data files and basic setup to configuring advanced matching rules and flagging ...

    • Configuring Import Settings

      Setting up a Generic Data Import (GDI) configuration involves defining how Clevr should find, read, and process your data file, and how it should match the rows within that file to people in the system. Careful configuration ensures that data is ...

    • Quick Start Guide

      Welcome to the Quick Start Guide for Generic Data Import (GDI)! This guide will help you get up and running quickly with importing data into your forms. Our feature allows you to import data from CSV and TSV files, with customizable configurations ...

    • Creating a New Generic Data Import (GDI) Configuration

      Creating a new Generic Data Import (GDI) configuration in Clevr allows you to define how external data files are brought into the system. This process involves initiating the new configuration from the main module view, providing basic identifying ...

    • Understanding the GDI Import Dashboard

      The Import Dashboard acts as a landing page for the Import Module, providing a quick overview of applicable settings, an overview of errors and logs, and a list of bulk imports jobs executed in the last 30 days. At a glance, you should be able to ...