Substituting standard reports

Report objects cannot be extended in versions previous to the Business Central 2021 release wave 1 version when ReportExtensions object was introduced. Since then, many of changes we need to do in reports can be done without creating a new copy of object.

On the other hand, there are definitely still many occasions where it’s appropriate (or even necessary) to create a new copy of the existing object. Afterwards, you may subscribe to the OnAfterSubstituteReport event, which is issued by Codeunit 44 – ReportManagement, to override the basic report.

Using another report as a replacement

Subscribing to the OnAfterSubstituteReport event will allow you to replace a report, as seen in the code below. Using the OnSubstituteReport publisher, you may replace a report’s ReportId with a new one. The original “Item Price List” will be replaced by “My Item Price List”.

[EventSubscriber(ObjectType::Codeunit, Codeunit::ReportManagement, 'OnAfterSubstituteReport', '', false, false)]
local procedure OnAfterSubstituteReportReportManagement(ReportId: Integer; var NewReportId: Integer)
begin
    if ReportId = Report::"Item Price List" then
        NewReportId := Report::"My Item Price List";
end;

Important info: In my opinion, the name of the publisher (OnAfterSubstituteReportEvent) is not correct. Microsoft says:

The event is called OnAfterSubstituteReport to match the pattern followed by other events in the ReportManagement codeunit, but the subscriber will be invoked before the substitution takes place.

Microsoft (Substituting Reports)

But the name just do not make any sense as it is definitely happening BEFORE report substitution or even better – OnSubstituteReport. Let’s hope Microsoft will change it in the feature…

The report to be replaced is launched by the user through a page action with the RunObject Property assigned to the report, through “Tell me” search window or if the report is run using any of standard methods (Run, Print, SaveAsXXX, ….).

Good things to know

It’s always a good idea to have report’s caption property with the same caption in both reports. Therefore, all links and captions pointing to the report will be in sync with the report’s actual content. Even when the original report is replaced with one with a different caption, bookmarks linking to the report retain the previous report’s caption.

Furthermore, it is good practice to verify whether the report has been already substituted with another extension: Prior to making a change, check the value of the Reported and NewReportId parameters. If the NewReportId variable is different from -1, it indicates that the report has been replaced in another event subscriber. This is important, because the order of subscribers that subscribe to the same publisher is unpredictable if you do not check the property, it could cause that if you print the report twice, you can get two different reports called.

[EventSubscriber(ObjectType::Codeunit, Codeunit::ReportManagement, 'OnAfterSubstituteReport', '', false, false)]
local procedure OnAfterSubstituteReportReportManagement(ReportId: Integer; var NewReportId: Integer)
var
    MyNewReportId: Integer;
begin
    if ReportId = Report::"Item Price List" then begin
        MyNewReportId := Report::"My Item Price List";
        if NewReportId <> -1 then begin
            // Inform user that there are two reports from two different extensions that are replacing the same source report.
            // Let them choose the one they want to use or return an error that only one is possible and that they should contact authors of both extensions.
            exit;
        end;
        NewReportId := MyNewReportId ;
    end;
end;