Overview of Reporting in the system

The Reporting functionality in system:inmation integrates the Stimulsoft reporting engine into DataStudio, giving a full suite of options to configure the report design. The retrieval of data and subsequent report layout is done using the Report Item object and the corresponding Report Designer Display. All configuration data is stored in the Report Item object.

The Stimulsoft Reports documentation is available here.

Concept of Reporting

To understand how the reporting functionality works in system:inmation, it is useful to consider the concepts of Design Time and Run Time before starting the examples.

Design Time covers the design phase and the initial configuration of the Report Item object. This includes using the Report Designer Display AND its Preview feature. Once the design phase is over and the report design configuration is saved in the Report Item, the report can be viewed in a Dashboard display.

During Design Time, the data that is shown in the ReportDesigner display is not reflective of Realtime data from linked data items. It is static data that is provided during the initial configuration of the item and will not be updated whilst still in the Design Time phase.

Run Time begins when the Report Item is triggered (manually or through another reference object). At this point, the designed Report will be populated with real-time (or history) data values from datasources specified in either the embedded Lua script or other Report query options. The Run Time Report will be displayed when a Report Item is added to a Dashboard display.

The differences between Design Time and Run Time will be highlighted in the examples below.

Report Item

The Report Item object is used to retrieve and structure data for reporting. It is similar to the Action Item object in that it can execute Lua scripts and be triggered through linked references in order to produce reports on demand or periodically. The report layouts that are created in the Report Designer Display during Design Time are saved in the Report Item in XML format. The data for the reports is retrieved using Lua then encoded in a JSON string that provides the structure for reporting. The different data fields and the structure of the JSON string can be defined in the Report Design Time Data property of the Report Item or in one of the pre configured Query Options. This JSON string is read by the Report Designer display as the data structure for the report.

  1. To create a Report Item under the Core, right-click on the Core object in the I/O Model and select Admin  New  Report  Report Item from the context menu.

  2. In the Create Object wizard, give the item a name then click Create.

The screenshot on the right highlights some of the key properties of the Report Item.

  • Lua Script Body - syslib Lua functions can be used to retrieve data from items in the I/O model. Scripts should return a JSON string containing fields that successfully populate designed reports. JSON string should ideally match the JSON data structure in Report Design Data property.

  • Report Design Time Data - This houses a JSON string that provides the data structure and contains the data fields that will be available in the Report Designer at design time. The Report Design Time Data does not need to be configured if using the QueryOptions (see below).

  • Fit Source Data - If the Fit Source Data checkbox is selected, any incomplete source data (from the Lua script for example) will be fitted to the Report Design Time Data structure at run time.

  • QueryOptions - To access data producing items in the I/O Model without having to create Lua scripts from scratch, preconfigured Realtime, Namespace and History query options can be set using a point and click interface.

  • Report Design Data - This property houses the report design from the Report Designer Display as an XML file. Multiple report designs can be created for each Report Item.

Detailed information on how to configure these properties will be covered in the examples.

Report Designer Display

The Report Designer uses the Stimulsoft Report designer engine which offers a full suite of configuration options.

Report Designer Display
Figure 1. Report Designer Display

The Report Designer Display primarily consists of a large Workspace section where the reports are designed and the Panels section on the left-hand side of the workspace. Possible report elements are located on the left-hand toolbar. The top eight icons on this bar are element groups while all the lower icons are shortcuts to selected elements from these groups. The top of the designer display is filled with the toolbars section. A status bar is located at the bottom of the display.

Report Items can be added to the Report Designer display via the context menu or by drag and drop into the window.

The report layout can be previewed by clicking on the Preview tab in the main Report Designer menu bar.

The Panel section on the left of the workspace has 3 tabs, Properties, Dictionary and Report Tree.

  • The Properties tab is where selected workspace items can be configured.

  • The Dictionary tab contains all the available data items that can be added to the report. This includes the data fields from the Report Design Time Data JSON defined in the Report Item. Other pre-defined fields (Date, Time, Count and others) that can be added to reports are also included.

  • The Report Tree tab shows the structure of the report in terms of the different elements that can be added (Titles, Data bands, Headers and Footers and others).