ReportingCloud Developer Blog

Retrieving template information using the ReportingCloud Web API

Blogged by Björn Meyer on Friday, August 11 2017

ReportingCloud provides an extensive API to manage templates. You can upload, list, count, delete and download templates from the ReportingCloud template storage. But it also provides endpoints to retrieve data structure information from a template.

The endpoint template/info returns information about the template including the merge field and merge block structure in a hierarchical form.

GET https://api.reporting.cloud/v1/templates/info

After calling this method with the template name as a request parameter, it returns a JSON string with the template information similar to this:

The returned object is of type TemplateInfo which contains all fields at root level and all nested merge blocks including contained merge fields:

TemplateInfo object

Key Value type Value description
templateName String The filename of the template in the template storage.
mergeBlocks List of ReportingCloud MergeBlock objects Contains all merge blocks in the template.
mergeFields List of ReportingCloud MergeField objects Contains all merge fields in the template.

MergeBlock object

Key Value type Value description
name String The name of the MergeBlock.
mergeBlocks List of ReportingCloud MergeBlock objects Contains all merge blocks in the template.
mergeFields List of ReportingCloud MergeField objects Contains all merge fields in the template.

MergeField object

Key Value type Value description
dateTimeFormat String Specifies a string format which is applied to date / time values.
name String Gets and sets the name of the field.
numericFormat String Specifies a string format which is applied to numeric values.
preserveFormatting Boolean Specifies whether the formatting is preserved.
text String Gets and sets the text of the field.
textAfter String Gets and sets the text after the field.
textBefore String Gets and sets the text before the field.

In most cases, hierarchical data is used to design the template. But there are also use cases where data is shaped based on the data structure in a template. The work flow would be similar to this:

To illustrate how to iterate through the hierarchical data, the following code shows how to fill a tree view in .NET using the .NET ReportingCloud wrapper:

The following screenshot shows the populated tree view in a sample .NET Windows Forms application:

ReportingCloud Template Browser

If you want to test this on your own, register today for a free 30-day trial license.

Happy coding!


Merging nested repeating blocks in ReportingCloud

Blogged by Björn Meyer on Thursday, August 10 2017

Thanks to the data source excerpt file concept, it is very easy to create templates with complex structures such as nested repeating blocks. A data source excerpt file is used to fill the drop-down lists of the template editor with proper merge fields, relations and dummy data for a template preview. A data source excerpt file is not the actual data that is used to merge the template. It helps to design the templates and to insert the proper field names.

In this article, the following .NET classes are used as the data source structure for the ReportingCloud merge process:

Report is the master template which reflects the complete template. In other words, the complete template is merged with the number of rows in this master template. The following code shows the instantiated .NET object that is used:

This object has 1 Sale object which consists of 2 different Item objects. In the template, a list of all Sale items should be visualized as a merge block. Inside this outer merge block, all Item objects should get listed as a nested merge block. The following screenshot shows this structure in the template:

Merging nested repeating blocks in ReportingCloud

But how to insert these blocks in the ReportingCloud template designer?

First, we need to create a serialized JSON string from the object. You can create this string manually or simply serialize this object using the JavaScriptSerializer class:

The results will look similar to this:

In the ReportingCloud Portal, open My Datasource Excerpts and create a new excerpt file by adding a name and pasting the JSON string to the excerpt input. As ReportingCloud expects an array of objects as the data source, enclose the complete string with square brackets.

Merging nested repeating blocks in ReportingCloud

Now, when designing the template in the ReportingCloud template designer, the merge blocks are listed in the available Insert Merge Block drop-down button. In the ReportingCloud Portal, create a new template in the My Templates area. Before editing the template, select the created datasource excerpt file from the available sources and confirm with Edit Template.

Merging nested repeating blocks in ReportingCloud

  1. In the opened template designer, click on sales from the Insert Merge Block drop-down to insert the outer merge block sales.

  2. Set the input position into the block row and add a table row using the right-click context menu.

    Merging nested repeating blocks in ReportingCloud

  3. Set the input position into the newly created table row and choose items from the Insert Merge Block drop-down to insert the nested block items.

  4. In the opened dialog, select the 2 columns price and qty and confirm with OK.

    Merging nested repeating blocks in ReportingCloud

