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