This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

Reports¶

Warning

This chapter does not explain how to create reports in the admin view or how to write Freemarker. This can be found in the Tocco manual. The manual can be found under https://VERSION.docs.tocco.ch/de . Replace VERSION with the nice2 version you working on (e.g. 218 for V2.18).

How to get started¶

Note

A report can be created via the following steps:

Register your report in the module configuration. See Register Reports
Register an output template. See Register Output Templates
Create fields (if necessary, for simple reports they might not be needed) and register them to the template. See Register Fields
Reload the config in the admin. See Report Synchronization

Now your new report should be available.

Report Synchronization¶

A report is a combination of different entities. Reports consist of the following entities

Report
Report_placement
Report_format
Output_template
Output_template_field
Output_template_format
Output_template_layout
Corporate_design
Corporate_design_business_unit

It would be possible to create these entities manually in the admin view and add them by Changesets like initial values. But it is cumbersome to adjust such entities by changesets. It is even more cumbersome to review a changeset which adjusts such an entity. An initial values changeset for an output template looks like this.

<changeSet author="author" dbms="postgresql" id="values-8sStU434An/2.13.5.0">
  <preConditions onFail="MARK_RAN">
    <sqlCheck expectedResult="0">select count(*) from nice_output_template where unique_id = 'einsatzplanung_kursleitende'</sqlCheck>
  </preConditions>
  <insert tableName="nice_output_template">
    <column name="unique_id" remarks="identifier" value="einsatzplanung_kursleitende"/>
    <column name="label" remarks="lang:de" value="Einsatzplanung Kursleitende"/>
    <column name="sorting" valueNumeric="NULL"/>
    <column name="active" value="true"/>
    <column name="less" value="@font-size-base: 10pt;&#10;@base-document-margin-right: 15mm;&#10;@base-document-margin-left: 25mm;&#10;@correspondence-document-padding-top: 50mm;&#10;@header-height: 25mm;&#10;@footer-height: 20mm;&#10;.ul li{margin-bottom:10px; border:solid 1px;}&#10;.sign {border-bottom:solid 1px;}&#10;.tpos&#10;{&#10;  margin-top: -20px;&#10;}"/>
    <column name="freemarker_template" value="&lt;div class=&quot;document-wrapper correspondence&quot;&gt;&#10;   &#9;[@templateSnippet id=&quot;correspondence_variables&quot;/]&#10;    [@templateSnippet id=&quot;correspondence_content&quot;/]&#10;    &lt;table border=&quot;0&quot; width=&quot;100%&quot;&gt;  &#10;    &lt;tr&gt;&#10;      &lt;td&gt;[@templateSnippet id=&quot;correspondence_location_date&quot;/]&lt;/td&gt;    &#10;    &lt;/tr&gt;&#10;    &lt;tr&gt;&#10;      &lt;td&gt;[@templateSnippet id=&quot;correspondence_signatures&quot;/]&lt;/td&gt;&#10;    &lt;/tr&gt;    &#10;  &lt;/table&gt; &#10;  &lt;table border=&quot;0&quot; width=&quot;100%&quot; class=&quot;tpos&quot;&gt;  &#10;  &#9;&lt;tr&gt;&lt;td class=&quot;sign&quot;&gt;&lt;/td&gt;&lt;td&gt;&amp;nbsp;&lt;/td&gt;&lt;/tr&gt;&#10;  &#9;&lt;tr&gt;&lt;td width=&quot;50%&quot;&gt;Vorname und Nachname&lt;/td&gt;&lt;td&gt;&amp;nbsp;&lt;/td&gt;&lt;/tr&gt;&#10;  &lt;/table&gt;&#10;&lt;/div&gt;"/>
    <column name="hide_logo_checkbox" value="false"/>
    <column name="enable_logo_checkbox" value="false"/>
    <column name="external" value="false"/>
    <column name="edited" value="false"/>
    <column name="_nice_version" valueNumeric="29"/>
    <column name="_nice_create_timestamp" valueComputed="NOW()"/>
    <column name="_nice_update_timestamp" valueComputed="NOW()"/>
    <column name="_nice_create_user" value="tocco"/>
    <column name="_nice_update_user" value="tocco"/>
    <column name="fk_output_template_format" valueComputed="(select pk from nice_output_template_format where unique_id = 'a4_portrait')"/>
    <column name="fk_report_file_format" valueComputed="(select pk from nice_report_file_format where unique_id = 'wkhtmltopdf.pdf')"/>
    <column name="fk_output_template_layout" valueComputed="(select pk from nice_output_template_layout where unique_id = 'header_footer')"/>
    <column name="fk_output_template_entitydocs" valueComputed="(select pk from nice_folder where nice_folder.??? = '???')"/>
  </insert>
