When a file-based import writes JSON or XML files, define each file's structure with a handlebars template. This article is for builders who send records to FTP, SFTP, Amazon S3, Azure Blob Storage, or Google Cloud Storage and need control over the file's structure - for example, a single JSON array for an API, JSON Lines for a data lake, or a well-formed XML document for a trading partner.
This article explains how integrator.io combines pages of records into files, which template pattern produces each file structure, and what template warnings or errors mean.
Prerequisites
- A flow with an export and a file-based import
- A working connection to the file-based destination
- Permission to edit the flow
Consider existing JSON or XML file imports
Keep the following points in mind for existing JSON or XML imports that use handlebars templates:
- For JSON and XML templates that generate one file per page of records, an
{{#each}}loop and a footer are now optional. - Templates that already wrap a JSON array or XML root around an
{{#each}}block will continue to work. You do not need to change them. - If you had added a placeholder footer such as
{{myfakefooter}}so the flow would run, you can now delete it. Leaving it in place doesn't break the file. - You must still type
[and]in your template if you want a JSON array. integrator.io does not add them. - Before October 27, 2026, a template without an
{{#each}}loop failed every record with the error{{# each data}} not found in the template(error codexml_template_parsing_error, shown with Source: Internal) orfooter not found in the template. Since October 27, 2026, integrator.io does not fail the run in either case. Instead, it evaluates the template and writes the output. A missing{{#each}}block shows a warning on the template field. XML with One file per flow run and no{{#each}}block shows an error on the field.
Configure new JSON or XML file imports
To set up JSON or XML file generation on the import step of your flow,
- On the Home page, select your integration, and then your flow.
- In the flow builder, select the file-based import step.
-
In the Edit transfer form, under How would you like to generate files? set File type to JSON or XML.
- In How many files would you like to generate?, select One file per flow run or One file per page of records.
- In the JSON document or the XML document field, enter the handlebars template.
- JSON document: The template is optional. If you leave it blank, integrator.io writes the mapped records as a JSON array.
-
XML document: The template is required. For One file per flow run, it must also include an
{{#each}}block. Without it, this field shows an error. You can still save and run. integrator.io writes the template once per page, so the file contains more than one root element.
- Select Preview to check the output.
- Select Save.
Preview uses one sample page of records and doesn't upload a file. Use Preview to check the structure of one page of output. Preview does not combine pages, so a template that previews fine can still write a different file when the flow runs: a comma at each page boundary, several summaries joined by commas, or XML with more than one root element. A run uploads to the real destination, so point the import at a test folder or destination first.
Combine pages and generate files for imports
integrator.io sends records to an import in pages. A page is a batch of records, and the export's page size (Advanced → Pages) sets how many records each page holds. The import's How many files would you like to generate? setting decides what happens to those pages - if you select:
- One file per flow run - integrator.io combines all pages into one file.
- One file per page of records - integrator.io writes each page as a separate file and doesn't combine them.
integrator.io renders your template once per file, against the page's list of records, not against a single record. Each record's fields are under record, for example {{record.orderId}}.
integrator.io splits your JSON or XML template into three parts: a header, a loop, and a footer. For One file per flow run, it writes the header and footer once for the whole file. For One file per page of records, it writes them once in each file:
| Part | Where it is in the template | When it's written |
|---|---|---|
| Header | Everything before {{#each}}
|
Once, at the start of the file |
| Loop |
{{#each batch_of_records}} ... {{/each}} (XML also accepts {{#each data}}) |
Once per page. Inside that page, {{#each}} writes one output per record. |
| Footer | Everything after {{/each}}
|
Once, at the end of the file |
Outside the {{#each}} loop there is no record. In the header and footer, {{record.orderId}} and a bare {{orderId}} render empty. To use record values, put them inside the loop. To use page-level values, use batch_of_records, for example {{batch_of_records.length}}.
- JSON templates read only
{{#each batch_of_records}}.{{#each data}}isn't supported for JSON. An{{#each}}block is optional for JSON. - XML templates accept
{{#each batch_of_records}}or the older{{#each data}}. Withbatch_of_records, reference fields as{{record.orderId}}. Withdata, the record itself is the item, so reference fields directly, for example{{orderId}}. XML templates that generate one file per flow run must include an{{#each}}block.
When integrator.io combines pages into one file, it joins JSON pages with a comma and concatenates XML pages with no separator.
If the template has no {{#each}} loop at all, integrator.io writes the whole template once for each page. With One file per flow run, it joins those results in the same way. With One file per page of records, each page is written as its own file.
Sample data used in this article
Every example in this article uses the same five orders, split into three pages with a page size of 2:
- SO-1042 and SO-1043 on page 1
- SO-1044 and SO-1045 on page 2
- SO-1046 on page 3
| Order | Customer | SKU | Qty | Total |
|---|---|---|---|---|
| SO-1042 | Northwind Outfitters | JKT-NAVY | 2 | 249.5 |
| SO-1043 | Blue Harbor Co | HAT-OLIVE | 1 | 88 |
| SO-1044 | Cedar & Pine | BOOT-8 | 1 | 412.1 |
| SO-1045 | Sequoia Trading | GLOVE-M | 3 | 54.75 |
| SO-1046 | Harborview Supply | BAG-CANVAS | 1 | 132 |
Each item in batch_of_records has this structure. Reference a field in your template as record.<field>, for example record.orderId.
{
"record": {
"orderId": "SO-1042",
"customer": "Northwind Outfitters",
"sku": "JKT-NAVY",
"qty": 2,
"total": 249.5
}
}Line breaks in the output examples are added for readability. The exact whitespace in your file depends on your template.
Choose the required template pattern for your import
Choose a template pattern based on the file structure your destination expects.
| Destination expects | Use this pattern | Works with |
|---|---|---|
| A single JSON array | Write a JSON array | Both file-count settings |
| One JSON object per line (JSON Lines) | Write JSON Lines | One file per page of records |
| A summary with no per-record output | Write a summary without a loop | One file per page of records |
| A well-formed XML document | Write an XML document | Both file-count settings |
Write a JSON array
To write a valid JSON array, wrap the {{#each}} loop in a header and footer that include [ and ]. This is the most common pattern, and existing templates that use it keep working.
{
"orders": [
{{#each batch_of_records}}
{{{jsonSerialize record}}}{{#unless @last}},{{/unless}}
{{/each}}
]
}This template has three parts:
-
Header:
{ "orders": [is written once, at the start of the file. -
Loop:
{{#each batch_of_records}} ... {{/each}}runs once for each record in the page. Inside the loop,recordis the current record.{{{jsonSerialize record}}}writes it as a JSON object. Use triple braces so the JSON is written as is. Double braces can escape characters, such as quotation marks, and break the JSON.{{#unless @last}},{{/unless}}adds a comma after every record except the last one in the page. -
Footer:
] }is written once, at the end of the file.
With One file per flow run, integrator.io adds the commas between pages for you. The outputs below are formatted for readability. jsonSerialize writes each object on a single line.
One file per flow run produces one file:
{
"orders": [
{
"orderId": "SO-1042",
"customer": "Northwind Outfitters",
"sku": "JKT-NAVY",
"qty": 2,
"total": 249.5
},
{
"orderId": "SO-1043",
"customer": "Blue Harbor Co",
"sku": "HAT-OLIVE",
"qty": 1,
"total": 88
},
{
"orderId": "SO-1044",
"customer": "Cedar & Pine",
"sku": "BOOT-8",
"qty": 1,
"total": 412.1
},
{
"orderId": "SO-1045",
"customer": "Sequoia Trading",
"sku": "GLOVE-M",
"qty": 3,
"total": 54.75
},
{
"orderId": "SO-1046",
"customer": "Harborview Supply",
"sku": "BAG-CANVAS",
"qty": 1,
"total": 132
}
]
}The commas after SO-1043 and SO-1045 mark the two page boundaries. integrator.io adds them automatically, so the result is one valid array regardless of how many pages the run has.
One file per page of records produces three files, each a complete, valid array:
orders-1.json
{
"orders": [
{
"orderId": "SO-1042",
"customer": "Northwind Outfitters",
"sku": "JKT-NAVY",
"qty": 2,
"total": 249.5
},
{
"orderId": "SO-1043",
"customer": "Blue Harbor Co",
"sku": "HAT-OLIVE",
"qty": 1,
"total": 88
}
]
}orders-2.json
{
"orders": [
{
"orderId": "SO-1044",
"customer": "Cedar & Pine",
"sku": "BOOT-8",
"qty": 1,
"total": 412.1
},
{
"orderId": "SO-1045",
"customer": "Sequoia Trading",
"sku": "GLOVE-M",
"qty": 3,
"total": 54.75
}
]
}orders-3.json
{
"orders": [
{
"orderId": "SO-1046",
"customer": "Harborview Supply",
"sku": "BAG-CANVAS",
"qty": 1,
"total": 132
}
]
}integrator.io doesn't show a warning for this template with either file-count setting.
Write JSON Lines
JSON Lines writes one JSON object per line with no surrounding array. Use it when the destination, such as a data lake or Snowflake stage, expects JSON Lines. The template contains only the loop, with nothing before {{#each}} and nothing after {{/each}}:
{{#each batch_of_records}}
{{{jsonSerialize record}}} {{/each}}integrator.io doesn't wrap the output in [ ] and doesn't treat this template differently when it joins pages. The result depends on the How many files would you like to generate? setting.
One file per page of records produces clean JSON Lines with no extra characters:
orders-1.json
{"orderId":"SO-1042","customer":"Northwind Outfitters","sku":"JKT-NAVY","qty":2,"total":249.5}
{"orderId":"SO-1043","customer":"Blue Harbor Co","sku":"HAT-OLIVE","qty":1,"total":88}orders-2.json
{"orderId":"SO-1044","customer":"Cedar & Pine","sku":"BOOT-8","qty":1,"total":412.1}
{"orderId":"SO-1045","customer":"Sequoia Trading","sku":"GLOVE-M","qty":3,"total":54.75}orders-3.json
{"orderId":"SO-1046","customer":"Harborview Supply","sku":"BAG-CANVAS","qty":1,"total":132}One file per flow run joins the pages with a comma, the same as every other JSON template. The comma is written at each page boundary, directly before the first record of the next page:
{"orderId":"SO-1042","customer":"Northwind Outfitters","sku":"JKT-NAVY","qty":2,"total":249.5}
{"orderId":"SO-1043","customer":"Blue Harbor Co","sku":"HAT-OLIVE","qty":1,"total":88}
,{"orderId":"SO-1044","customer":"Cedar & Pine","sku":"BOOT-8","qty":1,"total":412.1}
{"orderId":"SO-1045","customer":"Sequoia Trading","sku":"GLOVE-M","qty":3,"total":54.75}
,{"orderId":"SO-1046","customer":"Harborview Supply","sku":"BAG-CANVAS","qty":1,"total":132}Because of the commas before SO-1044 and SO-1046, this output is neither a JSON array nor valid JSON Lines. This is expected behavior. If your destination can't read it, select One file per page of records, which writes each page as its own valid JSON Lines file. Or wrap the loop in [ ] as described in Write a JSON array to get one valid JSON array.
Preview may show Evaluated result is not valid JSON for this template. The warning appears only in Preview, and you can still save and run the import.
Write a summary without a loop
A template without an {{#each}} loop writes one output per page instead of one per record. Use it for a summary, such as the number of orders on each page:
{"count": {{batch_of_records.length}} }The template field shows a yellow warning because the template has no {{#each}} block. You can still save and run the import.
One file per page of records writes a valid file for each page of the five sample orders:
-
orders-1.json:{"count": 2 } -
orders-2.json:{"count": 2 } -
orders-3.json:{"count": 1 }
One file per flow run runs the template once per page and joins the results with commas:
{"count": 2 },{"count": 2 },{"count": 1 }This output isn't valid JSON, and integrator.io doesn't wrap it into one object. To get a single count for the whole run, add an {{#each}} loop as described in Write a JSON array, or select One file per page of records.
Write an XML document
XML templates use the same header, loop, and footer model as JSON templates, but integrator.io concatenates XML pages with no separator. Because of this, XML templates that generate one file per flow run must include an {{#each}} block.
Template uses a loop with a root element
Wrap the loop in a root element to produce a well-formed XML document. XML templates accept {{#each batch_of_records}} or the older {{#each data}}. This example uses batch_of_records:
<orders>
{{#each batch_of_records}}
<order>
<id>{{record.orderId}}</id>
<customer>{{record.customer}}</customer>
<sku>{{record.sku}}</sku>
<qty>{{record.qty}}</qty>
<total>{{record.total}}</total>
</order>
{{/each}}
</orders>Double braces, such as {{record.customer}}, escape special characters, so & is written as &. Use double braces for XML values to keep the document valid. One file per flow run produces one document:
<orders>
<order>
<id>SO-1042</id>
<customer>Northwind Outfitters</customer>
<sku>JKT-NAVY</sku>
<qty>2</qty>
<total>249.5</total>
</order>
<order>
<id>SO-1043</id>
<customer>Blue Harbor Co</customer>
<sku>HAT-OLIVE</sku>
<qty>1</qty>
<total>88</total>
</order>
<order>
<id>SO-1044</id>
<customer>Cedar & Pine</customer>
<sku>BOOT-8</sku>
<qty>1</qty>
<total>412.1</total>
</order>
<order>
<id>SO-1045</id>
<customer>Sequoia Trading</customer>
<sku>GLOVE-M</sku>
<qty>3</qty>
<total>54.75</total>
</order>
<order>
<id>SO-1046</id>
<customer>Harborview Supply</customer>
<sku>BAG-CANVAS</sku>
<qty>1</qty>
<total>132</total>
</order>
</orders>One file per page of records produces three files, each a complete <orders> document that contains the orders from one page.
Template uses a loop without a root element
A loop with no root element writes a sequence of <order> elements. This output is an XML fragment - a set of elements without a single enclosing root - and is valid only if the destination accepts fragments. If the destination expects a full XML document, use a root element.
Template without a loop
Whether an XML template without an {{#each}} block is allowed depends on the file-count setting:
- One file per page of records — Allowed, with the same yellow warning as JSON. Each page becomes its own valid document.
-
One file per flow run — Shows an error on the template field because concatenating a complete document for each page would produce XML with multiple root elements, which parsers can't read. For example:
<summary><count>2</count></summary> <summary><count>2</count></summary> <summary><count>1</count></summary>
You can still save and run. The template field shows the error so you can add an {{#each}} block or select One file per page of records before the file is written. Preview of one page can still look fine. Imports created or edited through the integrator.io API don't show this UI error and can still write the unreadable file.
Warnings and errors reference
integrator.io checks JSON and XML templates when you save or preview them and shows these messages:
| Message | When it appears | Can you save? |
|---|---|---|
Without an {{#each batch_of_records}} block, this template won't loop over records. |
The template has no {{#each}} block. For XML, integrator.io also accepts {{#each data}}. |
Yes |
To generate one XML file per flow run, add an {{#each batch_of_records}} block or switch to One file per page of records. |
XML file type, One file per flow run, and no {{#each}} block. |
Yes |
| Evaluated result is not valid JSON | The Preview output isn't a single JSON value. | Yes. This warning appears only in Preview. |