Substituting reports

In versions prior to Business Central 2021 release wave 1, extensibility isn't 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, it's possible to extend reports. With a report extension object, you can extend existing report objects, similar to how you extend tables and pages. With report extensions, you can extend an existing report by:

• Adding columns to existing data items in the report dataset
• Adding new data items
• Adding trigger implementations
• Adding to request pages
• Adding more report layouts, either to reflect new fields that are added with an extension, or simply adding new report layouts on an existing report dataset.

Using a report extension, you might not need to use the report substitution feature.

For more information on report extensibility, see Report extension object.

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 is 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)
    begin
        if ReportId = Report::"Customer - List" then
            NewReportId := Report::"My New Customer - List";
    end;
}

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.

Note

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:

   • Run Method
   • RunModal Method
   • SaveAsHtml Method
   • SaveAsXml Method
   • SaveAsPdf Method
   • SaveAsExcel Method
   • SaveAsWord Method
   • RunRequestPage Method
   • Execute Method
   • Print Method
   • SaveAs Method

For more information about raising events, see Raising Events.

Good practices

• Consider using the same caption for both reports, given by the Caption Property. So, 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's substituted for one with another caption.

• Consider enhancing the code of the subscriber method to check if the report is already 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 is already substituted for another subscriber of the OnAfterSubstituteReport event.

Important

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