Skip to content

MIKE OPERATIONS Report Manager’s Report Writer

Introduction

This document focuses on how to develop MIKE OPERATIONS Report Manager’s Report Writer.

It is assumed that the reader is familiar with MIKE OPERATIONS plugin architecture and configuration through runtime.config. If not, the reader should familiarize himself with reference /1/ and /2/.

Accompanying this document is a zip-file with the source code of the Visual Studio solutions and projects discussed in the text.

What is a Report Writer?

A Report Writer is a pluggable element of Report Manager that allows Report Manager to deliver MIKE OPERATIONS content in a specific form to the user. Typically Report Writer produces a document that is a mix of static (defined in the report template) and dynamic (generated by MIKE OPERATIONS) content. An example of a Report Writer is a MS Word Report Writer, which produces MS Word documents containing MIKE OPERATIONS data like maps, time series plots, spreadsheet, etc.

A crucial feature of a Report Writer is the ability to read and understand report templates. A report template is a document that typically defines static content and placeholders for MIKE OPERATIONS content (dynamic content). The role of a Report Writer is to detect placeholders for MIKE OPERATIONS data, inform Report Manager about them and later fill these placeholders with the data that Report Manager provides based on content configuration that user performs.

A Report Writer supports report properties which are defined by user and applied to the generated report. They can be treated as a metadata that is included in the final document (e.g. author, title, company, etc.)

Each report writer generates report based on provided generation settings, which refer to technical aspects of a report generation, e.g. location of the generated report.

The process can be summarized on the diagram below (MS Word writer is used here).

Figure 1 Report Generation process

  1. User provides report template which is read by Report Writer and all content items are identified

  2. User configures identified content items (this is independent from Report Writer)

  3. User provides Report Writer specific report properties

  4. User provides Report Writer specific report generation settings

  5. Report Writer generates the final report based on: report template, content provided by Report Manager, report properties and report generation settings

A walk-through

This section describes the steps for implementing a specific Report Writer, the TextReportWriter which exemplifies many of the aspects of creating a report writer in the Platform without requiring difficult data handling logic.

A Report Writer will normally comprise of:

  • Report properties class

  • Report writer settings class

  • Report writer settings UI

  • Report handle

  • Report writer

Design of the report writer

The TextReportWriter will create a text report based on a text template. The template will be a simple text file with report content items defined as $itemA, $itemB.

Listing 1 Text report template example

TextReportWriter will support only Text and Report content type, which means that it will not handle Image and Table content.

User will be able to specify following report properties: Author, Title. Since text files have no built in metadata mechanism (like MS Word), properties will be simply written at the beginning of file content.

User will be able to specify following report generation settings: output folder (where to save text report), mark as read-only (created text report file can be marked as read-only).

The Visual Studio project structure

Figure 2 shows a typical example of how to organize a Report Writer in a Visual Studio project.

Figure 2 The solution structure

It is enough to have report writer included in a single project in a Visual Studio solution. The project should reference (among standard .Net libraries) following MIKE OPERATIONS libraries:

  • DHI.Solutions.Generic

  • DHI.Solutions.ReportManager.Interfaces

  • The example project consists of following classes:

  • TextReportHandle – represents the report handle of the text report

  • TextReportProperties – represents properties of the text report

  • TextReportWriter – text report writer itself

  • TextReportWriterSettings – represents generation settings of the text report writer

  • TextReportWriterSettingsControl – control to configure TextReportWriterSettings

Report handle

The report handle class provides the access to the generated report. It should implement the DHI.Solution.ReportManager.Interfaces.IReportHandle interface.

Listing 2 IReportHandle interface

The code listing for TextReportHandle is as follows:

Listing 3 TextReportHandle code

The implementation of TextReportHandle is very simple. It is mostly a container for information set by Report Writer.

Report properties

The report properties class allows the user to set certain properties of the generated report. It should implement the DHI.Solution.ReportManager.Interfaces.IReportProperties interface.

Listing 4 IReportProperties interface

The interface does not include any members itself, just states that each report properties class should be able to serialize and deserialize itself to/from XML (this is needed to persist the properties in database), notify about changes in its content and should be cloneable.

The code listing for TextReportProperties is as follows:

Listing 5 TextReportProperties code, part 1

Listing 6 TextReportProperties code, part 2

Following can be observed in the implementation:

  • IDssSerializable is implemented using DssSerializer class (DssElement attribute is used to mark properties which should be handled by DssSerializer)

  • Cloning is implemented using object.MemberwiseClone(), please note that events have to be nulled in cloned object

  • Author and Title properties are serialized by DssSerializer and are marked with PropertyName and PropertyDescription attributes so that they are properly described in MIKE OPERATIONS property window.

  • Object.ToString() method is overloaded to display a user friendly name for report properties node in the MIKE OPERATIONS property window

Report writer settings

Report writer settings class should contain all properties needed for the Report Writer to know where and how to write the report. It should implement the DHI.Solution.ReportManager.Interfaces.IReportWriterSettings interface.

Listing 7 IreportWriterSettings

