Mail Merge
Mail merge is the main task of ReportingCloud: you design a template once, your application sends JSON data with each request, and the Web API returns finished invoices, quotes, letters or reports as PDF, DOCX or another format. Each merge depends on a request with the right parameters, data shaped like the template, merge fields and blocks that match the data and settings for empty values and formats.
If you haven't merged a template yet, start with the Web API tutorial in Getting Started, which merges the demo template of your trial account.
How Mail Merge Works
A merge brings three parts together:
- The template is an MS Word compatible document, designed in the template editor of the ReportingCloud portal or in a word processor that saves DOCX, DOC or RTF. It contains merge fields for single values, merge blocks for repeating and optional sections, and image placeholders. A merge uses a template from your template storage or one sent with the request.
- The data is a JSON array of records. Its names match the names of the fields and blocks of the template.
POST /v1/document/mergefills the template with each record and returns the created documents as Base64 strings, in PDF, DOCX or another format, as one document or as one document per record.
Formatting and layout stay in the template, so your code doesn't change when a designer changes them.
Find the Right Page
| If you want to | Read |
|---|---|
| Understand the merge request, choose between a stored and a sent template and create one document or one per record | Overview |
| Build the JSON data for a template, or let the .NET or PHP SDK build it from your objects or arrays | Merge Data |
| Name, format and list the merge fields of a template, and keep or remove empty fields | Merge Fields |
| Repeat table rows for line items and decide what happens to blocks without data | Merge Blocks |
| Merge data with several levels, such as sales with their items | Nested Blocks |
| Merge logos and other images into image placeholders | Images |
| Include a section of the document only when the data contains it | Conditional Blocks |
| Merge text with bold, italic and underlined parts into a field | HTML Content |
Look up every option of the mergeSettings object, from empty fields to a document password | Merge Settings |
| Format dates and currency amounts for a country | Culture |
| Design a template for your data with a datasource excerpt in the template editor or in MS Word | Template Design |
Where to Start
- Overview: the request, its parameters and its response.
- Merge Data: the data your application sends.
- Merge Fields and Merge Blocks: the elements of every template.
- Template Design: a template built for your own data.
The parameters, the MergeBody and the MergeSettings object are listed in full in the reference of POST /v1/document/merge.
Pages in This Section
- Overview: how a template and data become documents, and how the merge request is built.
- Merge Data: the JSON array of records and how the SDKs serialize objects.
- Merge Fields: field names, formats, the fields of a stored template and empty fields.
- Merge Blocks: repeat parts of a template for each element of an array.
- Nested Blocks: design and merge a template with blocks inside blocks.
- Images: bind image placeholders to Base64 image data.
- Conditional Blocks: show or remove a block depending on the data.
- HTML Content: merge formatted HTML into merge fields.
- Merge Settings: every option of the
mergeSettingsobject. - Culture: format dates and currencies for a culture.
- Template Design: prepare data, create an excerpt and design a template.