ReportingCloud and .NET: Creating Templates with JSON Excerpt Files

A datasource 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 datasource excerpt file is not your actual data that is used to merge your template. It helps you to design your templates and to insert the proper field names.

In this tutorial, you will learn how to create a new template from a class in .NET.

The accepted JSON format in the Merge method of ReportingCloud is a JSON string containing an array of objects.

1. If you don't have a ReportingCloud account, create a new account:

   https://portal.reporting.cloud/Account/Register/

2. Open Visual Studio and create a new application (type and language doesn't matter in this tutorial).

3. Start the Package Manager Console from the NuGet Package Manager menu item of the Tools main menu. Type in the following command to install Newtonsoft Json:

   PM> Install-Package Newtonsoft.Json

4. Create the required classes for your report. The following sample shows a simple invoice class:

   	public class Invoice
   	{
   	public string InvoiceNumber { get; set; }
   	public Customer Customer { get; set; }
   	public List<Product> Items { get; set; }
   	}
   	public class Customer
   	{
   	public string Name { get; set; }
   	public string Street { get; set; }
   	public int Zip { get; set; }
   	public string City { get; set; }
   	}
   	public class Product
   	{
   	public string Name { get; set; }
   	public string Description { get; set; }
   	}

   view raw tx.cs hosted with ❤ by GitHub

5. Use the following code to create an instance of your data and use JsonConvert class to serialize the object to a Json string:

   	List<Invoice> Invoices = new List<Invoice>();
   	Invoice invoice = new Invoice()
   	{
   	Customer = new Customer() {
   	Name = "Peter Thiel",
   	City = "Charlotte",
   	Street = "123 Microsoft Way",
   	Zip = 22282 },
   	InvoiceNumber = "I778977622",
   	Items = new List<Product>()
   	{
   	new Product() {
   	Name = "Product 1",
   	Description = "Product 1 Description"
   	},
   	new Product() {
   	Name = "Product 2",
   	Description = "Product 2 Description"
   	}
   	}
   	};
   	Invoices.Add(invoice);
   	var json = JsonConvert.SerializeObject(Invoices, Formatting.Indented);

   view raw tx.cs hosted with ❤ by GitHub

   Set a breakpoint to line 28 and copy the string from the Text Visualizer to the clipboard:

   

   This Json format is exactly the format that is accepted by the Merge method of ReportingCloud and the online template designer.

6. Open a browser and navigate to:

   https://portal.reporting.cloud

   Log in with your credentials.

7. Click on My Datasource Excerpts and create a new excerpt file by adding a name and pasting the Json string into the Datasource Excerpt text box:

   

   Save the excerpt file by clicking the Create Excerpt button.

8. Click on My Templates, choose New Template... and type in a name and choose your preferred template format such as DOCX. Confirm with OK.

   

9. In the next dialog, click on Edit template, choose the created datasource excerpt file from the drop-down box and confirm with Edit Template:

   

10. The template editor is opened and you can start designing your template. Open the Merge Field drop-down box from the Merge Fields group of the Reports ribbon tab.

    Open the master table and insert the merge field invoicenumber.

    

11. After the merge field has been added, insert some blank lines and then click on Merge Block to select items from the available drop-down items. In the opened dialog box, check description and name and confirm with OK.

    

12. A repeating merge block (marked as red) is inserted into the template:

    

13. Now, click on Preview Merge Results in the Preview group and confirm the opened dialog box with OK.

    

14. Finish your template design, save the template and use Back to navigate back to the dashboard.

This template contains the proper field and block names that matches your datasource. When merging the template with the list of Invoice objects, ReportingCloud will populate the merge fields with the public property values of your invoice objects.