Substituting Reports

In versions prior to Business Central 2021 release wave 1 extensibility is not supported for report objects. Therefore, if you want to make any changes to the dataset or the layout of a base application report, you must create a new version of the report and apply the changes on the new object. Then you can override the base report with your own customized version by subscribing to the OnAfterSubstituteReport event published by Codeunit 44 – ReportManagement. From Business Central 2021 release wave 1, report extensi

How to substitute a report for another report

To substitute a report, you create a method and subscribe it to the OnAfterSubstituteReport event, as shown in the code below. The OnSubstituteReport method replaces the report specified by the ReportId with the one given by the NewReportId parameter. In this example the "Customer - List" report will be substituted for "My New Customer - List".

codeunit 50100 "Substitute Report"
    [EventSubscriber(ObjectType::Codeunit, Codeunit::ReportManagement, 'OnAfterSubstituteReport', '', false, false)]
    local procedure OnSubstituteReport(ReportId: Integer; var NewReportId: Integer)
        if ReportId = Report::"Customer - List" then
            NewReportId := Report::"My New Customer - List";

For more information on how to subscribe to events, see Subscribing to Events.

When the OnAfterSubstituteReport event is raised, the event subscriber method is called and the substitution takes place.


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.

The OnAfterSubstituteReport event is raised when:

  1. The user activates a page action that runs the report to be substituted, that is, an action that has the RunObject Property set to the report.

  2. The report is invoked from the Tell Me window.

  3. The report is called by one of the following static methods:

For more information about raising events, see Raising Events.

Good practices

  • Consider using the same caption for both reports, given by the Caption Property. Consequently, any links and action captions that lead to the report will match the report itself. This is also relevant for bookmarks linked to a report, since they maintain the caption of the original report, even if it has been substituted for one with another caption.
  • Consider enhancing the code of the subscriber method to check if the report has already been replaced with another extension. This is done by comparing the ReportId and NewReportId parameters before making the change, such that if the value of the NewReportId parameter is different from the value of the ReportId parameter and different from -1, it means that the report has already been substituted for another subscriber of the OnAfterSubstituteReport event.


Make sure that if a report is called on code, you use a compatible report to replace it to avoid run time errors.

See Also

Report Data Type
Subscribing to Events
Events in AL
GetSubstituteReport Method
Get Started with AL