ReportingCloud: Uploading Templates Vs. Sending Templates Inside MergeBody
ReportingCloud offers two template delivery methods: uploading to persistent storage via the /templates/upload endpoint, or embedding Base64-encoded template data in the MergeBody POST request. Stored templates merge faster because they skip repeated upload transfers each time.
Our reporting Web API ReportingCloud provides two different ways to upload templates for merging processes:
- Upload templates into the template storage in a separate step
- Upload templates inside MergeBody when merging a document
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.
Read more about privacy and data security in this article:
ReportingCloud: Web service privacy and data security
When to Use Which Option?
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.
To upload a template to the template storage, ReportingCloud provides an extensive API to manage the template storage.
The /templates/upload endpoint can be used to upload a template.
https://api.reporting.cloud/v1/templates/upload
In this method, the template data is sent encoded as a Base64 string along with a template name for the template storage. Template names are unique and existing templates with the same name will be overwritten. It is recommended to check first whether a template with that name exists using the /templates/exists endpoint.
https://api.reporting.cloud/v1/templates/exists
In order to delete a template from the template storage, the /templates/delete endpoint should be used.
https://api.reporting.cloud/v1/templates/delete
When merging templates that are stored in the template storage, the template name is given in the /document/merge endpoint's optional request parameter templateName:
https://api.reporting.cloud/v1/document/merge?templateName=test_invoice.tx
In case the template is very dynamic or if you don't want to store templates in the template storage for other reasons, the template can be sent within the merge request. The MergeBody object that is sent within the POST request body data contains not only the merge data, but also the template data in this case:
MergeBody Object
| Key | Value Type | Value Description |
|---|---|---|
| mergeData | JSON object | The datasource for the merge process as a JSON array. |
| template | Base64 encoded string | Optional. The template encoded as a Base64 string. Supported formats are RTF, DOC, DOCX and TX. |
| mergeSettings | ReportingCloud MergeSettings object | Optional. Optional merge settings to specify merge properties and document properties such as title and author. |
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.
If you want to test this on your own, register today for a free 30-day trial license.
Happy coding!
Cloud
Are we moving to the cloud? This question is changing from "if" to "when" and "how". Text Control ReportingCloud brings complete reporting functionality to the cloud so all developers can use it, irrespective of the platform or language they're using. Its highly RESTful API can be used to merge Microsoft Word compatible templates with JSON data from all clients including .NET, Javascript, PHP, Node.JS, jQuery, Ruby, Python, Android, Java and iOS.
Related Posts
MailMerge: Table Headers and Repeating Blocks
Repeating table headers appear at the top of each page when tables span multiple pages during a MailMerge process. When combining table headers with nested merge blocks, the complete table must be…
ReportingCloud: Conditional Text Blocks Based on Merge Blocks
Conditional text rendering in ReportingCloud uses merge blocks combined with the RemoveEmptyBlocks setting. When the data source provides an empty object for a named block and RemoveEmptyBlocks is…
Web API Test Sandbox Released on ReportingCloud Portal
The ReportingCloud portal includes a Web API Test Sandbox for running endpoint calls against your own account data and template storage without affecting document quota. Each endpoint in the Web…
ReportingCloud: New Test Parameter for Document Quota Related Endpoints
ReportingCloud merge, convert, and findandreplace endpoints now accept an optional test parameter. Test calls bypass the document quota and produce watermarked output with a TEST MODE label,…
ReportingCloud: The MergeData JSON Object Format Explained
ReportingCloud merge operations accept a JSON object containing data for all merge fields and blocks. The .NET wrapper serializes typed business objects to JSON automatically via MergeBody and…