A second nested block has been inserted into the outer block:

Merging nested repeating blocks in ReportingCloud

When previewing this template, the expected results of the nested block are rendered successfully:

Merging nested repeating blocks in ReportingCloud

Test this on your own and create a free trial account today.


ReportingCloud: Uploading templates vs. sending templates inside MergeBody

Blogged by Björn Meyer on Wednesday, August 02 2017

Our reporting Web API ReportingCloud provides two different ways to upload templates for merging processes:

  1. Upload templates into the template storage in a separate step
  2. 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.

POST 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.

GET https://api.reporting.cloud/v1/templates/exists

In order to delete a template from the template storage, the /templates/delete endpoint should be used.

DELETE 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:

POST 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!


MailMerge: Table headers and repeating blocks

Blogged by Björn Meyer on Tuesday, August 01 2017

When using table headers and repeating blocks in combination in a MailMerge process, there are some things you need to know before creating your templates.

A table header can consist of n number of rows in a table that get repeated as header rows at the top of each page when tables break across pages. The following screenshot shows a repeated table header:

MailMerge: Table headers and repeating blocks

Repeating blocks or merge blocks is a very flexible feature within Text Control Reporting. The content of a block is repeated based on the number of data rows that are passed in the merge process. Generally, a block can repeat anything: A table row, a complete table, paragraphs or a single word. All break characters are repeated and applied automatically. The following screenshot shows a merge block in a template. The highlighted area in red defines the repeating block.

MailMerge: Table headers and repeating blocks

After merging data into the template, the merge block is perfectly repeated:

MailMerge: Table headers and repeating blocks

A merge block can be part of a table that has a table header that gets repeated automatically when a table breaks across pages. As you can see in the sample template above, the second table row (highlighted in red) represents the merge block. The block is part of a table that has been created with a repeating table header. This table header is valid for the complete table and is repeated for each page the table is extended to.

The table header can contain merge fields from the master table or related tables.

MailMerge: Table headers and repeating blocks

It is also possible to include the table header into the merge block in order to insert the block data merge fields into the table header.

Now, consider a nested merge block that contains block data in a table header:

MailMerge: Table headers and repeating blocks

In this case, you have to be careful with the merge block setup. As the outer table is expanded over pages, it will have a static table header with the same content for all pages. In the results, you can see that the header on the second page still reads status AA, even if the data rows are already coming from the third merge block CC.

MailMerge: Table headers and repeating blocks

In order to solve this issue, the complete table should be embedded into the block. Each block table has it's own table header, in case a block table breaks across pages.


Are we moving to the cloud? This question is changing from "if" to "when" and "how"

Blogged by Björn Meyer on Friday, July 14 2017

Business-critical documents must be created and stored on premise!

This is a sentence that was and might be valid for information governance people around the globe. Companies must exercise control over its data processing and ensure that data is processed on valid legal grounds and in a secure environments. All of that is true, but the ship has already sailed on the cloud. The cloud is not the solution for everything, but it should be part of every process planning discussion.

Are we moving to the cloud?

Digital transformation changed every process in today's business world. The number of e-commerce transactions skyrocket and supply chains are fully connected. In nearly any business process, documents and reports need to be designed, created, shared and archived.

Companies who are not digitizing their operations and documents will be left behind

As Text Control, we are very strong in the healthcare industry and this seems to be the fastest and most dynamic vertical when it comes to digitization of document processes. This is surprising as you would think that the data protection barriers are significantly higher in this industry. And that is very true.

But with the help of incentives (and penalties), the Health Information Technology for Economic and Clinical Health (HITECH) Act in the United States, paper records have been transformed to electronic patient records very quickly.

Are we moving to the cloud?

In the 70s, the "paperless office" have been promoted mainly with cost saving incentives, because documents were not supposed to be printed anymore. We all know that the "paperless office" didn't happen yet. In the near future, paper won't go away completely. But an effective digitization will be crucial for companies. We believe that the form of a document will continue to survive even with 100% digital transactions.

Consider a complete paperless office and a paperless order process. Company A is ordering a product from company B. The order is arriving digitally directly in company B's system (let's say as JSON as this format is hip right now). The seller is checking inventory automatically and when the products are available, they are shipped. An order notification, shipping "paper" and an "invoice" is generated in JSON form and will be sent to the procurement system of company A.

