Skip to main content
Dynamics 365
·
6 min read

Report Execution Insights

With the release of Microsoft Dynamics NAV 2015, the way reports are executed has changed. In Microsoft Dynamics NAV 2015, reports can use a built-in RDLC layout (as before), a built-in Word layout, or a custom layout, which can be based on RDLC or Word. Built-in layouts are part of the report object, while custom layouts are stored in table 9650 Custom Report Layout of the database. The new behavior relies on a few new functions in codeunit 1. Additionally, Microsoft Dynamics NAV 2015 introduces the capability to schedule a report for execution later. This functionality also relies on codeunit 1 triggers, as well as a few new C/AL functions.

Report Execution

This section explains what happens behind the scenes when a report is executed. A report is executed when any of the following happen:

  • From the client, a user chooses Preview, Print, or Microsoft Excel, Microsoft Word, or PDF on the report request page.
  • C/AL code executes the following functions:
    • RUN or RUNMODAL without a request page.
    • SAVEAS, SAVEASEXCEL, SAVEASPDF, SAVEASWORD, or SAVEASXML.

Report Execution Flow

The following figure illustrates the sequence of interactions between the platform and codeunit 1 functions when a report is executed.

  1. The report execution calls the HASCUSTOMLAYOUT function in codeunit 1 to determine whether the particular report is currently set up to use a custom RDLC or custom Word layout.

    If the report does not use a custom layout (that is, the function result is 0), then the report will use the default built-in layout, which can be either RDLC or Word as specified by the DefaultLayout property of the report object.

    Note: This is function is called before the request page is shown to the user because some of the Print button options on the request page depend on whether the report uses and RDLC layout or Word layout.

  2. If the report is set up to use a custom Word layout or a built-in Word layout, then the MERGEDOCUMENT function is called to handle the report execution.
  3. If the report is set up to use a custom RDLC layout, then the REPORTGETCUSTOMRDLC function is called to handle the report execution. The function returns the custom RDLC in a text string as XML. 

Word Report Layout Execution

The execution of reports that use Word layouts consists of two parts: design time and run time.

  • Design time

To enable the user to map report dataset fields to the Word document that defines the layout, the system must generate an XML document (schema) that can be imported into Word. This XML document is generated by the REPORT.WORDXMLPART function. You must use Word 2013 (or later) for XML mapping. However, you can use Word 2010 for basic editing of the layout, such as changing font type or size.

  • Run time

When report is executed, the report data output is merged with the Word layout to produce the final report. The report data output is in XML format which has the same form as the output of the REPORT.SAVEASXML function. The merge operation uses the .NET Framework assembly Microsoft.Dynamics.Nav.DocumentReport. The merge operation happens on the Microsoft Dynamics NAV Server and it uses additional.NET Framework components, such as Open XML SDK 2.5. Word is not required on the computer that is running Microsoft Dynamics NAV Server. If the user has requested to view the report as a PDF document, then the Word document is converted from a .docx file type to a .pdf file type by the .NET Framework assembly Microsoft.Dynamics.Nav.PdfWriter.WordToPdf.

The following figure illustrates the different components that are involved in the Word layout authoring and merging:

 

As mentioned in the previous section, the Word layout documents are handled by the following function in codeunit 1:

MergeWordLayout(

  ReportID:Integer;

  ReportAction:SaveAsPdf,SaveAsWord,SaveAsExcel,Preview,Print’;

  InStrXmlData:InStream;

  FileName:Text);

As you can see, the function has to handle all report actions, including printing. Although SaveAsExcel is included in the code, a function call with this parameter will result in an error message that states that this function is not available.

Note: FileName is used for SaveAsPdf and SaveAsWord. However, it is also used for server-side printing, in which case, it specifies the name of the server-side printer. Client-side printing is done through Word.

Report Scheduling

