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 18 Next »

Data Keys

In the Reporting Module, we use Data Keys to pull values from data sources and show them on the report. In simple terms, Data Keys are placeholders for your data. The simplest reference to data is a simple Data Key.  At report generation time, these keys resolve to the values (or sets of values) provided by the data source. Additionally, Data Keys may be used as expressions, which are referred to Keychain Expressions. 

As you add Parameters and Data Sources to the Data section of your report, they will appear in the Key Browser's Parameters and Datasources folders. 

Data Keys on the Report

Data Keys are enclosed in the "@" character when utilized by components in the report. They may be typed manually, or dragged directly from the Key Browser. 

Keys that contain a single value will create a Text Shape when dragged onto the report. 

Keys that represent datasets will create a Table component, and configure the Data Key property to use the key. 

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 Data Key Description


This key has multiple sub-keys that provide meta-data about the report.

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


Built-in Keys

Show Calculations Property

In the Key Browser, the Show Calculations property will add several aggregates to each key. These allow your reports to easily display things like the total of a key. These calculations are typically used in the summary row on the Table component. 

Once Show Calculations is enabled, the Key Browser will refresh, and each key will be expandable. Expanding a key will show the available calculations. 

Show Calculations Disabled

Show Calculations Enabled

Calculation Keys work like any other key: they may be dragged onto the report, and utilized in keychain expressions.

Data Key Usage

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 datasources are outside the scope of this page, but you can learn about Datasource 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.


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


Colors in Expressions

Colors may be references in Keychain Expressions in several ways.

Colors in Hexadecimal

First, hexadecimal case-insensitive color codes may be used. The code must be wrapped in quotation marks to be evaluated correctly. Note that the color change will only appear when the report is executed. The easiest way to test the expression is to switch to the Preview Panel.

Below we see a Blue hexadecimal code of "0000FF" is used on the Fill Color of a Rectangle. The Fill Color on the Rectangle was originally set to White. Because the expression will not evaluate in the Design Panel, the Rectangle will appear as a White color.


However, switching over to the Design Panel will generate the report, and evaluate the expression. This in turn returns a Blue Fill Color. 

The 7th and 8th digits may be added to specify an alpha channel, or the opacity of the color: 00 is fully transparent, while FF is fully opaque. Below, we see the same rectangle, but with a code of "0000FF40". This represents ~25% opacity, so objects behind the rectangle will be visible, and the fill color will only be slightly opaque. 

Strings as Colors

Additionally, case-insensitive string color names may be used to return a color. Again, the value must be wrapped in quotation marks. 

The following string values may be used:



Parameters as Colors

You may also leverage Report Parameters to specify colors. This typically involves creating a parameter with a string datatype, and using the color expression function. 

Once created, you can simply create a dynamic data key reference on the property by dragging the parameter from the Key Browser onto the property in the Property Inspector. This way, you can have several components use the same color, and modify the color in a single location. 

 Multiple Fill Color Expression Example

Expanding on the example above, we can use an expression to return one of potentially multiple colors. This allows us to highlight different values or ranges contextually, making important values stand out. 


#If the value of the "myValue" key is greater than 5, a blue color will be returned. Otherwise, a green color will be used. 


In the image below, the Fill property is also using a dynamic data key, so the Fill Color will be disabled if myValue is less than 1, Blue if myValue is between 1 and 4, and Green if greater or equal to 5. 


To add more color-value pairs, we simply add more if statements:


#If the value of "myValue" will determine one of multiple colors: Greater than 10 will return Red, 6 to 10 will return Blue, and 1 to 5 will return Green.


Use Dynamic Data Key




  • No labels