Introduction to Import Data Transformation

Introduction to Import Data Transformation

Sometimes, the data in your source file isn't in the exact structure or format that your forms require. Data Transformation is an optional but powerful step in the import process that allows you to clean, restructure, and manipulate your source data before it gets imported.

This feature is essential for complex imports and is required when using JSON or XML files. It gives you complete control to reshape your data to meet any requirement.

The Transformation Editor

You'll build your transformation in the Import Processing Editor. This tool is designed to make writing the necessary XSLT 1.0 code much easier by visualizing your source data and providing shortcuts to generate code.

The editor shows your source data structure on the right, allowing you to click buttons to automatically insert loops, values, and conditional logic into the code editor on the left.

The Transformation Workflow

The transformation process uses a standard web technology called XSLT (Extensible Stylesheet Language Transformations). Even if you're not familiar with XSLT, the workflow is straightforward:
  1. Initial Conversion to XML: The system first takes your source file—whether it's a CSV, JSON, or XML file—and converts it into a standardized, intermediate XML format.
  2. Your Transformation is Applied: The system then applies your custom XSLT stylesheet to this intermediate XML. Your stylesheet contains a set of rules that tell the system how to change the XML structure.
  3. Final XML is Produced: The output of your transformation is a final XML file structured in the exact format the Import Module requires for processing.
This final, clean XML is then used for caching, matching, and importing into your forms.

What Can You Do with Transformations?

Data transformations can solve a wide range of common data problems:
  1. Restructure Data: Change the layout of your source data, such as converting nested JSON or XML into the flat structure needed for import.
  2. Clean Data: Correct inconsistencies, such as reformatting dates, trimming extra spaces, or changing text to uppercase.
  3. Combine Fields: Concatenate multiple source columns into a single target column (e.g., combining {FirstName} and {LastName} into {FullName}).
  4. Split a Field: Split a single source column into multiple target columns (e.g., splitting {FullName} into {FirstName} and {LastName}).
  5. Combine Rows: Consolidate multiple source rows into a single row in the final output.
  6. Split a Row: Split a single source row into multiple rows in the final output.
  7. Use Conditional Logic: Apply if/then logic to route data to different target columns based on the value of another field (e.g., if {ContactType} is "Home", map a number to the {HomePhone} column).
  8. Create Repeater Data: Loop through nested data to create the <instance> nodes required for repeater imports.

Next Steps

Before you can write a transformation, you need to know what the intermediate and final XML structures look like. The next article provides a detailed guide with clear examples of these formats.


    • Related Articles

    • Advanced Mapping: Importing Data into Repeaters

      A repeater allows a section of your form to be duplicated, which is perfect for lists of information like emergency contacts. This guide explains how to map data from your import file to the fields inside a repeater. Before you begin, ensure your ...

    • Advanced Mapping: Using Indexed Expressions

      While repeaters handle lists of data that can grow or shrink, sometimes you have a fixed number of related entries to import into separate, static sections of a form. A common example is importing contact information into predefined "Guardian 1" and ...

    • An Introduction to XSLT

      XSLT 1.0 (Extensible Stylesheet Language Transformations) is a versatile language designed for transforming XML data from one structure to another, supporting formats like CSV, JSON, and XML. As a core part of the W3C’s XML family of technologies, ...

    • Import Transformation Patterns (XSLT)

      This article provides practical, ready-to-use XSLT 1.0 code for the most common data manipulation tasks. Each pattern is presented in a separate section. Within each section, you'll find tabs explaining the Goal, showing the Source XML you're ...

    • Import Error Code Reference

      When an import fails, the system will log an error code to help you diagnose the problem. This guide explains what each error code means and provides step-by-step instructions on how to resolve the issue. E0001: Cannot Read File Problem The system ...