</changeSet>

Especially the fields less and freemarker_template are extremely long. These fields contain the whole styling and content of the output template. It is almost impossible to review this.

The report synchronization solves this problem. Output templates and template snippets can be written in *.ftl files, the whole styling can be written in *.less files and reports can be registered in the @Configuration class of the module. The reports then will be synchronized with the applications related database. This means the report synchronization creates, updates entities on the basis of the written files and sets the correct relations (e.g. Report_placement).

Synchronized entities are

Report
Output_template
Output_template_layout
Output_template_field
Template_snippet
Corporate_design
Business_unit_corporate_design

Hint

Entities which are created manually are not synchronized at all. Only entities which are created by the report synchronization will be synchronized further. Therefore the entities have a hidden flag external which is set by the report synchronization.

The following image shows the basic process of the report synchronization.

../../_images/report-synchronization-overview.png

The report synchronization does not synchronize all entities automatically. If such an entity was adjusted manually by any user a hidden flag edited is set to true. On a detail form of a synchronized entity it is always visible if the entity was edited by an user or if it is synchronized.

Example of a synchronized entity

The message on the top of the detail form displays if the output template was edited manually. The report synchronization does synchronize this entity.

../../_images/report-synchronization-synced-output-template.png

Example of a manually edited Output template

The message on the top of the detail form displays if the output template was edited manually. The report synchronization does not synchronize this entity anymore.

../../_images/report-synchronization-edited-output-template.png

Reset a Manually Edited Entity¶

To synchronize a manually edited entity call the action Restore in the detail form. After the entity was restored, the synchronization synchronizes this entity again.

../../_images/report-synchronization-restore.png

Warning

All manual adjustments made by any user are lost if the restore action is called.

Starting the Report Synchronization¶

The report synchronization is done with the ReportSynchronizer service. This service is registered as starter but synchronizes the entities only in the RunEnv mode production and test during the start up.

Starting Manually¶

The report synchronization also can be triggered manually by calling the config reload action reports. Go to the system menu and choose Reload configuration. Select Reports and press Reload selected.

../../_images/report-synchronization-reload-action.png

Register Reports¶

A report can be registered as follows in the module where the report should be added:

@Bean
public ReportContributionsBuilder addressReportContributions() {
    return ReportContributionsBuilder.create()
        .module(currentModule())
        .id("phonelist")
        .label("report.phonelist")
        .synchronize(true)
        .outputTemplate("phonelist")
        .roles("addressmanager, addressguest, usermanager, userguest")
        .outputLanguagePath("relCorrespondence_language")
        .addPlacementConfig(new PlacementConfig("User", "list"));
}

Attribute	Description
active	Sets the field `active` on the entity `Report`.
description	Sets the field `description` on the entity `Report`.
id	A unique id for the report. This is the `unique_id` on the `Report` entity.
label	A text resource key. The label of the report will be set with the corresponding text resource.
outputTemplate	The output template which is set on the report entity. See Register Output Templates
synchronize	`true` if this report should be synchronized. Default is `false`.
roles	If set, only users with these roles can generate the report. If not set, every user can generate this report.
outputlanguagePath	Defines which locale is used to generate the report.

Depending on the placement config attribute, Report_placement entities will be generated. The above example defines that the report will be available on the list form of the User entity.

Attribute	Description
location	Comma separated list of forms where the report will be included (list, detail).
entityModel	The entity model on which the report should be included
sorting	Can be used to place the report more specific.

Register Output Templates¶

Output templates are written in Freemarker and saved in *.ftl files. Output templates are located in the folder <module-root>/resources/outputtemplates.

