Using Data in Reports

A ReportLayer template is designed to be populated with dynamic data from your application. When designing the report, you use a sample of that data, saved together with the template. The structure defined by your sample data allows you to tell the designer how to link sections of your report with the data, and to insert data fields and calculations in the template.

How sample data works

The sample data that you enter in the Sample Data tab in ReportLayer is dummy data, and will not appear in the final generated documents. However, its structure should match the structure that you will provide when the report is generated. That's because the designer uses the structure of the sample data to know how to find data elements for use in the report.

The sample data should be regular JSON data.

Dates

JSON doesn't support literal JavaScript Date objects. For dates, your dummy data should use ISO (8601) date-time strings in double-quotes, for example:

myDate: "2019-05-25"

myDateTime: "2019-05-25T15:53:00"

At runtime your data source can provide the real data value either as an ISO string or as a JavaScript Date object.

Unique JSON elements vs. arrays

It's important to keep in mind which parts of your JSON structure are unique (that is, not repeating). Any element inside an array (whether an immediate element of the array, or nested within an array element) is non-unique.

For example, in the following data sample:

{
  "header": {
    "name": "John Wilson",
    "address": "123 1st St."
  },
  "lineItems": [{
    "quantity": 3,
    "sku": "ABC123"
  },{
    "quantity": 2,
    "sku": "DEF456"
  }]
}

The following paths are unique:

header.name

header.address

lineItems

However, paths within the lineItems array are not unique, because there are multiple elements inside the array. If you write lineItems.quantity, it is not clear which of the array elements should be used.

Any JSON field path that does not go into an array is unique.

Inserting data fields in text elements

Unique data elements can be used in text elements. Data elements are inserted using curly braces around the JSON path to the data element. For examples:

The customer's name is {header.name}.

Calculations use regular JavaScript math syntax in the same curly braces, like this:

The subtotal is {unitPrice * quantity}.

The designer will suggest known data elements in a pop-up next to the text entry area. You can click one of those to insert it.

Using array data to populate report sections and tables

Arrays are useful for creating repeating sections in the report template, where each element in the final array fills one instance of the repeated section. Tables and charts can also use arrays as their row data source.

To create a repeating section in the report, you can select an existing section and use the New Element menu (the + sign at the left margin) to insert a new section above or below.

Select the new section and, in its properties in the left sidebar, select the path to the array node in your sample data.

Note that your sample data does not need to include more than a single element in each array. The important thing is that the sample data inside the array element contain all the field names that you'll want to use in your document.

Aggregating values within arrays

You can use aggregate functions like SUM and COUNT across the elements of an array in your data. To do so, provide the path to the array itself as the second argument to the aggregate function:

{SUM(fieldNameToAggregate, pathToArray)}

For example, if your data looks like this:

{
  "orderDetails": {
    "lineItems": [{
      "quantity": 3,
      "sku": "ABC123"
    },{
      "quantity": 2,
      "sku": "DEF456"
    }]
  }
}

Then the following expression calculates the sum of the quantity fields from each element in the lineItems array:

{SUM(quantity, orderDetails.lineItems)}

Result: 5

You can see an example of this in the totals in the Packing Slip demo report.

How sample data works#

Dates#

Unique JSON elements vs. arrays#

Inserting data fields in text elements#

Using array data to populate report sections and tables#