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.

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:

{
"templateName": "sample_invoice.tx",
"mergeBlocks": [
{
"name": "item",
"mergeFields": [
{
"dateTimeFormat": "",
"name": "qty",
"numericFormat": "",
"preserveFormatting": false,
"text": "«qty»",
"textAfter": "",
"textBefore": ""
}
],
"mergeBlocks": []
}
],
"mergeFields": [
{
"dateTimeFormat": "",
"name": "yourcompany_companyname",
"numericFormat": "",
"preserveFormatting": false,
"text": "«YOURCOMPANY_COMPANYNAME»",
"textAfter": "",
"textBefore": ""
},
{
"dateTimeFormat": "",
"name": "invoice_no",
"numericFormat": "",
"preserveFormatting": false,
"text": "«invoice_no»",
"textAfter": "",
"textBefore": "#"
}
]
}
view raw test.json hosted with ❤ by GitHub

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:

  • Retrieve template information
  • Create data object based on contained data structure
  • Merge template with newly created pre-shaped data object

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:

private void addBlockToTreeView(List<MergeBlock> blocks, TreeNode node)
{
foreach (MergeBlock block in blocks)
{
TreeNode curNode;
if (node == null)
curNode = treeView1.Nodes.Add(block.Name);
else
curNode = node.Nodes.Add(block.Name);
foreach (MergeField field in block.MergeFields)
{
curNode.Nodes.Add(field.Name);
}
if (block.MergeBlocks != null)
addBlockToTreeView(block.MergeBlocks, curNode);
}
}
view raw test.cs hosted with ❤ by GitHub

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!