Table of Contents

Interface IReportGenerator

Report generation is done asynchronously, and the developer must provide a callback method that will be executed when the report is generated.

Important

Development setup
The "auto-start reporting server" feature is not available for backend report generations. The reporting server must be started manually

For PowerShell examples to run in legacy, filesystem, or S3 report persistence mode in development, see Troubleshooting > Configuration.

Warning

Callback execution context
The callback will be executed in a different context, and it could even be on a different instance than the one that made the request. However, the following context is retained: User, SignalR, and Tenant.

Methods RequestAsync<T>(Arguments, callback)

Task RequestAsync<T>(ReportRequestArguments requestArguments, Expression<Func<T, ReportGenerationResponse, Task>> callbackMethod)

  • The ReportRequestArguments class contains the necessary information to generate the report, such as the report name, a filter, and parameters.

  • The callback method will be called as soon as the report server notifies the current cluster instance that the report generation is complete.

  • The ReportGenerationResponse contains information resulting from the generation, such as either the generated report or an error if there was one.

Technical demonstration

Overview

Refer to the TechnicalDemos cluster's menu entry Export from Server in the "Reports" section.

The idea is to add a send email button that will generate a report and return a notification indicating that the email has been sent, along with the name of the report.

The send mail is just a simulation.

Implementation

Setting up the demo involves:

  • Creating a new report (e.g. called "ReportsCustomerForSendEmail").
  • Creating a server method called SendEmail, which will generate the report and simulate sending an email.

In the server method:

  • Injecting the IReportGenerator interface to call the report generation.
  • Calling the RequestAsync method in the ExecuteAsync method.

The RequestAsync method requires a callback, which we need to create a specific class for.

In this case, the class is called EmailSender and has a SendEmailWithReportAttachmentAsync method that takes a ReportGenerationResponse as one of the parameters.

Note

The EmailSender class will be instantiated by the dependency injector, so you can pass it repositories or other dependencies. In this example, we pass it the IMailSentNotification class, which will be responsible for sending a notification to the front-end to simulate the sending of an email.

Tools for response processing

Generated report handling

Since version v2.5, three new APIs have been introduced to simplify report retrieval and optimize storage handling:

  1. ReportGenerationResponse.ReportContent property - Contains the actual UTF-8 content of the generated file, automatically handling Base64 decoding in legacy mode and avoiding unnecessary conversions in NAS-based storage mode.

  2. ReportGenerationResponse.GetDownloadIdentifierAsync() method - Extension method that provides a simplified way to get a download identifier for generated reports, automatically detecting the storage mode and only storing in the database when using legacy mode.

  3. ReportGenerationSucceededNotificationArgs.CreateFromResponseAsync() method - Factory method that creates notification arguments directly from the response, handling storage optimization transparently.

These APIs automatically accommodate both legacy and Network Attached Storage-based deployments without requiring manual storage mode detection.

Migration from older version

If you're upgrading from v2.4 or earlier and have existing code that handles report generation responses, you should migrate to use the new APIs to benefit from storage optimization and improved performance.

The new APIs eliminate the need for manual Base64 conversion and database storage when using NAS-based mode, while maintaining backward compatibility with legacy deployments.

For detailed migration steps and code examples, see Report retrieval migration from legacy mode to NAS-based storage.

Intercepting report generation

You can hook into the report generation process to inspect or modify generated reports before they are processed by your callback. This is useful for:

  • Adding metadata or watermarks to PDFs
  • Implementing audit trails
  • Applying conditional transformations
  • Cancelling callback execution under certain conditions

For complete information on creating and registering interceptors, see Report generation interceptors.

Alternatively, you can modify the PDF directly within your callback method using the ReportGenerationResponse.ForgeSuccessfulGenerationResponse() method. See Alternative approach: modifying PDF in callback for a comparison of both techniques.

Technical API documentation and sample code

For more information and a code sample, please refer to the API documentation of Interface IReportGenerator.

Automatic behavior

Localization

PDF generation is localized based on the language information contained in the HTTP request.

But the language can be overridden with the Culture option.