So far so good. The goods have been exchanged, digital invoices have been sent and the transaction is completed. This process works very well, if all business partners provide the same interface to their EDI (Electronic Data Interchange) systems and if all business partners have such a system. Additionally, this works very well with pre-negotiated terms and conditions. But as long as a human is involved in this process, a human-friendly paper format based document is required. The paper format is the perfect format to get a quick overview of a transaction. Compare an invoice to a dashboard report that summarizes mass data that could not be recognized easily by looking at the pure data.

Users will increasingly demand pixel-perfect information on any device

Employees use a variety of devices to process and view documents in business processes. Mobile phones, tablets, laptops and desktop computers must be included in each and every process. Creating documents and forms for each of these devices from one source is the goal in these cases.

The PDF format is the de facto standard and successor of the printed document. It has the same paper based format, cannot (easily) be modified, can be encrypted, protected and controlled (user access options) and it is available in several ISO standards such as PDF/A for archiving purposes.

Today's business applications need to include paper-based processes, PDFs and digital documents

Text Control provides the tools to integrate powerful document processing into business applications. Documents and reporting templates can be created and modified in any browser using a fully featured WYSIWYG MS Word-like interface and documents such as invoices can be created on a server or in the cloud. Text Control products help to integrate PDF document workflows into processes and to create centralized document creation processes.

Are we moving to the cloud?

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.


More impressions from DWX Developer Week 2017

Blogged by Björn Meyer on Thursday, June 29 2017

The DWX Developer Week 2017 was a huge success. We really enjoyed the powerful atmosphere talking to so many enthusiastic developers about our products, technologies and services.

On the last day, we had our XBox One raffle and handed out again hundreds of Text Control yo-yos. Thanks to everyone who stopped by our booth. User feedback and innovation drives our development. We are spending a significant amount of resources to support conferences and community events around the world, because we believe in the technology we all use every day.

We are convinced that those technical events from developers for developers are very important to build a thriving developer community.

Find below more impressions of the raffle and our booth area:

See you next year!


DWX Developer Week 2017: First impressions

Blogged by Björn Meyer on Tuesday, June 27 2017

We are currently exhibiting at Germany's largest conference: DWX Developer Week. We are giving away our Text Control yo-yos, raffling off an XBox One and talking about our reporting libraries, our roadmap for version X15 and upcoming products.

Below, you will find some impressions of the conference atmosphere and our booth area:

Stay tuned for more impressions of the following days.


NDC Oslo 2017 impressions: Part II

Blogged by Björn Meyer on Monday, June 19 2017

Last week, we exhibited at NDC Oslo 2017 - a fantastic event. We would like to say thank you to all attendees who stopped by our booth to talk about our products and services. It was a lot of fun talking to everybody.

Below, you will find the second part of impressions of the conference atmosphere and our booth area:

See you next year!


First day at NDC Oslo 2017: Some impressions

Blogged by Björn Meyer on Thursday, June 15 2017

We just wrapped up the first day of NDC Oslo 2017 where we are exhibiting as partners since 4 years now. At this fantastic conference in the Oslo Spektrum, more than 2000 developers meet to learn, share and connect.

We talked to so many users and interested attendees about our products and handed out hundreds of our blue Text Control yo-yos and Text Control stickers.

Find below some impressions of the conference and our booth area:

We will post more impressions of NDC Oslo 2017 over the next days. Happy coding!


Meet Text Control at Developer Week 2017 (DWX) in Nuremberg

Blogged by Björn Meyer on Wednesday, June 07 2017

Meet Text Control at Developer Week 2017 (DWX) in Nuremberg

#BlackShirt is coming to DWX in Nuremberg for his keynote: Learn about Mobile DevOps with Xamarin, HockeyApp and Visual Studio Team Services.

If you want to see Donovan L Brown (#BlackShirt) live on stage and learn from 150+ other great speakers around the world, you should attend this conference in Germany. On June, 26-29 2017, attendees can learn in 200+ sessions more about .NET, web and mobile development, agile practices and UI development.

We will be exhibiting with a small team to present our roadmap of TX Text Control X15 and to give demos of our reporting functionality. If you are attending, stop by our booth and say hello.

See you in Nuremberg!


Read older blog entries