Edit

Upgrade reports

APPLIES TO: Upgrading to Business Central 2024 release wave 1 (version 24) and later from Business Central version 19 and earlier

This article discusses changes to the report platform done in Business Central 2022 release wave 1 (version 20) and their effect on upgrading from version 19 and earlier to version 24 and later.

Report platform changes

Version 20 introduces a new report rendering model. Previously, the application rendered reports. With version 20 and later, the platform renders reports by default,

To support this new model, Business Central includes the following changes:

  • An updated Microsoft Word report rendering engine
  • A new custom report renderer
  • Improved layout management that supports multiple layouts per report by using extension layouts
  • New platform-supported layouts and layout selection tables
  • New and obsoleted application events in codeunit 44 ReportManagement

New and obsoleted events

This section lists the new and obsoleted events in version 24 and later.

New events

Codeunit 44 ReportManagement includes new integration events for processing reports and loading report layouts.

  • Events for processing reports:

    [IntegrationEvent(false, false)]
local procedure OnAfterDocumentReady(ObjectId: Integer; ObjectPayload: JsonObject; DocumentStream: InStream; var TargetStream: OutStream; var Success: Boolean)
begin
end;

[IntegrationEvent(false, false)]
local procedure OnAfterDocumentDownload(ObjectId: Integer; ObjectPayload: JsonObject; DocumentStream: InStream; var Success: Boolean)
begin
end;

[IntegrationEvent(false, false)]
local procedure OnCustomDocumentMergerEx(ObjectID: Integer; ReportAction: Option SaveAsPdf,SaveAsWord,SaveAsExcel,Preview,Print,SaveAsHtml; ObjectPayload: JsonObject; XmlData: InStream; LayoutData: InStream; var DocumentStream: OutStream; var IsHandled: Boolean)
begin
end;

  • Events for loading report layouts:

    [IntegrationEvent(false, false)]
local procedure OnSelectReportLayoutCode(ObjectId: Integer; var LayoutCode: Text; var LayoutType: Option "None",RDLC,Word,Excel,Custom; var IsHandled: Boolean)
begin
end;

[IntegrationEvent(false, false)]
local procedure OnFetchReportLayoutByCode(ObjectId: Integer; LayoutCode: Text; var TargetStream: OutStream; var IsHandled: Boolean)
begin
end;

Obsoleted events

Some events in codeunit 44 ReportManagement and codeunit 9651 "Document Report Mgt." have been obsoleted.

  • Codeunit 44 ReportManagement events:

    [IntegrationEvent(false, false)]
[Obsolete('Replaced by platform document merge using OnCustomDocumentMergerEx.', '20.0')]
local procedure OnMergeDocumentReport(ObjectType: Option "Report","Page"; ObjectID: Integer; ReportAction: Option SaveAsPdf,SaveAsWord,SaveAsExcel,Preview,Print,SaveAsHtml; XmlData: InStream; FileName: Text; var printDocumentStream: OutStream; var IsHandled: Boolean)
begin
end;

[EventSubscriber(ObjectType::Codeunit, Codeunit::"Reporting Triggers", 'ReportGetCustomRdlc', '', false, false)]
[Obsolete('This procedure will be replaced with platform functionality. Subscribe to the event FetchReportLayoutByCode instead to retrieve a layout.', '20.0')]
local procedure ReportGetCustomRdlc(ReportId: Integer; var RdlcText: Text)
begin
end;

[IntegrationEvent(false, false)]
local procedure OnAfterHasCustomLayout(ObjectType: Option "Report","Page"; ObjectID: Integer; var LayoutType: Option "None",RDLC,Word,Excel,Custom)
begin
end;

[IntegrationEvent(false, false)]
local procedure OnApplicationReportMergeStrategy(ObjectId: Integer; LayoutCode: Text; var InApplication: boolean; var IsHandled: Boolean)
begin
end;

[IntegrationEvent(false, false)]
local procedure OnWordDocumentMergerAppMode(ObjectId: Integer; LayoutCode: Text; var InApplication: boolean; var IsHandled: Boolean)
begin
end;

  • Codeunit 9651 "Document Report Mgt.":

    [IntegrationEvent(false, false)]
