Substituting standard reports

by Jun 20, 2022AL Language, Reports

Home 9 Development 9 AL Language 9 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;

Recent Articles from the category

Connect to Azure Function in BC 2022 wave 2 (v21)

Connect to Azure Function in BC 2022 wave 2 (v21)

The new version of the Microsoft Dynamics 365 Business Central brought a new system module "Azure Functions" that makes integration with Azure Functions much easier and straightforward. The typical scenario, why to use Azure Functions together with Business Central,...

read more
Collectible Errors?! Is it already in use?

Collectible Errors?! Is it already in use?

Collectible Errors?! Is it already in use? This is the second part of my new article series about Collectible Errors. Let's check out the first part here: Collectible Errors?! | Microsoft Dynamics 365 - Ing. Tomáš Kapitán (kepty.cz) or you might be interested in my...

read more
Collectible Errors?!

Collectible Errors?!

Collectible Errors?! It has been already almost a year since ErrorInfo datatype & CollectibleErrors were introduced (I already have an article about basic structure: ErrorInfo data type & Collectible Errors). This article was released for the first time in...

read more
Report layouts in Excel? Yes!!!

Report layouts in Excel? Yes!!!

Everyone is surely aware of how strong Excel is as a software. It has been deeply ingrained in corporate operations worldwide, whether it be for assessing stocks or companies, creating budgets, or organizing customer sales lists. Usage of Excel Layout Due to the fact...

read more
Isolated events

Isolated events

With Business Central 2022 wave 1, a new setting for event publishers was introduced. Until this version, any error in any event subscriber caused interruption to the current running process and stopped the whole activity. In some cases (such as log-in), this is...

read more
Custom Filter Tokens

Custom Filter Tokens

As a user of the Business Central you have some constants you can use to filter or insert values. These constants contain useful values for data manipulation such as t / today for date field - return current dateq / quarter for date field filters - return range of the...

read more
1D & 2D Barcodes in Business Central 19.1

1D & 2D Barcodes in Business Central 19.1

Business Central (cloud-only!) includes one-dimensional (1D) barcode fonts since Microsoft Dynamics 365 Business Central 2020 wave 2 (17.0) was released in October 2020. It is a great improvement to how developers can handle requirements from their clients to print...

read more

Sign Up for News

Certifications

Highest certification
Microsoft Data Management and
also in D365 Business Central

Microsoft Certified: Dynamics 365 Business Central Functional Consultant Associate

See other certifications here