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!