[Obsolete('Platform will render Word Document Reports, look for OnAfterDocumentReady.', '20.0')]
local procedure OnAfterConvertToPdf(var TempBlob: Codeunit "Temp Blob"; ReportID: Integer);
begin
end;

[IntegrationEvent(false, false)]
[Obsolete('Platform will render Word Document Reports.', '20.0')]
local procedure OnAfterGetCustomLayoutCode(ReportID: Integer; var CustomLayoutCode: Code[20])
begin
end;

[IntegrationEvent(false, false)]
[Obsolete('Platform will render Word Document Reports.', '20.0')]
local procedure OnBeforeMergeDocument(ReportID: Integer; ReportAction: Option SaveAsPdf,SaveAsWord,SaveAsExcel,Preview,Print,SaveAsHtml; var InStrXmlData: InStream; PrinterName: Text; OutStream: OutStream; var Handled: Boolean; IsFileNameBlank: Boolean)
begin
end;

[IntegrationEvent(false, false)]
[Obsolete('Platform will render Word Document Reports.', '20.0')]
local procedure OnBeforeMergeWordDocument()
begin
end;

[IntegrationEvent(false, false)]
[Obsolete('Platform will render Word Document Reports, look for OnDocumentReady.', '20.0')]
local procedure OnAfterMergeWordDocument(ReportID: Integer; InStrXmlData: InStream; var TempBlob: Codeunit "Temp Blob")
begin
end;

[IntegrationEvent(false, false)]
[Obsolete('Platform will render Word Document Reports.', '20.0')]
local procedure OnMergeReportLayoutOnSuppressCommit(ReportID: Integer; var IsHandled: Boolean)
begin
end;

What the changes mean for upgrade

These report rendering changes may affect upgrades from earlier versions if your application:

  • Uses layouts stored in application table 9650 Custom Report Layouts
  • Implements custom report layout selection
  • Subscribes to any of the obsoleted events.

The following areas are commonly affected:

  • Report layout selection that depends on OnAfterHasCustomLayout event or design-time temporary selection. The platform extends layout selection to support additional layout types.
  • Events on the Document Management codeunit related to Word documents as layouts now render in platform by default.

If you perform a full upgrade of the pplication and platform, you might have to rewrite custom code to use the new events. For more information, refer to Upgrade of reports with custom layouts.

These changes don't affect the upgrade process for RDLC report layouts or built-in Word reports layouts. If your solution doesn't include custom Word layouts, then no action is required.

Upgrade of reports with custom layouts

The new platform now supports native rendering of Microsoft Word reports. As a result, the following report events in AL are no longer used:

  • OnAfterHasCustomLayout
  • OnMergeDocumentReport
  • OnBeforeMergeDocument

If you have custom code that subscribes to these events, change the code to subscribe to new events, including:

  • OnSelectReportLayoutCode
  • OnFetchReportLayoutByCode
  • OnCustomDocumentMergerEx

Customization of OnAfterHasCustomLayout event

Custom code that uses the OnAfterHasCustomLayout event must be reimplemented to use the following events instead:

  • OnSelectReportLayoutCode

    This event gets the layout code and type that the application has set using the Report Layout Selection application table.

  • OnFetchReportLayoutByCode

    This event reads the layout data from application tables (not needed if the layouts are stored in platform system tables by using extension provided layouts or layouts inserted manually in the Tenant Report Layout table.

Customization of OnMergeDocumentReport or OnBeforeMergeDocument

Extensions that depend on the legacy Microsoft Word render by using the OnMergeDocumentReport or OnBeforeMergeDocument events must be changed to use the new custom report render type and subscribe to OnCustomDocumentMergerEx instead.

By subscribing to OnCustomDocumentMergerEx, the application can use extension defined report renders featuring layouts stored in the platform layout tables. These layouts must be added as type custom in the reports rendering section. By subscribing to OnCustomDocumentMergerEx, the layouts can be added in the extension by using the rendering section in AL code of the report. The layout will then be stored in the platform layout tables.

  • Last updated on