# 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.
Learn more about report extensibility in Report extension object<devenv-report-ext-object>.
## How to substitute a report for another report
To substitute a report, create a method and subscribe it to the OnAfterSubstituteReport event, as shown in the following code. The OnSubstituteReport method replaces the report specified by the ReportId parameter with the report specified by the NewReportId parameter. In this example, the `"Customer - List"` report is substituted for `"My New Customer - List"`.
```al
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;
}
```
Learn more about subscribing to events in devenv-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 is 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 properties/devenv-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:
  methods-auto/report/reportinstance-run-method
  methods-auto/report/reportinstance-runmodal-method
  methods-auto/report/reportinstance-saveashtml-method
  methods-auto/report/reportinstance-saveasxml-method
  methods-auto/report/reportinstance-saveaspdf-method
  methods-auto/report/reportinstance-saveasexcel-method
  methods-auto/report/reportinstance-saveasword-method
  methods-auto/report/reportinstance-runrequestpage-method
  methods-auto/report/reportinstance-execute-method
  methods-auto/report/reportinstance-print-method
  methods-auto/report/reportinstance-saveas-method
Learn more about raising events in devenv-raising-events.
## Good practices
 Use the same caption for both reports, set by the properties/devenv-caption-property. This way, all links and action captions that lead to the report match the report itself. This practice also applies to bookmarks linked to a report, since they keep the caption of the original report even if you replace it 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
> Ensure that if a report is called on code, you use a compatible report to replace it to avoid runtime errors.
## Related information
methods-auto/report/report-data-type
devenv-subscribing-to-events
devenv-events-in-al
methods-auto/report/report-getsubstitutereportid-method
Get started with AL<devenv-get-started>

Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-substituting-reports, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact. https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-substituting-reports/
