How to Run a Report in the Context of an Underlying Entity

The needed artifacts for each Basic report are:

Data Source Provider (DSP) class which provides the report data; it also enables changing the report execution settings (e.g. Selected Template, Selected Print Destination, etc.) and Print Destination Placeholders handling dynamically, i.e. during report execution.
Print Report Manager (PRM) class which defines Report ID and the report parameters, handles report execution from opening the report dialog form to printing the report to a selected print destination.
Report Menu Item which points to the report Print Report Manager (PRM) class.

Report Execution Context table

The underlying entity of an executing report is a record of a so called Report Execution Context table, e.g. PurchTable that is currently selected when the report runs.

The Report Execution Context table for a report can be accessed and used:

In all methods of a Data Source Provider (DSP) class that we can override, e.g. the generateXmlDataSource()
method which builds a report data source.
In all methods of a Print Report Manager (PRM) class that we can override, e.g. the validateReportParameters() method which validates the entered report parameters before report execution.

Learn more about these methods here.

A Report Execution Context table is also important if we want to save a report to this table’s Attachments after the report is printed. For that purpose we can use the improved Docentric File print destination.

Report Menu Item is an Action menu item which points to the report Print Report Manager (PRM) class. When we open the Report Menu Item the main() method of the PRM class is invoked. This will result in opening the report dialog form and afterwards printing the report.

We can include Report Menu Item in an arbitrary form and use one of Form Data Sources as its Data Source. This is the easiest way to set the underlying entity of an executing report, i.e. the Report Execution Context table.

The Report Menu Item label becomes the report caption when the report is executed. The report caption is used as the caption of the report dialog form and is also used for the default output file and email attachment name creation.

Setting the Report Execution Context table through the code

We can also set the Report Execution Context table of a report from the code.

Take a look at the sample main() method of the PRM class of a Basic report, which always prints a particular purchase order, e.g. the one that fulfills certain specific conditions.

public static void main(Args _args)
{
    DocPrintReportBase    docPrintReport;
    PurchTable            purchTable;

    // Instance the DocPrintReport class for the report.
    docPrintReport = DocPrintReportBase::constructFromArgs(_args);

    // Assume that we want to run this report for some specific purchase order.
    select firstOnly purchTable where purchTable.PurchId == '000002';
    
    // Set the Report Execution Context table.
    docPrintReport.setReportExecutionContextRecord(purchTable);
    
    // Set the parameter value for the hidden parameter PurchId.
    docPrintReport.setParameterValue('PurchId', purchTable.PurchId);

    // Show the print report form and execute the report.
    docPrintReport.run();
}

public static void main(Args _args)

{

DocPrintReportBase docPrintReport;

PurchTable purchTable;

// Instance the DocPrintReport class for the report.

docPrintReport = DocPrintReportBase::constructFromArgs(_args);

// Assume that we want to run this report for some specific purchase order.

select firstOnly purchTable where purchTable.PurchId == '000002';

// Set the Report Execution Context table.

docPrintReport.setReportExecutionContextRecord(purchTable);

// Set the parameter value for the hidden parameter PurchId.

docPrintReport.setParameterValue('PurchId', purchTable.PurchId);

// Show the print report form and execute the report.

docPrintReport.run();

}

CONTENTS

How to Run a Report in the Context of an Underlying Entity

IN THIS ARTICLE

Report Execution Context table

Setting the Report Execution Context table through the Report Menu Item

Setting the Report Execution Context table through the code

See also

IN THIS ARTICLE