{"title":"Obsoleting reports","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-reports-obsoletion/","by":"JOP-AL","license":"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-reports-obsoletion, 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.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-reports-obsoletion","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn how to obsolete Business Central reports.","date":"2025-03-13","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Obsoleting reports","slug":"obsoleting-reports","at":0,"chars":8209},{"level":2,"title":"How to communicate report deprecation to developers","slug":"how-to-communicate-report-deprecation-to-developers","at":498,"chars":1053},{"level":2,"title":"How to communicate report obsoletion to users: Tell-me search results","slug":"how-to-communicate-report-obsoletion-to-users-tell-me-search-results","at":1551,"chars":1243},{"level":2,"title":"How to communicate report deprecation to users: The request page","slug":"how-to-communicate-report-deprecation-to-users-the-request-page","at":2794,"chars":1537},{"level":2,"title":"How to communicate report deprecation to users: The help pane for the request page","slug":"how-to-communicate-report-deprecation-to-users-the-help-pane-for-the-request-page","at":4331,"chars":1287},{"level":2,"title":"How to communicate report obsoletion to users: The Report Layouts page","slug":"how-to-communicate-report-obsoletion-to-users-the-report-layouts-page","at":5618,"chars":1697},{"level":2,"title":"Tracking usage of a deprecated report or layout","slug":"tracking-usage-of-a-deprecated-report-or-layout","at":7315,"chars":707},{"level":2,"title":"Related information","slug":"related-information","at":8022,"chars":187}],"text":"# Obsoleting reports\nIf you plan to deprecate reports in your Marketplace apps or per-tenant extensions, you might want to communicate the deprecation to other developers and to your users before you remove the reports.\n> NOTE\n> The article describes some best practices that Microsoft uses for obsoleting reports and layouts, and is meant as a nonenforced guidance and best practices. You can use this article as inspiration for how to set up your own best practices for deprecating your reports.\n## How to communicate report deprecation to developers\nThe report object supports the following properties for deprecations:\n ObsoleteReason\n ObsoleteTag\n ObsoleteState\nUse these properties to communicate why and when the report is deprecated. With compiler preprocessor statements and preprocessor symbols, you can even write code that caters for the different deprecation stages in a uniform way. Starting in 2025 release wave 1 (runtime 15), you can define the obsoletion properties at the layout level. When these properties are set, the layout appears as deprecated on the Report Layouts page in the Business Central client.\n```al\n// Example of how to set obsoletion properties on a report\nreport 50100 MyReport\n{\n#if Version3\n    ObsoleteState = Removed;\n    ObsoleteTag = '19.0';\n#else\n    ObsoleteState = Pending;\n    ObsoleteTag = '16.0';\n#endif\n    ObsoleteReason = 'The MyReport has been replaced by MyReport2.';\n}\n#endif\n```\nTo learn more about the guidelines, go to Best practices for deprecation of AL code<devenv-deprecation-guidelines>.\n## How to communicate report obsoletion to users: Tell-me search results\nThe Tell-Me search in Business Central uses the report caption and the search terms defined in the report object to find reports that match search criteria. Tell-Me search results also display the report caption. You can use the caption to communicate the upcoming change when people use Tell-Me.\nYou can gradually introduce more severe warning texts by using compiler preprocessor statements and preprocessor symbols.\n```al\nreport 50100 MyReport\n{\n    // Other report properties here ...\n\n    // Consider adding obsolete to the caption\n    // This will help users to identify the report as obsolete when they use Tell-me search\n    // and when they open the request page for the report.\n\n    #if Version3\n        Caption = 'MyReport (Now removed)';\n    #else\n        #if Version2\n            Caption = 'MyReport (Obsolete. Will soon be removed)';\n        #else\n            #if Version1\n                Caption = 'MyReport (Obsolete)';\n            #else\n                Caption = 'MyReport';\n            #endif\n        #endif\n    #endif\n\n    // Consider adding explicit search terms\n    AdditionalSearchTerms = 'Obsolete, Deprecated';\n\n    // More report here ...\n}\n```\n## How to communicate report deprecation to users: The request page\nThe request page in Business Central displays the following report elements from the report object:\n Report Caption\n AboutTitle\n AboutText\n Layout Caption\nYou can use any of these properties to communicate the upcoming change to people who run reports through the request page.\n```al\nreport 50100 MyReport\n{\n    // Other report properties here ...\n\n    // Consider adding obsolete to the caption\n    // This will help users to identify the report as obsolete when running the report through the request page.\n\n    Caption = 'MyReport (Obsolete)';\n\n    dataset{ ... }\n\n    requestpage\n    {\n        // Consider adding obsolete to the teaching tip properties (AboutTitle and AboutText).\n        // This will help users to identify the report as obsolete if they have teaching tips enabled.\n        // The same information will also be shown in the help pane of the request page.\n\n        AboutTitle = 'About myOldReport (obsolete)';\n        AboutText = 'Teaching tip content. **This report is obsolete and will be removed in the v3 release.**';\n    }\n\n    rendering\n    {\n        layout(myOldLayout)\n        {\n            // Other layout properties here...\n\n            // Consider adding obsolete to the layout caption\n            // This will help users to identify the layout as obsolete when they use the request page.\n            // The same information will also be shown on the Report Layouts page.\n\n            Caption = 'MyOldLayout (Obsolete)';\n        }\n}\n```\n## How to communicate report deprecation to users: The help pane for the request page\nThe Help pane for the request page in Business Central displays the following report elements from the report object:\n AboutTitle\n AboutText\n ContextSensitiveHelpPage\nYou can use any of these properties to communicate the upcoming change to people who have the Help pane open when the request page displays.\n```al\nreport 50100 MyReport\n{\n\n    // Other report properties here ...\n\n    dataset{ ... }\n\n    requestpage\n    {\n        // Consider adding obsolete to the teaching tip properties\n        // This will help users to identify the report as obsolete if they have teaching tips enabled.\n        // The same information will also be shown in the help pane of the request page.\n\n        AboutTitle = 'About myOldReport (obsolete)';\n        AboutText = 'Teaching tip content. **This report is obsolete and will be removed in the v26 release.**';\n\n        // Consider updating your documentation for the report:\n        //   Mention that the report is obsolete and will be removed in the v26 release\n        //   Explain which alternative reports or features that users can use instead of this report.\n\n        ContextSensitiveHelpPage = 'report-50100';\n    }\n\n    // More report code here ...\n}\n```\n## How to communicate report obsoletion to users: The Report Layouts page\nThe Report Layouts page in Business Central displays the following report elements from the report object:\n Report Caption\n Layout Caption\n Layout Summary\n Layout ObsoleteReason, ObsoleteState, and ObsoleteTag (introduced in 2025 release wave 1 (runtime 15))\nYou can use any of these properties to communicate the upcoming change to people who open the Help pane for the request page.\n```al\nreport 50100 MyReport\n{\n    // Other report properties here ...\n\n    // Consider adding obsolete to the caption\n    // This will help users to identify the report as obsolete when they use Tell-me search\n    // and when they open the request page for the report.\n\n    Caption = 'MyReport (Obsolete)';\n\n    dataset{ ... }\n\n    requestpage{ ... }\n\n    rendering\n    {\n        layout(myOldLayout)\n        {\n            // Other layout properties here...\n\n            // Consider adding obsolete to the layout caption\n            // This will help users to identify the layout as obsolete when they use the request page.\n            // The same information will also be shown on the Report Layouts page.\n\n            Caption = 'MyOldLayout (Obsolete)';\n\n            // Consider adding obsolete text to the layout description\n            // This will be shown on the Report Layouts page.\n\n            Summary = 'MyOldLayout is used for showing data about XYZ. **Note that this layout is obsolete and will be removed in the v2 release**';\n\n            ObsoleteReason = 'This layout is obsolete and will be removed in the v28 release';\n            ObsoleteState = Pending;\n            ObsoleteTag = 'myObsoleteLayoutTag';\n\n        }\n}\n```\n## Tracking usage of a deprecated report or layout\nReport telemetry gathers data about which, and when, reports are run in environments. Among many other details, it provides information about who ran the report, which layout was used, and how the output was consumed. For example, whether the reports were printed, previewed, or downloaded.\nTenant administrators and app publishers can use this data to gather statistics on report and layout use. The information lets you communicate to organizations and users that they're using reports or layouts that won't be unavailable in the future.\nTo learn more about the data provided, go to Analyzing report telemetry<../administration/telemetry-reports-trace>.\n## Related information\ndevenv-multiple-report-layouts#obsoleting-layouts\nBest practices for deprecation of AL code<devenv-deprecation-guidelines>\n../administration/telemetry-reports-trace"}