Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

Data Keys

The most critical part of any report is data.  Without data, there is nothing to report!  In the Reporting Module, we use Data Keys and (optionally) Keychain Expressions to feed the report from the data sources.  The simplest reference to data is a simple Data Key.  A Data Key is a reference that points to the data it represents. At report generation time, these keys resolve to the values (or sets of values) provided by the data source.   In simple terms, Data Keys are placeholders for your data.

 Data Key Example

If we created a data source named Countries, we can experiment with Data Keys to see how they resolve.  Create a table in the Report Designer.  Drag the Countries data source from the Key Browser to the Data Key field in the Table Configuration Panel as seen below.  In the image, you can also see that we enabled the Table's Header, and typed header descriptions for each column we wanted to display.  Then we dragged and dropped keys from the Key Browser into the Details columns.  We can tell which items in the Report Designer reference data keys because they are surrounded by "@" symbols.

"Countries" Data Source
Country, Capital, Population
"China", "Beijing", 20693000
"Japan", "Tokyo", 13189000
"Russia", "Moscow", 11541000
"South Korea", "Seoul", 10528774
"Mexico", "Mexico City", 8851080
"Italy", "Rome", 2858104
"Germany", "Berlin", 3520000

If we click to the Preview tab, you will see a simple table that neatly displays a row for each entry in Countries data source.  Looking at the XML in this tab, you can see that the Countries data source sent a single row of data for each entry.  You'll notice that the headers are printed exactly as they were in the Design panel.  As an experiment, you can surround these header values with "@" symbols to see what happens.

Data Key Usage

All text fields in Report Design elements are able to resolve Data Keys.  In fact, you can freely mix plain text and data keys anywhere. In our table example above, we could substitute "@Population@" with "@Population@ people" and the data key portion would be swapped out for the appropriate data.  This can be a very powerful feature when trying to create reports. For example, you could have a text field at the bottom of a report that displays "@Page@ of @PageMax@".   If for some reason your Data Key can't be found, your report will display a Substitution String (which defaults to "<N/A>" but can be configured in the Report's Property Table by selecting the Report in the Project Browser).   

For more information on Data Key syntax, lease see the Key Calculations page. 

Data Keys as Paths

Data Keys are relative, and use 'dot notation' to reference children.   Meaning, if we have a nested data structure, we can use Data Key paths (also known as Keychains) to reference the nested data.  In the key browser image below, we have a nested data source called Downtime.  Downtime contains a number of columns, and then contains a reference to additional data called runInfo.  If we wanted to access the highlighted operator data, we could use the keychain dot notation in the designer - @Downtime.runInfo.operator@ .  Nested data sources are outside the scope of this page, but you can learn about Data Source nesting in the Nested Queries section.

Array Index of Data

You can reference an individual object in a list using standard array indexing syntax (brackets) like this: @Data[0].firstName@, where Data is a data source that contains a child data key named firstName. In this case, we would be accessing the first firstName in the set of data.

On this page ...


Built-In Keys

Built-In Keys provide a lot of useful information on your report at a glance. The Built-In keys are found in the Key Browser.  Expand the Built-In folder and you'll see all the default keys, including a Report folder.  The keys in the Report folder are specifically related to the report: Gateway name that the report is located in, report name, folder path from the Project Browser to the report, and the Timestamp of the Gateway.  The other Data Keys are related to information you may want to add to a report like the date you are viewing or printing the report, page number, number of total pages, and more.

Here's a screenshot of the Key Browser showing all the default Built-In Keys that can be used on a report.


The tables below show the Built-In Report Data Keys and Built-in Data Keys along with a brief description of each key. 

Built-In Report Data Keys

Key Description 
GatewayName of the Report's Ignition Gateway
NameName of the Report
PathPath to the Report in the Project Browser
TimestampThe Gateway's current timestamp

Built-In Data Keys

DateThe current date/time
PageThe current page
PageMaxThe total number of pages in the generated report
Page of PageMaxShows current page number and the total number of pages in the report
PageBreakThe number of explicit page breaks encountered
PageBreakMaxThe total number of explicit page breaks in generated report
PageBreakPageThe number of pages since last explicit page break
PageBreakPageMaxThe total number of pages in current explicit page break
RowShows the current row number. Must be used in a table


In the Design Panel, simply drag any of the data keys anywhere on to your report. Move them around on your report until you find the best location. The Preview Panel shows exactly how the report will look when it is generated. 


Built-in Keys

Design Panel

Preview Panel


Show Calculations Property

Another important property is Show Calculations. In the Key Browser, set the Show Calculations property to 'true' and expand Datasources.  You'll see the 'count' key was added under Datasources. A 'count' is the total number of rows in your Datasource. Expand your columns and you'll see that a number of built-in keys were added. For each column you can calculate the following: value, total of all the values in that column, average, maximum value, minimum value, running total, and running average. These keys are available for each column that you bring into your table once you set Show Calculations to 'true'. The Show Calculations property can come in pretty handy once your familiar with how it works.

Drag one of the keys over to the table and you'll notice the value or total or whatever shows up.  You can also create another row for the summary information, create titles (i.e. Total, Summary) and bold it so it stands out. Not recommended for text strings, but for showing calculations this is great.



Use Dynamic Data Keys

Dynamic Data Keys allow you to make changes to a report allowing you to tailor a report to a specific need or requirement at a given time. You can bind properties on Reporting components to parameters. It's as simple as dragging-and-dropping the parameter to the property, or right clicking the property and clicking on 'Use dynamic data key'.


Dynamic keys are very powerful. You can bind report parameters to components on a window allowing you to change a report based on a specific need.

Date and Number Formats

Date Format and Number Format properties accept Dynamic Data Keys. String values should be used for these properties, such as "#0.00##" for number format.

Each property has several predefined format strings to choose from for displaying Dates and Numbers. Click on the icon on the right side of the property name to select a format string, and press OK



Use Dynamic Data Key




  • No labels