}

Committed by
Bjoern Meyer on Wednesday, February 13, 2019

Merging Templates

The basic idea of ReportingCloud is to populate placeholders (merge fields) in templates to create the final document.

Invoices, quotes or any other dynamic documents can be created from any application: Desktop, web or mobile. Whether creating an iPhone, Android, Windows Phone or web app - using Text Control ReportingCloud, professional documents can be created with one simple Web API call. The Web API endpoints enable developers to manage templates and to create documents.

The Basic Idea

The most typical application of ReportingCloud is to merge MS Word compatible templates with JSON data. These templates contain merge fields and repeating blocks that are populated with hierarchical data. ReportingCloud is matching these fields and merge blocks automatically with data from your JSON data in form of arrays.

The following illustration shows this concept. On the left, you can see an MS Word compatible template with merge fields. This template gets merged with JSON data using the endpoint document/merge. The response of this request is an Adobe PDF document encoded as a Base64 string.

The Merging Workflow

This is an example of how you can use the ReportingCloud Web API to merge data into a template:

  1. You create your document exactly as you want it to look like (WYSIWYG) using the template editor or any word processor that supports MS Word formats.

  2. As placeholders, merge fields are added to the document. These merge fields get names that should match your data (name/value pairs) in the JSON string.

  3. In your document/merge request, pass the JSON data with the actual data that should be used to populate the placeholders.

Template Storage Considerations

Templates can be created and stored in the ReportingCloud template storage and loaded from there when merging a template. In this case, the template name is simply passed as a request parameter when calling the document/merge endpoint.

Another way is to send the template with the document/merge request in the mergeBody object. The template can be passed as a Base64 encoded string. Supported formats are RTF, DOC, DOCX and TX.

Templates (that usually doesn't contain sensitive data) can be stored in the ReportingCloud template storage. Using the Web API, potentially sensitive data is sent to our servers in JSON format. ReportingCloud merges this data with the template and returns a resulting document.

We never store any merge data nor created documents on our servers at any time. Only transaction meta data to log the transaction is stored to provide statistics and to calculate the document quota.

Naturally, the merge process is faster, if the template has been already uploaded to the template storage. If you reuse templates many times, it makes sense to upload the templates to the storage, so that the template must not be uploaded every time the template is merged.

If you send the template with your request, the template is temporarily uploaded to our servers, unpacked in memory, merged and deleted after the merge process. At no time, this template is stored physically on our servers.

We recommend to store the templates in the ReportingCloud template storage and use them from there for document creation processes for performance reasons.

Sample Request

The following sample request shows how to create documents based on templates and data.

Request:

Results:

Request:

Results:

    Found a in our documentation?

    Edit this page on GitHub