Understanding the Source and Target XML Formats

Understanding the Source and Target XML Formats

This guide explains the two critical data structures you need to know for any transformation: the system-generated source XML (your starting point) and the required target XML (your goal).

Understanding the Source and Target XML Formats

Every data transformation starts with one data structure (the source) and ends with another (the target). To write a successful transformation, you must understand both. This guide shows you what the system-generated source XML looks like for different file types and defines the exact target XML structure that the importer requires.

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.

As shown in the image, the editor has two main parts:
  1. The Code Editor (Left): This is where you'll write your XSLT stylesheet.
  2. The Side Panel (Right): This panel has two important tabs:
    1. Elements Tab: This is the default view. It displays your source XML as a browsable tree of nodes. You can use the buttons next to each node to quickly insert the necessary XSLT code (like loops and value selections) into your stylesheet, which greatly speeds up the process.
    2. Data Source Tab: This tab shows you the raw, intermediate source XML that was generated from your uploaded file. It's a useful view for confirming the exact structure you need to work with.

The Source XML (Your Starting Point)

After you upload a file, the system converts it into a standard XML format that your transformation can process. This is the structure you'll see in the Elements tree and in the Data Source tab.

For CSV/TSV Files

Each row in your file becomes a <row> element inside a <root>. Each cell in that row becomes an XML element named after its corresponding column header. Any spaces or special characters in the header are sanitized to comply with XML naming rules (e.g., "First Name" becomes FirstName).

Example CSV:
  1. StudentID,First Name
  2. 101,Jane
Becomes this Source XML:
  1. <root>
  2.   <row>
  3.     <StudentID>101</StudentID>
  4.     <FirstName>Jane</FirstName>
  5.   </row>
  6. </root>

For JSON Files

Your JSON file is converted into an XML structure inside a single <root> element. If you use the recommended structure of an array of objects, each object in the array becomes a child <element> node within the root.

Example JSON:
  1. [
  2.   { "StudentID": 101, "FirstName": "Jane" },
  3.   { "StudentID": 102, "FirstName": "John" }
  4. ]
Becomes this Source XML:
  1. <root>
  2.   <element>
  3.     <StudentID>101</StudentID>
  4.     <FirstName>Jane</FirstName>
  5.   </element>
  6.   <element>
  7.     <StudentID>102</StudentID>
  8.     <FirstName>John</FirstName>
  9.   </element>
  10. </root>

For XML Files

Your original XML file is used directly as the source, without any modification or wrapper elements.

The Target XML (Your Goal)

Your transformation stylesheet must convert the source XML into the following specific target format. This is the only structure the importer understands.

The structure is always: <importedData> → <row> → <column>
  1. <importedData>: The single root element of the final file.
  2. <row>: Represents a single record to be imported. There can be many <row> elements.
  3. <column>: Represents a single piece of data. It must have a header attribute whose value is the name you will use in your form mapping Expressions (e.g., {StudentIdentifier}).
Example of a valid Target XML:
  1. <importedData>
  2.   <row>
  3.     <column header="StudentIdentifier">101</column>
  4.     <column header="FullName">Jane Doe</column>
  5.   </row>
  6.   <row>
  7.     <column header="StudentIdentifier">102</column>
  8.     <column header="FullName">John Smith</column>
  9.   </row>
  10. </importedData>

Handling Repeaters in the Target XML

To populate a repeater on your form, the structure is slightly different. The <column> element for a repeater field must contain multiple child <instance> elements. Each <instance> tag will create one entry in the repeater.

Example Target XML for a Repeater:
This would populate a "Contacts" repeater with two instances.
  1. <importedData>
  2.   <row>
  3.     <column header="StudentIdentifier">101</column>
  4.     <column header="ContactName">
  5.       <instance>Maria Garcia</instance>
  6.       <instance>Luis Garcia</instance>
  7.     </column>
  8.     <column header="ContactPhone">
  9.       <instance>555-0101</instance>
  10.       <instance>555-0102</instance>
  11.     </column>
  12.   </row>
  13. </importedData>

Next Steps

Now that you know the starting and ending points for your transformation, you're ready to start writing the code.
  1. For practical, copy-and-paste solutions to common import scenarios, see the recipes guide.
    Next Article: Import Transformation Patterns (XSLT)
  2. For a general reference on syntax, functions, and best practices for writing XSLT, see our core documentation.
    Reference: Clevr XSLT

    • Related Articles

    • 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 ...

    • Viewing and Understanding the Import Cache

      Viewing the import cache is a powerful diagnostic technique that gives you a snapshot of your data at a critical point in the import process. The cache itself is a temporary storage area where the system holds your data after reading the source file ...

    • Preparing an XML File for Import

      XML (Extensible Markup Language) is a powerful format for handling complex or hierarchical data. Because XML files can have virtually any structure, they must go through a Data Transformation step to be processed by the Import Module. While any valid ...

    • 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 ...

    • Overview of the Import Process

      The Import Module is a powerful tool for bringing external data directly into your forms. It streamlines workflows, reduces manual entry, and enhances data accuracy by using structured files like CSV, TSV, XML, or JSON to automatically populate or ...