When a file-based import writes JSON or XML files — to FTP, SFTP, Amazon S3, Azure Blob Storage, Google Cloud Storage, or Celigo Storage — a handlebars template defines each file's structure: 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 assembles the records in a flow run into files, how to set up the import, which template pattern produces each file structure, and what the template warnings and errors mean. For CSV and XLSX output, see File generation for structured data in CSV and XLSX.
Prerequisites: A flow with an export and a file-based import, a working connection to the file destination, and Manage permissions for the integration.
How integrator.io turns pages into files
A flow run delivers records to an import in pages. The export's page size (Advanced > Pages on the export) sets how many records each page holds, and the import's How many files would you like to generate? setting decides what happens to the pages:
- One file per flow run — all pages are combined into one file.
- One file per page of records — each page is written as its own file.
The template is rendered once per page against the page's list of records, batch_of_records, not against a single record. Each record's fields are under record, for example {{record.orderId}}. integrator.io splits the template into three parts around the {{#each}} loop:
| Part | Where it is in the template | When it's written |
|---|---|---|
| Header | Everything before {{#each}}
|
Once, at the start of each file |
| Loop |
{{#each batch_of_records}} … {{/each}} (XML also accepts {{#each data}}) |
Once per page; inside it, once per record |
| Footer | Everything after {{/each}}
|
Once, at the end of each file |
Outside the loop there is no record, so {{record.orderId}} or a bare {{orderId}} in the header or footer renders empty. Page-level values are available there through batch_of_records, for example {{batch_of_records.length}}.
When One file per flow run combines pages, JSON pages are joined with a comma and XML pages are concatenated with no separator. That rule explains every result in this article: a template that wraps the loop in [ ] or a root element produces one valid file, and a template that doesn't produces stray commas or several root elements. A template with no {{#each}} loop at all is rendered once per page and combined the same way.
The two file types differ in what the template must contain:
| JSON document | XML document | |
|---|---|---|
| Template | Optional. Left blank, the mapped records are written as a JSON array. | Required. |
{{#each}} loop |
Optional. Only {{#each batch_of_records}} is read; {{#each data}} isn't supported. |
Optional for One file per page of records; required for One file per flow run. Accepts {{#each batch_of_records}} (fields as {{record.orderId}}) or the older {{#each data}} (fields as {{orderId}}). |
[ ] or root element |
You type them. integrator.io doesn't add them. | You type the root element. |
Note: Existing templates that already wrap the loop in [ ] or a root element keep working as they are. A placeholder footer added only to make a template save, such as {{myfakefooter}}, isn't needed and can be deleted; leaving it in place doesn't break the file.
Sample data used in this article
Every example uses the same five orders, delivered in three pages with a page size of 2: SO-1042 and SO-1043 on page 1, SO-1044 and SO-1045 on page 2, and 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 as record.<field>:
{
"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 whitespace in your files depends on your template.
Set up a JSON or XML file import
- Go to Home
, open the integration, and then open the flow.
- In Flow builder, select the file-based import step. The Edit transfer form opens.
-
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 JSON document or XML document, enter the handlebars template, following one of the patterns below.
- Select Preview to check the output, and then save the import.
Preview renders one sample page and doesn't upload a file, so use it to check the structure of a single page. It doesn't combine pages: a template that previews cleanly can still write a different file when the flow runs — a comma at a page boundary, several summaries joined by commas, or XML with more than one root element. Because a run uploads to the real destination, point the import at a test folder or destination first.
Choose a template pattern
| 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
Wrap the loop in a header and footer that supply [ and ]. This is the most common pattern, and it works with either file-count setting.
{
"orders": [
{{#each batch_of_records}}
{{{jsonSerialize record}}}{{#unless @last}},{{/unless}}
{{/each}}
]
}-
Header
{ "orders": [is written once at the start of the file. -
Loop runs once per record in the page.
{{{jsonSerialize record}}}writes the record as a JSON object; the triple braces write it as is, where double braces would escape quotation marks and break the JSON.{{#unless @last}},{{/unless}}adds a comma after every record except the last in the page. -
Footer
] }is written once at the end of the file.
With One file per flow run, the five sample orders produce one file. The commas after SO-1043 and SO-1045 are the page boundaries, added by integrator.io, so the array is valid however many pages the run has:
{
"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
}
]
}With One file per page of records, the same template produces three files, each a complete, valid array holding that page's orders. This template shows no warning with either setting.
Write JSON Lines
JSON Lines is one JSON object per line with no surrounding array, used by data lakes and warehouse stages. The template is the loop alone, with nothing before {{#each}} and nothing after {{/each}}:
{{#each batch_of_records}}
{{{jsonSerialize record}}} {{/each}}With One file per page of records, each file is clean JSON Lines:
{"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}With One file per flow run, the pages are joined with a comma like any other JSON template, written directly before the first record of each new 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}That output is neither a JSON array nor valid JSON Lines. If the destination can't read it, select One file per page of records, or wrap the loop in [ ] to get one valid 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 with no {{#each}} loop writes one output per page instead of one per record — for example, a count of the orders on each page:
{"count": {{batch_of_records.length}} }The template shows a warning because it has no {{#each}} block; you can still save and run the import. With One file per page of records, each page becomes a valid file: {"count": 2 }, {"count": 2 }, and {"count": 1 }. With One file per flow run, the per-page results are joined with commas:
{"count": 2 },{"count": 2 },{"count": 1 }That isn't valid JSON, and integrator.io doesn't wrap it into one object. For a single count across the run, add an {{#each}} loop as 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, but pages are concatenated with no separator — which is why an XML template that generates one file per flow run must include an {{#each}} block. Wrap the loop in a root element to produce a well-formed document:
<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>Use double braces for XML values: they escape special characters, so & is written as & and the document stays valid. With One file per flow run, the sample orders produce 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>With One file per page of records, each page becomes its own complete <orders> document.
Two variations to be aware of:
A loop with no root element writes a sequence of <order> elements — an XML fragment, valid only if the destination accepts fragments. If it expects a full document, add the root element.
No loop at all is allowed with One file per page of records, with the same warning as JSON, and each page becomes its own valid document. With One file per flow run, the template shows an error, because a complete document per page would be concatenated into XML with several root elements, which parsers can't read:
<summary><count>2</count></summary> <summary><count>2</count></summary> <summary><count>1</count></summary>
You can still save and run; the error is there 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 look fine. Imports created or edited through the integrator.io API don't show this error and can write the unreadable file.
Template warnings and errors
integrator.io checks JSON and XML templates when you save or preview the import:
| 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, {{#each data}} also counts as a loop. |
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; appears only in Preview |