../../_images/report-synchronization-folder-structure-output-template.png

An output template can be registered as follows in the module where the output template should be added:

@Bean
public OutputTemplateContributionsBuilder addressOutputTemplateContributions() {
    return OutputTemplateContributionsBuilder.create()
        .uniqueId("phonelist")
        .label("report.phonelist")
        .freemarker(findModelResource("outputtemplate/phonelist.ftl"))
        .outputTemplateFormat("a4_landscape")
        .outputTemplateLayout("header_footer")
        .outputTemplateUsage("report")
        .fileFormat("wkhtmltopdf.pdf");
}

Attribute	Description
id	A unique id for the output template. Will be mapped to the `unique_id` on the `Output_template` entity.
label	A text resource key. The label of the output template will be set with the corresponding text resource.
freemarker	The path to the `*.ftl` file. The content of the ftl file will be set on the `Output_template` entity.
less	The path to the `*.less` file. The content of the less file will be set on the `Output_template` entity.
fileFormat	Defines to what format the template will be rendered. Possible formats are `wkhtmltopdf.pdf`, `pdf`, `xml`, `csv`, `xls`, `taf`.
outputTemplateFormat	Defines the format of the output template. See entity `Output_template_format` for available values.
outputTemplateLayout	Defines layout in which the output template is wrapped in. See entity `Output_template_layout` for available values.
outputTemplateUsage	Defines whether this output template is used in a report or correspondence.
hideLogoCheckbox	Sets the field `hide_logo_checkbox` on the entity `Output_template`. Default is `false`
enableLogoCheckbox	Sets the field `enable_logo_checkbox` on the entity `Output_template`. Default is `false`
fileFormat	Sets the file format on the entity `Output_template`. Default is `pdf`

Register Output Template Layouts¶

Register Fields¶

Fields are written in Freemarker and saved in *.ftl files. Fields are located in the folder <module-root>/resources/outputtemplate/fields.

A field can be registered as follows in the module where the field should be added:

@Bean
public OutputTemplateFieldContributionsBuilder addressOutputTemplateFieldContributions() {
    return OutputTemplateFieldContributionsBuilder.create()
        .uniqueId("phonelist.lastname")
        .outputTemplate("phonelist")
        .snippetId("phonesnippet")
        .title("report.phonelist.lastname")
        .sorting(10)
        .freemarker(findModelResource("outputtemplate/fields/phonelist.lastname.ftl"));
}

Attribute	Description
uniqueId	A unique id for the output template field. Will be mapped to the `unique_id` on the `Output_template_field` entity.
outputTemplate	Defines to which output template this field belongs.
snippetId	Simple text which can be defined if two or more fields with the same name are used in the same output template.
title	A text resource key. The title of the output template field will be set with the corresponding text resource.
sorting	Defines the sorting of the field. The higher the sorting, the more right it will appear on the list.
width	Defines the width of the field.
freemarker	The path to the `*.ftl` file. The content of the ftl file will be set on the `Output_template_field` entity.

Register Template Snippets¶

Template snippets are written in Freemarker and saved in *.ftl files. Template snippets are located in the folder <module-root>/resources/templatesnippet.

A template snippet can be registered as follows in the module where the template snippet should be added.

@Bean
public TemplateSnippetContributionsBuilder templateSnippetsContributions() {
    return TemplateSnippetContributionsBuilder.create()
        .uniqueId("generic_table")
        .label("templatesnippet.generic_table")
        .freemarker(findModelResource("templatesnippet/generic_table.ftl"))
        .categories("report");
}

Attribute	Description
uniqueId	A unique id for the template snippet field. Will be mapped to the `unique_id` on the `Template_snippet` entity.
freemarker	The path to the `*.ftl` file. The content of the ftl file will be set on the `Template_snippet` entity.
categories	Defines to which categories the template snippet belongs. Check the entity `Template_snippet_category` for available values.
label	A text resource key. The label of the template snippet will be set with the corresponding text resource.

Register Corporate Designs¶

Corporate designs are written in Less and saved in *.less files. Corporate designs are located in the folder <module-root>/resources/corporatedesign