Make documents from a spreadsheet

Getting the form

Open a template, choose "Make from spreadsheet", and download the Excel form or one CSV per sheet. The form is generated from the template: the number of sheets is decided by how deeply the template nests arrays. No arrays: one sheet (doc). A table over data.items: two sheets (doc and items). Two levels (a block with a table inside): three.

Row 1 is the header and is the contract — do not change it. Row 2 explains each column, row 3 is an example; both are ignored on upload. Enter data from row 4. The Excel file also carries a hidden sheet that ties it to the template.

Filling it in

Column A of every sheet is _key, the document key — for example the invoice number. It must be different for every document and is what joins the rows of one document across sheets. It is not part of the data your template sees.

A third-level sheet (a table inside a repeating block) also has _row in column B: the number of the parent row among rows with the same _key, counting from 1. Second-level sheets need only _key; their order is the file order.

An empty cell means the value is missing. If the template uses that value, generation stops and the cell is named. To make a column optional, give it a default in the template: {{ data.memo || "" }}.

Numbers: plain digits only — no thousands separators or currency symbols. "1,000" stays text and breaks arithmetic. Dates: YYYY-MM-DD. In Excel, number and date cells keep their type; in CSV a cell that reads entirely as a number becomes one.

CSV: one file per sheet. Keep the file names — they say which sheet a file is and which template it belongs to. Files saved by Korean Excel in EUC-KR are read as well as UTF-8.

What is checked

The check runs in your browser; the file is not sent to the server. It compares the form to the current template, the headers to the expected columns, the keys (empty, duplicate, orphaned), and the row limits. Then it compiles every document the same way the renderer will, and reports any value the template cannot use: empty cells, text where arithmetic needs a number, more than 100 pages.

Every finding names the sheet, row and column. If there is one finding, the make button does not appear. Fix the file and upload again.

Making and downloading

After the checks, the first document is previewed and the button says how many documents will be made and how many credits that costs. Documents are submitted 50 at a time as one run; the page shows done, running, queued and failed counts and a download link per finished document.

If submission stops partway (quota or queue budget), the documents already submitted are still made, the run is marked failed at that point, and you can upload again to submit the rest. A run is never silently cut short.

Scheduled runs

Instead of uploading a table every time, register a data URL and we fetch it on schedule and build the documents. It must be an https URL that opens without a login — a Google Sheets “publish to the web” CSV link, an export URL on your own server, and so on.

A schedule is daily, weekly on a chosen weekday, or monthly on a chosen day, plus a time and a time zone. There is no cron syntax. Because the time zone is stored, a run happens at the same wall-clock time even where daylight saving applies. A day that does not exist in a month (the 31st of February, say) falls back to the last day of that month.

We open the URL and check it the moment you register it. If it does not pass, nothing is saved — so you never learn about a broken URL a month later, on the first run.

Every run goes through exactly the same checks as an upload. If anything fails, no document is built at all, the run is recorded as failed, and we email you. No credits are used. Successful runs are not emailed.

A given run happens once and only once. After three consecutive failures the schedule turns itself off and we tell you. If you edit the template it no longer matches the registered form, so delete the scheduled run and create it again.

The shortest interval is one day; there are no hourly or minute schedules. A run starts later than the time you set — usually by about a minute, and by at most six. That is the wait for the next five-minute sweep plus the delay the cloud adds in firing it. Each run builds at most 500 documents (fewer than the 1,000 you may upload by hand), each URL may return at most 10 MB within 20 seconds and through at most 3 redirects. The number of scheduled runs you can keep on equals your plan's template count. Sources that require a login or token are not supported yet.

Limits

Up to 1,000 documents per run and 10 MB per file. Arrays may nest two levels deep (a block and a table, or two blocks); a template three deep cannot have a form. Each document is subject to the usual 100-page limit and to your plan quota — one document is one render.