In Microsoft Dynamics NAV 2015, a report can be scheduled for executing later from the Job Queue. This functionality relies on a new codeunit 1 function and a set of new C/AL functions that support the delayed report execution. When a report is run from the client, it can be run by calling either the RUN or RUNMODAL function. The RUNMODAL function is used when the system expects the report to be executed in the current context, in other words, when the results are needed immediately. This is the case, for example, with the Copy Document action that is invoked from a new sales order. Reports that are executed by the RUNMODAL function cannot be scheduled. The user can only schedule reports that are executed by the RUN function.

It is important to note that most document reports are run by using the Report Selection feature, which uses the RUNMODAL command to execute reports in sequence. Therefore, when printing, for example, a Sales Invoice, the user will not see a Schedule option on the report request page. However, if the Sales Invoice report is run directly from Object Designer in the development environment, the request page will include the Schedule option, as illustrated in the following figure.

 

When the user chooses Schedule on the request page, the report is not executed immediately. Instead, the codeunit 1 function ReportScheduler@79(ReportId:Integer;RequestPageXml:Text):Boolean is called, where the ReportId parameter specifies the report’s ID and the RequestPageXml parameter specifies the request page parameters as an XML string. This function creates a new record in table 472 Job Queue Entry where it stores the RequestPageXml parameter value (the Job Queue Category Code field is left blank). Before the function inserts the new record in the Job Queue Entry table, page 682 Schedule a Report opens in the client and enables the user to choose the report output type and when to run the report. The following figure illustrates an example of the Schedule a Report page for the report 111 Customer Top 10.

Report Inbox

After the Job Queue processes an entry for a report, if the output type is Word, Excel, or PDF, the Job Queue will create an entry for the report in table 477 Report Inbox table. In the client, the entry will appear in the user’s Role Center in the Report Inbox part. Because there is only one Report Inbox table, which is shared by all users, the Report Inbox part is filtered on the user’s ID.

C/AL Functions Used by Job Queue for Reports

When the Job Queue processes the report request, it uses on the following new C/AL functions:

  • REPORT.SAVEAS(ReportID,RequestPageXml,ReportFormat::Pdf,OutStr [,RecRef]);
    • This function is a more general version of the SAVEASPDF function, for example. The RequestPageXml parameter specifies a string of request page parameters as XML. The ReportFormat parameter specifies the output file type as PDF, Excel, Word, or XML.
    • It stores the report to an outstream, so there is no need for an intermediate file on the server.
    • It accepts an optional parameter of type RecordRef, in case you want to run the report on a specific record, such as a sales invoice header.
  • REPORT.EXECUTE(ReportID,RequestPageXml [,RecRef]);
    • This function is used to execute processing-only reports (batch jobs), which do not have an output.
  • REPORT.PRINT(ReportID,RequestPageXml,PrinterName [,RecRef]);
    • This function prints the report to a specified printer.
    • Printing reports from the Job Queue occurs on the computer that is running Microsoft Dynamics NAV Server. Any printers that you want to use for printing reports must be set up server computer for login account that is used by the Microsoft Dynamics NAV Server instance.
    • To schedule a report to print, on the Schedule a Report page, the user sets the Report Output Type field to Print, and then selects the Printer Name field to choose the printer from a list of server printers. The list includes the printers that are set up for the login account on the Microsoft Dynamics NAV Server computer. If the default printer on the user’s computer matches a printer on the server computer, then that printer is automatically selected in the list. If the Printer Name field is left blank, then the default printer on the server computer is used.

Important: We do not recommend that you set up print-to-file drivers (such as Microsoft XPS Document Writer or PDF printer) on the server computer because using them to print reports can block the Job Queue. Microsoft Dynamics NAV cannot distinguish between print-to-file drivers and physical printers. If the user selects a print-to-file driver, the driver will open a file dialog box on the server computer, which will stop the printer job on the server and subsequently block the Job Queue. Eventually (perhaps after several hours), the Job Queue will time out and continue.

  • RequestPageXml:= REPORT.RUNREQUESTPAGE(ReportID [,RequestPageXml]).
    • This function opens the report request page that includes the OK and Cancel buttons, but does not run the report. It returns an XML string that contains the request page parameters that are entered on the request page. If you want to edit previously stored request page data, you can supply the old data as an optional parameter. 
navteam

Related posts