{"title":"Report Triggers and Runtime Operations","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-report-triggers/","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-report-triggers, 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-report-triggers","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":"Report triggers in AL for Business Central.","date":"2021-05-17","meta":{"topic":"reference"},"outline":[{"level":1,"title":"Report Triggers and Runtime Operations","slug":"report-triggers-and-runtime-operations","at":0,"chars":13390},{"level":2,"title":"Overall report trigger and operations","slug":"overall-report-trigger-and-operations","at":547,"chars":2690},{"level":3,"title":"#tab/current","slug":"tabcurrent","at":838,"chars":125},{"level":3,"title":"#tab/legacy","slug":"tablegacy","at":963,"chars":1112},{"level":3,"title":"How data items are processed","slug":"how-data-items-are-processed","at":2075,"chars":1162},{"level":2,"title":"<a name=requestpage></a> Request page and preview triggers and operations","slug":"a-namerequestpagea-request-page-and-preview-triggers-and-operations","at":3237,"chars":6699},{"level":3,"title":"Request page preview modes","slug":"request-page-preview-modes","at":3800,"chars":2012},{"level":4,"title":"How the mode is set","slug":"how-the-mode-is-set","at":5407,"chars":405},{"level":3,"title":"Visible and head-less request page flows","slug":"visible-and-head-less-request-page-flows","at":5812,"chars":1894},{"level":3,"title":"Detailed child instance triggers and operations in multiple-preview mode","slug":"detailed-child-instance-triggers-and-operations-in-multiple-preview-mode","at":7706,"chars":2230},{"level":2,"title":"Report layout flow","slug":"report-layout-flow","at":9936,"chars":583},{"level":3,"title":"RDLC layouts<#tab/rdlc>","slug":"rdlc-layoutstabrdlc","at":9958,"chars":281},{"level":3,"title":"Word layouts<#tab/word>","slug":"word-layoutstabword","at":10239,"chars":280},{"level":2,"title":"Key design guidelines and considerations","slug":"key-design-guidelines-and-considerations","at":10519,"chars":2642},{"level":3,"title":"Multiple-preview mode","slug":"multiple-preview-mode","at":10563,"chars":2163},{"level":3,"title":"General","slug":"general","at":12726,"chars":435},{"level":2,"title":"Related information","slug":"related-information","at":13161,"chars":229}],"text":"# Report Triggers and Runtime Operations\nThis article describes the triggers and operations that are executed when a report is run. The triggers and operations will depend on a few things, like:\n Whether the report has request page\n What action the user takes on the request page, like preview, print, and schedule\n What preview mode the report uses\nSome triggers are invoked in the report, while others are invoked on the request page. Understanding the sequence of the triggers and operations will help you design reports that work as expected.\n## Overall report trigger and operations\nFor starters, look at the following diagram that illustrates the general overall flow when a report is invoked. The flow is broken down even further in the next section<#requestpage>, which discusses triggers and operations related to request pages.\n### #tab/current\nThe following figure illustrates the general report trigger flow for Business Central version 26 and later.\n### #tab/legacy\nThe following figure illustrates the general report trigger flow for Business Central version 19 and earlier.\n<https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/media/report-triggers-complete-flow.png#lightbox>\nWhen you start the report run, the triggers-auto/report/devenv-oninitreport-report-trigger is called. If the OnInitReport doesn't end the processing of the report, then the request page for the report is run, if one is enabled. The page triggers for the request page are called. On the request page, you select the options that you want for this report. You can also decide to cancel the report run. If you decide to continue, then the triggers-auto/report/devenv-onprereport-report-trigger is called. At this point, no data has yet been processed. When the OnPreReport trigger has been run, the first data item is processed unless the processing of the report was ended in the OnPreReport trigger.\n> TIP\n> For more information about the print triggers and operations, see Developing Printer Extensions in Business Central<devenv-reports-printing#overview>.\n### How data items are processed\nData items are processed one after the other, each in the same way. When there are no more data items, the triggers-auto/report/devenv-onpostreport-report-trigger is called to do any necessary post processing, for example, removing temporary files.\nThe process for each data item is as follows:\n1. Before the first record is retrieved, the triggers-auto/reportdataitem/devenv-onpredataitem-reportdataitem-trigger is called.\n2. Data item records are processed one at a time.\n Processing a record involves executing the record triggers and outputting data. After a record is retrieved from the data item, the OnAfterGetRecord (Data Items) Trigger<triggers-auto/reportdataitem/devenv-onaftergetrecord-reportdataitem-trigger> is called.\n If there's an indented data item, its records are also processed. After the last record in the indented data item, the control returns to the point from which processing was started. In the case, it's the next record of the data item on the next highest level.\n3. After the last record has been processed, the triggers-auto/reportdataitem/devenv-onpostdataitem-reportdataitem-trigger is called.\n## <a name=requestpage></a> Request page and preview triggers and operations\nThe section outlines the triggers and operations that are related to the report request page and report preview. The following diagram illustrates the main trigger and operation sequence. The focus is on the triggers and actions related to the request page invocation and button actions. See the sections that follow for details about some of the concepts shown.\n<https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/media/report-trigger-main-flow.png#lightbox>\n### Request page preview modes\nRequest pages can invoke the preview window in two different modes: preview & close and multiple-preview. The mode will affect the report behavior, depending on the trigger implementation in the current report. The following table describes the two preview modes.\nPreview mode|Description\npreview & close|The preview & close mode is the only mode supported in Business Central 2020 release wave 1 (version 16) and earlier. This mode invokes the preview action within the current report instance, referred to as the primary instance. In this mode, the request page closes when the user previews the report. The user will then have to run the report again if the preview doesn't show the expected result.<br><br>In the client, a request page that uses this mode will include the Preview & Close button.\nmultiple-preview|The multiple-preview mode was introduced in Business Central 2020 release wave 1 (version 17.). It provides users the ability to preview a report multiple times, without closing the request page. When the preview action is selected, the mode first captures the values in the visible request page controls and filters. Then, it invokes a new report instance, referred to as the child instance, to generate the preview document based on the settings. The request page in the original report instance will remain available after the user closes the preview window.<br><br>In the client, a request page that uses this mode will include the Preview button.\nFor more information to help your design, see Key Design Guidelines and Considerations<#multiplepreview>.\n#### How the mode is set\nBy default, reports use the multiple-preview mode. The mode is determined by two report properties: properties/devenv-savevalues-property and properties/devenv-allowscheduling-property, as outlined in the following table:\nSaveValues|AllowSheduling = true|AllowSheduling = false\nSaveValues = true|Multiple-preview|Preview & close\nSaveValues = false|Preview & close|Preview & close\n### Visible and head-less request page flows\nThere are two different request page flows that can be invoked in the process: a visual request page and a head-less request page. The request page flow used will depend on various design factors. Each type has a different trigger sequence.\nThe visual request page flow is used on the request page instance that appears for the user in the client. In this case, the triggers are executed on the primary instance.\nThe head-less request page flow shows the triggers that are executed when a report runs without a visible request page. The head-less flow occurs under the following conditions:\n In the child instance, when a report uses the multiple-preview mode\n When a report is scheduled to run in the background\n When a report is invoked with the request page XML data in the parameter list\n When a report that doesn't have an enabled request page\nThe following diagram highlights the basic trigger sequence for a request page for the two possible request pages.\n<https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/media/report-preview-triggers-full-flow.png#lightbox>\nThe key differences between the two flows are the triggers-auto/requestpageextension/devenv-onaftergetcurrrecord-requestpageextension-trigger and triggers-auto/requestpageextension/devenv-onqueryclosepage-requestpageextension-trigger triggers in the visual flow. Only visible user interface elements are transferred to the child instances through the request page XML data. User interaction triggers, like lookup, validate, and other page triggers, aren't invoked in head-less reports flows.\n> NOTE\n> The GetPrinterName procedure in the diagram isn't an actual AL-enabled trigger. Instead, it's a call from platform to the application code that subscribes to the GetPrinterName event, which will return the selected printer name for the current report.\n### Detailed child instance triggers and operations in multiple-preview mode\nWith multiple-preview mode, a child instance is created off the parent visual request page. The child instance collects data from visual request page, then uses the head-less request page to process data items and build the PDF preview.\nThe new instance will rerun most the report triggers and some request page triggers.\nThe following snippet lists the actual triggers that are invoked when a report is run. It starts from when the user first selects preview, and continues through printing.\n Lines prefixed with ROOT indicate triggers that are run in the primary instance.\n Lines marked with `--PAGE` are triggers invoked from the request page. All other triggers originate from the report object itself.\n Lines prefixed with CHILD indicate triggers that are run in the child instance.\n For simplicity, only one record in each nested data item is shown.\n```\nROOT OnAfterSubstituteReport\nROOT OnInitReport\nROOT OnInit                        --PAGE\nROOT OnAfterHasCustomLayout\nROOT OnAfterGetPrinterName\nROOT OnOpenPage                    --PAGE\nROOT OnAfterGetCurrRecord          --PAGE\n    CHILD OnInitReport             --PAGE\n    CHILD OnInit                   --PAGE\n    CHILD OnOpenPage               --PAGE\n    CHILD OnClosePage              --PAGE\n    CHILD OnPreReport\n    CHILD OnAfterGetPaperTrayForReport\n    CHILD MasterRecord - OnPreDataItem\n        CHILD MasterRecord - OnAfterGetRecord 1\n            CHILD MasterRecordLines - OnPreDataItem\n                CHILD MasterRecordLines - OnAfterGetRecord 101\n            CHILD MasterRecordLines - OnPostDataItem\n        CHILD MasterRecord - OnPostDataItem\n    CHILD OnAfterHasCustomLayout\n    CHILD OnPostReport\n    CHILD OnMergeDocumentReport\nROOT OnQueryClosePage              --PAGE\nROOT OnClosePage                   --PAGE\nROOT OnPreReport\nROOT OnAfterGetPaperTrayForReport\nROOT MasterRecord - OnPreDataItem\n    ROOT MasterRecord - OnAfterGetRecord 1\n        ROOT MasterRecordLines - OnPreDataItem\n            ROOT MasterRecordLines - OnAfterGetRecord 101\n        ROOT MasterRecordLines - OnPostDataItem\nROOT MasterRecord - OnPostDataItem\nROOT OnPostReport\nROOT OnMergeDocumentReport\n```\n## Report layout flow\n### RDLC layouts<#tab/rdlc>\nThe following figure illustrates the flow associated with an RDLC report layout type.\n![RDLC report layout flow for version 20 and later.]<https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/media/rdlc-layout-flow.png#lightbox>\n### Word layouts<#tab/word>\nThe following figure illustrates the flow associated with a Word report layout type.\n![Word report layout flow for version 20 and later.]<https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/media/word-layout-flow.png#lightbox>\n## Key design guidelines and considerations\n### Multiple-preview mode\n Avoid the following implementations:\n   Set global variables in page triggers\n   Use the OnQueryClose page trigger to change global variables in the report\n   Depend on instance methods to be called to set state variables before report invocation\n   The request pages that have SaveValues property set to false.\n  If you have reports that use any of these implementations, refactor them to ensure report content renders as expected.\n> NOTE\n> If a legacy report depends on global variable state, the developer can use a single instance codeunit to transfer variable state between the two running instances. The state is the set in the primary object and read from the child object.\nFor more information about the flow, see Request page and preview triggers and operations<#requestpage>.\n Only visible user interface elements are transferred to the preview in child instances.\n  User interaction triggers from the visible request page, like lookup, validate, and other page triggers, aren't invoked in head-less request page flow in the child instance. Design these triggers so that they don't affect variables that are hidden in the object. See Visible and head-less request page flows<#headless>.\n OnInitReport trigger calls\n  OnInitReport trigger is run when the report initially invoked, and again for every preview of the report in the child instance. This condition, in some cases, can mean that before the report is even executed, the OnInitReport trigger has already run twice. See Detailed child instance triggers and operations in multiple-preview mode<#child>.\n The design of some reports may make it impossible or undesirable to run in the multiple-preview mode.\n  In these cases, the report should run in the preview & close mode. So as a developer, you set the AllowScheduling property to false in the report object declaration. Optionally, you can set the SaveValues property of request page to false, in which case, the mode will revert to preview & close mode. However, this configuration isn't recommended, because it removes the ability to save current settings for later use.\n  See Request Page Preview Modes<#modes>.\n### General\n Defining methods that have the same name in the report and table\n  If you have two methods with the same name, one defined in a report and the other in a table that is referenced by the report, you cannot invoke the method defined in the report directly. By default, a call to the method invokes the method that's defined in the table. This behavior occurs when the method is called from a source expression or a trigger.\n## Related information\ntriggers-auto/report/devenv-oninitreport-report-trigger\nReport data item triggers<triggers-auto/reportdataitem/devenv-onpredataitem-reportdataitem-trigger>\ndevenv-report-object\ntriggers-auto/devenv-triggers"}