If the built-in accounting software formats do not match what your accounting system needs, create a batch download template. The template is a text pattern written in Handlebars, and Rhythm fills it with each batch’s accounting entries when you download the batch.
What It Controls
A batch download template controls the downloaded batch file’s layout, line by line, and builds the file name. After you create a template, any business unit can choose it as its Custom Download Template: so downloads use your layout instead of the built-in layout for its accounting package. See Accounting Software, Downloads, and Document Templates for where to make that choice.
Downloads produce CSV plain-text files only; they do not create native Excel files. A deferred revenue batch download and a regular batch download work like different reports with different expected columns, so plan to create a separate template for each one.
Built-in accounting software layouts, such as the layouts for Great Plains or Microsoft Dynamics, are shared by every Rhythm account that uses that accounting software. You cannot edit one only for your account. If you need account-specific formatting, or your finance system has no matching built-in layout, such as an older or less common system, create a custom template instead of asking to change the shared layout.
Where to Find It
Go to Finance & Billing › Setup › Templates › Batch Downloads to view your templates, then select Create Batch Download Template to add one. Select a row’s Edit icon to change a template, or select Preview while editing to see what it produces.
The Settings
| Setting | Options | Default | Effect |
|---|---|---|---|
| Name: | Any text | Blank | The template name a business unit sees when choosing a custom download template |
| ID: | Letters, digits, underscores, dashes, and vertical bars | Suggested from the name | The template’s permanent identifier, which you set only when you create the template |
| File Name Template | A Handlebars pattern | A pattern that combines the current date with journal-entries.csv | Builds the downloaded file name, including the date |
| Status: | Active, Inactive | Active | Controls whether the template appears when a business unit chooses a custom download template |
| Layout | A Handlebars pattern that loops over subledgerEntries | A short example that prints one line per entry | Sets the line-by-line content of the downloaded file |
Building the Layout
A new template starts with this example, which you can build on:
{{#each subledgerEntries}}
{{businessUnit.id}} {{glAccount.code}} {{debits}} {{credits}}
{{/each}}Put every field from an individual accounting entry inside an each-loop block over subledgerEntries, as shown in the example. The placeholder picker above the layout box lists available fields by category: Business Unit, Customer, Transaction, Product, Payment, G/L Account, Accounting Project, Department, and Batch. When you choose a placeholder, Rhythm copies it to your clipboard so you can paste it into the layout. These placeholders are not limited to fields stored on the batch record itself; several pull related transaction, product, and payment data into the row.
Some placeholders only work inside that each-loop. If you use one outside the loop, Rhythm refuses to save the layout and shows an error naming the field. If a placeholder you expect to work shows that error, wrap it in the {{#each subledgerEntries}}...{{/each}} block instead of using it on its own.
Not every identifier you want for reconciliation is necessarily available as a placeholder. If you need something specific, such as an invoice, payment, or order number for matching entries back to your accounting system, check the placeholder picker first because the list has grown over time. If the field you need is not offered, a manual Query Center export can assemble similar data as a stopgap, though it takes manual work for each batch and is not a long-term substitute for a working template.
Two fields deserve special care because they are easy to assume will always match. {{department.code}} and {{accountingProject.code}} are both available placeholders, but the department or accounting project on a transaction can belong to a different business unit than the batch transaction itself. Do not derive either code by assuming it shares the transaction’s business unit prefix; use the placeholder’s own value instead.
Your template can also reference several date fields, such as when an order or payment was created, a payment’s own date, and a batch’s close date. These dates do not always match, so check the placeholder picker and use the date your accounting system needs.
Two helpers are especially useful when you format values:
- Row numbering. Use
{{templateRowNumber}}inside your loop to print a consecutive number for each row instead of building your own counter. - Currency formatting. When you use a currency-formatting helper without a currency code, and the value does not include one, the helper prints an unresolved currency marker instead of a plain number. Pass the entry’s own currency code to the helper to avoid that marker.
Tip
Keep your layout to a clean, one-to-one list of output columns. Define each field once, and avoid extra unused placeholders or trailing commas in a CSV-style layout. A duplicated field or stray comma-separated placeholder can shift every value after it into the wrong column of the downloaded file, even though the template saves without error.
Warning
A field that fills in on a detail download can come back blank when the business unit's Batch Download Method is set to Summary or Batch-Level Summary instead of Detail. If batch metadata, invoice, product, or payment placeholders are blank, check the download method before assuming the template is broken.
Rhythm does not add quoting or escaping around text values for you. If a field contains a comma, such as an organization name, the value can split into extra columns when the file opens in a spreadsheet. If that causes a problem for a downstream import, such as QuickBooks Online, wrap that placeholder in literal quotation marks in your layout.
The way a downloaded CSV file opens can also depend on the spreadsheet application and its regional settings. The same file can open neatly in columns in one application and look garbled in another because of decimal, thousands, or delimiter settings. If a download does not look right, check your spreadsheet application’s separator settings before assuming the template produced bad data.
Preview Your Template
Select Preview to render your current layout and file name with built-in sample data, then open the result in a new tab. Use the preview to check your layout before you use it on a real download.
Warning
Preview sample data does not include every field that a real download provides. If your template references totals, a control total, the fiscal period, invoice or order details, or a line’s row number, those fields may be blank in the preview even though they fill in correctly on an actual download.
Your layout can also produce a clean credit memo number in its output, along with the control total and fiscal period fields mentioned above.
Dependencies and Precedence
- A business unit must choose your template. Creating a template does not affect downloads by itself. A business unit’s Custom Download Template: setting must name the template before that business unit uses it. See Accounting Software, Downloads, and Document Templates.
- Only one layout per download. A download uses either your custom template or the built-in layout for the selected accounting software, never both. If you create a custom template to replace a built-in one, such as for NetSuite, and leave out a field the built-in layout normally includes, such as Order ID, that field will not appear in your downloads. Compare your layout against the built-in one if a field goes missing after you switch to a custom template.
Change Impact and How to Revert
Changing a template’s layout or file name pattern affects only downloads made after you save. Files that were already downloaded are not regenerated. If you no longer need a template, switch its Status: to Inactive instead of deleting it. A business unit cannot point to a deleted template, so Rhythm refuses to delete a template while a business unit still names it.
If you fix a template after batches were already posted and downloaded with the broken version, downloading again with the corrected template is not enough on its own. You need to unpost those batches, post them again, and download them again so the correct data reaches your accounting system.
Permissions
You need the Collect Administrator role, specifically access to batch templates, to create, edit, or delete a batch download template. See Set Access and Permissions in Finance & Billing.
Validation and Errors
- A layout that isn't valid Handlebars is refused when you save, with a message that says the template is invalid. Rhythm checks that the layout compiles and runs with no data. A layout that compiles but fails with real data is still accepted here, and it fails only when a download uses it.
- An invalid file name pattern is accepted at save time and fails only when a download is generated.
- An unrecognized helper name in your layout is refused when you save, because Rhythm only understands a fixed set of formatting helpers.
- If Preview fails, Rhythm shows a general message instead of the specific reason. Check your layout for a syntax error, then try again.
- A field appears in the placeholder picker but always comes back blank in your downloaded output, especially when it comes after
creditsin your layout, such as a transaction ID, a product field, or a customer’s organization. Being listed as available does not guarantee every field renders in every account. If a specific placeholder never populates no matter what you try, contact Support.
Related Tasks
Choose your custom template as a business unit’s default in Accounting Software, Downloads, and Document Templates. For the accounts and dimensions your template’s placeholders can reference, see Chart of Accounts, Bank Accounts, and Reporting Dimensions.