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 report design (the Stimulsoft Reports documentation is available here). 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.

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 ReportItem object. This includes using the ReportDesigner display AND its Preview feature. Once the design phase is over and the report design configuration is saved in the ReportItem, 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 ReportItem 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 ReportItem 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 ActionItem 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 ReportItem 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. To create a Report Item under the Core, right-click on it and select Admin > New > Report > Report Item from the context menu. In the Create Object wizard, give the item a name then click Create. The screenshot below highlights some of the key properties of the Report Item.

Report Item Properties
Figure 1. Report Item Properties

  • 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. When the Fit Source Data checkbox is selected, any incomplete source data (from the Lua script for example) will be fitted to the design time data structure at run time. The Report Design Time Data does not need to be configured if using the QueryOptions (see below).

  • QueryOptions - To access data producing items in the I/O in the 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 ReportItem.

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

Report Designer Display

Open the Report Designer display through the Open menu of DataStudio. Report Items can be added to the Report Designer display via the context menu or by drag and drop into the window. The Report Designer uses the Stimulsoft Report designer engine which offers a full suite of configuration options (click here for the Stimulsoft reports documentation). The Display consists of a large workspace area where the reports are designed. The report layout can be previewed by clicking on the Preview tab.

The panel to the right 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 included in the Report Design Time Data JSON defined in the Report Item. Also included are other pre defined fields (Date, Time, Count and others) that can be added to reports.

  • 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).

Report Designer Display
Figure 2. Report Designer Display

The Report Designer Display will be explained further in the worked examples in the following sections.