The interface states that each report writer settings class should be able to serialize and deserialize itself to/from XML (this is needed to persist the settings in database) and notify about changes in its content. It additionally requires that the implementing class has IsSubReport property, so that Report Manager can communicate to the Report Writer that the report should be generated as a sub-report.

The code listing for TextReportWriterSettings is as follows:

Listing 8 TextReportWriterSettings, part 1

Listing 9 TextReportWriterSettings, part 2

Following can be observed in the implementation:

  • IDssSerializable is implemented using DssSerializer class (DssElement attribute is used to mark properties which should be handled by DssSerializer)

  • OutputFolder and MarkReadonly properties are serialized by DssSerializer

  • IsSubReport property is not serialized as it’s provided each time by Report Manager and needs not to be saved in the database

Report writer settings control

Unlike Report properties which are edited in MIKE CUSTMISED properties control, Report writer settings need to have specialized control provided. The control should implement the DHI.Solution.ReportManager.Interfaces.IReportWriterSettingsControl interface.

Listing 10 IReportWriterSettingsControl

The interface extends DHI.Solutions.Generic.IControl that represents a general MIKE OPERATIONS control and adds a method to bind report writer settings.

Layout of the control reflects the properties of TextReportWriterSettings class. Textbox and checkbox are moved to the right so that they align well with general report generation settings that will be present on the same form in Report Manager.

Figure 3 TextReportWriterSettingsControl layout

The listing of control’s code is as follows:

Listing 11 CsvTableContentFormattingControl code

Please note that:

  • Control binds TextReportWriterSettings properties to its children

  • There’s no need to initialize the control with IShell, as no interaction with Shell or Application are performed in TextReportWriterSettingsControl

  • Caption and IconHandle are not needed, as the control will be embedded in a form

Report Writer

Report writer is the actual plugin in the MIKE OPERATIONS that generates reports, analyses report templates and provides the system with properties and setting classes and controls.

Each report writer has to implement DHI.Solutions.ReportManager.Interfaces.IReportWriter interface.

Listing 12 IReportWriter, part1

Listing 13 IReportWriter, part 2

The code of TextReportWriter class is following:

Listing 14 TextReportWriter basic properties and methods

Please note following:

  • Report writer has its own GUID assigned that will identify the writer among other report writers

  • Report writer returns a name and description that will be shown to the user (typically these come from a resource file, so they can be localized)

  • Report writer returns explorer icons for normal and derived report definitions that will distinguish them from report definitions from other report writers

  • Report writer returns a list of content types that it will support (Text, Report), i.e. it will only include these types of content in the report and not include other types of content in the report

  • Report writer returns supported files filter, which indicates which files can be read as templates. In case of TextReportWriter, only text files are supported.

  • Report properties, report writer settings and report writer settings control are returned from appropriate methods to allow user to configure the report generation

  • EditTemplate method starts the default process which handles template files. In case of .txt files it is Notepad.exe

  • GetContentItems method uses regular expressions to find all content items, for TextReportWriter these are all words starting with a dollar sign, e.g. $title, $indicatorA

Listing 15 TextReportWriter.Generate() part 1

This listing shows first part of the implementation of TextReportWriter.Generate() method. Please note the following:

  • Method gets the report writer settings object which needs to be casted to correct type. Generate method is also responsible for ensuring that the provided settings are correct. Here it checks if the output folder for the report is specified if the report is not a subreport (subreport should use a temporary path)

  • Method prepares metadata object which in this case is just a string that will be later written to the output file

  • Content items in the report template are replaced with the actual content. Text content is provided as string by Report Manager and Report content is provided as IReportHandle (which points to a file which can be read). All problems that occur during content substitution have to be reported as warnings. They will be later presented to the user by the Report Manager.

Listing 16 TextReportWriter.Generate() part2

This listing shows a second part of TextReportWriter.Generate() implementation. What happens here is:

  • Report output location is determined. If the report is to be generated as a subreport it will be written to a temporary location. Otherwise the provided folder should be used.

  • The report is written to the file on disk (metadata + template with subsitituted content).

  • Read-only attribute is set on file according to the user preferences provided in ReportWriterSettings object. This is just an example of user provided setting, other report writers don’t have to define and use read-only setting.

  • Report handle is created and all required properties are assigned

  • Report handle is returned

Deploy file

Part of the solution is also a TextReportWriter.deploy file. This is needed to ensure easy inclusion of TextReportWriter in runtime.config.

Listing 17 TextReportWriter.deploy

Deploy file for the report writer has only one plugin listed. The plugin is of type DHI.Solutions.ReportManager.Interfaces.IReportWriter.

Use in application

After the report writer has been built, copied to Bin folder of MIKE OPERATIONS and included in runtime.config it should appear as one of report types in the “Add new report definition” dialog.

Figure 4 Add new report definition

After the report definition is created it is displayed in report explorer with its own icon.

Figure Report explorer with text report defintions

Example template for the text report writer can look like this:

Listing 18 Text report writer temlpate example

Content items in the template (bold font) are: $one, $two, $three.

After setting the content and properties in the Report Manager final report can look like this (substituted content in bold):

Listing 19 Text report writer report example