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

Analysis mode in Business Central 2023 wave 1

Analysis mode in Business Central 2023 wave 1

Analysis mode is a new type of view for any list page, available from Business Central 2023 wave 1. This mode on list pages enables users to analyze and pivot data directly in the client. Let's explore what is available and how it can be used. The feature is disabled...

read more
NavigationAction for ErrorInfo data type

NavigationAction for ErrorInfo data type

One more article about ErrorInfo data type. Have you already read my previous posts about ErrorInfo and Collectible Errors? ErrorInfo data type & Collectible Errors | MSDyn365 Business Central - Ing. Tomáš Kapitán (kepty.cz) Collectible Errors?! | MSDyn365...

read more
Error actions for ErrorInfo data type

Error actions for ErrorInfo data type

It is already almost one and a half years since the ErrorInfo data type was introduced (we saw this data type for the first time in BC2021w2). If you do not know what it is and how to use this data type, check my previous posts: ErrorInfo data type & Collectible...

read more
Data types under the microscope: List

Data types under the microscope: List

The List data type in AL language represents an ordered collection of objects that can be accessed by their index. Unlike an Array data type, a List does not have a fixed size and does not need to have its dimension specified when it is declared. The List data type...

read more
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

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