Skip to content

Reports

Report generation in the Payroll Engine is split into two stages: the backend prepares the data as an ADO.NET DataSet, and a report client transforms it into a document. Any tool that accepts ADO.NET DataSets can act as a client — the Payroll Console and the web application both use FastReport Open Source.

Report Generation Process

Report Generation Process

The pipeline has five optional steps: build parameters → validate → setup queries → execute queries → post-process results. A simple report needs only the query step. Complex reports can implement scripting at every stage using the Microsoft DataSet API.

Reports support localized templates per culture (.frx, .docx, .rdlc, …) — the same report definition can produce an English and a German document from the same data.

Report Definition

A report is a regulation object. It defines the queries to run, the parameters to accept, and the templates to use for rendering.

Example Report.yaml — a monthly payroll result report for the Basic Payroll example:

# yaml-language-server: $schema=PayrollEngine.Exchange.schema.json
createdObjectDate: 2023-01-01T00:00:00Z
tenants:
- identifier: StartTenant
  regulations:
  - name: StartRegulation
    reports:
    - name: StartReport
      queries:
        Employees: QueryEmployees               # produces the Employees DataTable
        Results: QueryPayrollResultValues       # produces the Results DataTable
      parameters:
      - name: TenantId
        hidden: true                            # injected automatically, not shown in UI
        parameterType: TenantId
      - name: PayrunJobName
        mandatory: true                         # user must supply this value
      - name: Results.Filter
        hidden: true
        value: "jobName eq '$PayrunJobName$'"   # OData filter — scopes Results to one job
      templates:
      - name: StartReportTemplate English
        culture: en
        contentFile: Report.English.frx
      - name: StartReportTemplate German
        culture: de
        contentFile: Report.German.frx
    updateMode: NoUpdate
  updateMode: NoUpdate

The Results.Filter parameter is a hidden OData expression that passes the PayrunJobName value directly into the query filter — no scripting required for simple result scoping.

Report Template

FastReport templates are XML files that declare TableDataSource elements to bind query results. The two tables from the report definition above — Employees and Results — are connected by a parent-child relation on Identifier / EmployeeIdentifier.

For the visual design of FastReport templates, download the free Community-Edition Designer (FastReport.Community.{Version}.zip) and run Designer.exe.

Full template source: Report.frx

Key sections of the template:

<!-- Data declaration -->
<Dictionary>
  <TableDataSource Name="Employees" ReferenceName="Data.Employees" ...>
    <Column Name="Identifier" DataType="System.String"/>
    <Column Name="FirstName"  DataType="System.String"/>
    <Column Name="LastName"   DataType="System.String"/>
    <!-- additional columns -->
  </TableDataSource>
  <TableDataSource Name="Results" ReferenceName="Data.Results" ...>
    <Column Name="KindName"          DataType="System.String"/>
    <Column Name="ResultNumericValue" DataType="System.Decimal"/>
    <!-- additional columns -->
  </TableDataSource>
  <!-- parent-child join: one employee row -> many result rows -->
  <Relation Name="EmployeeResults"
            ParentDataSource="Employees" ChildDataSource="Results"
            ParentColumns="Identifier"   ChildColumns="EmployeeIdentifier"
            Enabled="true"/>
</Dictionary>

<!-- Report layout: Employee band -> nested Result band -->
<DataBand Name="Employee" DataSource="Employees">
  <TextObject Text="[Employees.FirstName] [Employees.LastName]"/>
  <DataBand Name="Result" DataSource="Results"
            VisibleExpression="[Results.ResultNumericValue] != 0">
    <TextObject Text="[Results.KindName]"/>
    <TextObject Text="[Results.ResultNumericValue]" Format="Currency"/>
  </DataBand>
</DataBand>

Running the Report

Report parameters are passed as a JSON file. For the example above, the only required parameter is the payrun job name from the Basic Payroll test:

{
  "PayrunJobName": "StartPayrunJob.Jan23"
}

Available Payroll Console commands for this example:

Command Output
Report.Setup.pecmd Full setup + PDF report (initial run)
Report.Pdf.English.pecmd English PDF
Report.Pdf.German.pecmd German PDF
Report.Excel.pecmd Excel workbook
Report.XmlRaw.pecmd Raw XML dataset

In the web application's report dialog, parameters and output format are selected and the document is offered for download.

Next Steps