HowTo develop a new report

Example

This page uses the "Partner by City" as an example.

Report Definition

• this is for the sql queries and instructions how to calculate and render the report
• create new html report file in XmlReports/Partner/partnerbycity.html. See https://github.com/openpetra/openpetra/blob/master/XmlReports/Partner/partnerbycity.html

GUI Definition

• this is for defining how a screen should look like that presents all parameters of the report to the user
• see https://github.com/openpetra/openpetra/blob/master/js-client/src/forms/Partner/Reports/PartnerReports/PartnerByCity.html
• see https://github.com/openpetra/openpetra/blob/master/js-client/src/forms/Partner/Reports/PartnerReports/PartnerByCity.json

Data Calculation

For calculation of the data, see this class:

• https://github.com/openpetra/openpetra/blob/master/csharp/ICT/Petra/Server/lib/MReporting/MPartner/PartnerByCity.cs

Navigation

• modify the file csharp\ICT\Petra\Definitions\UINavigation.yml
  • if you are using a customized version of OpenPetra, this will be Customizing\gui\UINavigation.yml

 Reports: {Icon=printer.ico, Namespace=Ict.Petra.Client.MReporting.Gui.MPartner}
     PartnerByCity: {ActionOpenScreen=TFrmPartnerByCity}

Store default settings

Once you are able to run your Report GUI, you can enter and select the default values and then save the settings with the name "standard", and this should create the file XmlReports/Settings/Partner/Partner by City/standard.xml. Add this line of code to the standard file to make sure that your standard settings don't get overwritten by the user:

<Parameter id="systemsettings" value="True" />

If you have a date in your settings, you most likely want to use the current date when you load the standard settings. To make this happen delete the line in standard.xml where the date is defined. If the Date Time Picker doesn't get a date, it is set to the current date.

Committing new files to git

You will usually have to add these files to git:

XmlReports/Partner/partnerbycity.xml
XmlReports/Settings/Partner/Partner by City/standard.xml
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/PartnerByCity.yaml
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/PartnerByCity.cs
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/PartnerByCity.Designer.cs
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/PartnerByCity.ManualCode.cs

There will be modified files as well, but TortoiseGit will show those anyways:

csharp\ICT\Petra\Definitions\UINavigation.yml (or Customizing\gui\UINavigation.yml)
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/Ict.Petra.Client.MReporting.Gui.MPartner.csproj

Files that the reports do depend on

• Most report yaml files refer to a base yaml file, eg. csharp\ICT\Petra\Client\lib\MReporting\gui\MPartner\PartnerReportingForm.yaml
  • this is useful to define general permissions, which are not implemented yet
  • also defines the way the user can select the columns

• on the report definition side (XML), the report depends on XmlReports\reports.dtd which is the schema DTD for the XML file, and on XmlReports\common.xml or other xml files to avoid similar basic functions or queries in several XML files.

Calling special functions

If you want to get some special data which you can't get from a sql querry then you can call functions on the server to retrieve those data. There are two ways to use the data in the report xml file.

• If you want to get just one value you call the function and assign the return value to a variable.
• If you want to get many different values, you have to store these values on the server side in the results.

Getting one value from the server

For example "GetFieldOfPartner". This function is implemented in Server/lib/MReporting/MPartner/Functions.cs and returns a string with the field name of the partner. The function is called from XmlReports/Personnel/passportexpiryreport.xml and assigned to a varible in the report.

Getting many values from the server

For example to get the best address of a partner use GetPartnerBestAddress. This function is implemented in Server/lib/MReporting/MPartner/Function.cs and returns the all the address details of the best address of a partner. The function is called from XmlReports/Personnel/emergencycontactreport.xml.

Each value is stored with a command like this:

situation.GetParameters().Add("StreetName", "81 London Road");

In the xml file there must be a definition for StreetName:

<calculation align="left" id="Street Name" returns="text" returnsFormat="text">

<value text="Street Name"></value> <query> <queryDetail> <value variable="StreetName"></value> </queryDetail> </query> </calculation> There is a list of all the special function in Special Functions For Reports

Verify values for report generation

In many cases some values need to be defined in order to generate a report. To inform the user about undefined values use the TVerfification class during the method ReadControls().

• AReportAction indicates in which context ReadControls() is called. It is either during save, load, or generating the report.
• Add an instance of TVerification to FPetraUtilsObject to inform the user about some missing values. If there is a Verification error, the report will not be generated or saved.