Docentric Basic Report Execution Hooks Overview

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 building and 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. When opens the main() method of the PRM class is invoked. This will result in opening the report dialog form and afterwards printing the report.

The wizard generates most methods that can be overridden along with basic APIs and examples of use.

A sample Data Source Provider (DSP) class generated by the wizard:

A sample Print Report Manager (PRM) class generated by the wizard:

Data Source Provider (DSP) class

In a Data Source Provider (DSP) class we can override the following methods:

generateXmlDataSource()
Use Record Builder to build the report data source by simply traversing through the data needed for the report and adding them to Record Builder as (calculated) records, (calculated) fields, field groups, display (parameterless) methods, etc. Example of use:

protected void generateXmlDataSource(DocXmlRecordBuilder _recordBuilder)
{
    PurchTable    purchTable;
    PurchLine     purchLine;
    PurchId       selectedPurchId = this.getParameter('PurchId').parmValue();
	
    select firstOnly purchTable where purchTable.PurchId == selectedPurchId;
	
    _recordBuilder.addRecord(purchTable);
    _recordBuilder.addField(fieldStr(PurchTable, PurchId));
    _recordBuilder.addCalculatedField('PurchOrderDate', purchTable.createDate(), "@SYS27900");
    _recordBuilder.addCalculatedFieldSysLbl(
        'Requester', HcmWorker::find(purchTable.Requester).name(), fieldStr(PurchTable, Requester));
    
    while select purchLine where purchLine.PurchId == selectedPurchId && purchLine.IsDeleted == false
    {
        _recordBuilder.addRecord(purchLine);
        _recordBuilder.addField(fieldStr(PurchLine, ItemId));
        _recordBuilder.addDisplayMethod(tableMethodStr(PurchLine, itemName));
        _recordBuilder.addField(fieldStr(PurchLine, LineNumber));
        _recordBuilder.addField(fieldStr(PurchLine, LineAmount));
        _recordBuilder.addFieldGroup(tableFieldGroupStr(PurchLine, Discount)); 
    }
}

protected void generateXmlDataSource(DocXmlRecordBuilder _recordBuilder)

{

PurchTable purchTable;

PurchLine purchLine;

PurchId selectedPurchId = this.getParameter('PurchId').parmValue();

select firstOnly purchTable where purchTable.PurchId == selectedPurchId;

_recordBuilder.addRecord(purchTable);

_recordBuilder.addField(fieldStr(PurchTable, PurchId));

_recordBuilder.addCalculatedField('PurchOrderDate', purchTable.createDate(), "@SYS27900");

_recordBuilder.addCalculatedFieldSysLbl(

'Requester', HcmWorker::find(purchTable.Requester).name(), fieldStr(PurchTable, Requester));

while select purchLine where purchLine.PurchId == selectedPurchId && purchLine.IsDeleted == false

{

_recordBuilder.addRecord(purchLine);

_recordBuilder.addField(fieldStr(PurchLine, ItemId));

_recordBuilder.addDisplayMethod(tableMethodStr(PurchLine, itemName));

_recordBuilder.addField(fieldStr(PurchLine, LineNumber));

_recordBuilder.addField(fieldStr(PurchLine, LineAmount));

_recordBuilder.addFieldGroup(tableFieldGroupStr(PurchLine, Discount));

}

Learn about writing DSP classes in detail >>

overrideReportRunSettings()
Dynamically changes the report execution settings such as the report output file name, e-mail subject, e-mail body, To email addresses, etc. or replace standard and custom placeholders.

public DocPlaceholderManager overrideReportRunSettings(
    DocReportRunContext _reportRunContext, boolean _replaceStandardPlaceholders = true)
{
    DocPlaceholderManager placeHolderMng;
    
    // -- Change the report caption (e.g. under special conditions..).
    _reportRunContext.parmReportCaption('New report caption');

    // -- Change the flag for saving the reprot to Print Archive.
    _reportRunContext.parmSaveToArchive(true);

    // -- Change the selected template dynamically.
    _reportRunContext.parmTemplateCompanyId('en-us');
    _reportRunContext.parmTemplateLanguageId('usmf');
	
    // (a) If you want to use the default template for the selected company and language:
    _reportRunContext.parmTemplateId('');
    // (b) If you want to specify a particular non-default template for the selected company and language:
    _reportRunContext.parmTemplateId('MyTemplateId');

    // -- Replace all standard placehodlers in the current print destination.
    placeHolderMng = super(_reportRunContext, _replaceStandardPlaceholders);

    // -- Replace the custom placeholders in the current print destination.
    if (_reportRunContext.parmPrintDestination() == DocPrintDestination::Email)
    {
        placeHolderMng.replacePlaceholdersInCurrentPrintDest([['PlaceholderText', 'ABC'], ['PlaceholderNumber', 12345]]);
    }

    // -- Replace the custom placeholder(s) in any print destination.
    DocPlaceholderManager::replacePlaceholder(_reportRunContext.emailPrintDestSettings().parmEmailBody(), 'PlaceholderText', 'ABC');

    // -- Change the current print destination (e.g. under special conditions..).
    _reportRunContext.parmPrintDestination(DocPrintDestination::File);

    // -- Change a print destination settings.
    _reportRunContext.filePrintDestSettings().parmIsCalculatedFilename(false);
    _reportRunContext.filePrintDestSettings().parmOutputFileFormat(DocOutputFileFormat::DOCX);
    _reportRunContext.filePrintDestSettings().parmUseNextFilename(false);
    _reportRunContext.filePrintDestSettings().parmSaveToAttachments(false);
    _reportRunContext.filePrintDestSettings().parmOpenGeneratedDoc(true);
	
    // -- You can use a value stored in a class member within the overriden generateXmlDataSource() method.
    if (storedValueinGenerateXmlDsMethod)
    {
        _reportRunContext.filePrintDestSettings().parmGeneratedDocFilename(@'\\Share\ReportOutputFile_' + storedValueinGenerateXmlDsMethod + '.docx');
    }
    else
    {
        _reportRunContext.filePrintDestSettings().parmGeneratedDocFilename(@'\\Share\ReportOutputFile.docx');
    }

    return placeHolderMng;
}

public DocPlaceholderManager overrideReportRunSettings(

DocReportRunContext _reportRunContext, boolean _replaceStandardPlaceholders = true)

{

DocPlaceholderManager placeHolderMng;

// -- Change the report caption (e.g. under special conditions..).

_reportRunContext.parmReportCaption('New report caption');

// -- Change the flag for saving the reprot to Print Archive.

_reportRunContext.parmSaveToArchive(true);

// -- Change the selected template dynamically.

_reportRunContext.parmTemplateCompanyId('en-us');

_reportRunContext.parmTemplateLanguageId('usmf');

// (a) If you want to use the default template for the selected company and language:

_reportRunContext.parmTemplateId('');

// (b) If you want to specify a particular non-default template for the selected company and language:

_reportRunContext.parmTemplateId('MyTemplateId');

// -- Replace all standard placehodlers in the current print destination.

placeHolderMng = super(_reportRunContext, _replaceStandardPlaceholders);

// -- Replace the custom placeholders in the current print destination.

if (_reportRunContext.parmPrintDestination() == DocPrintDestination::Email)

{

placeHolderMng.replacePlaceholdersInCurrentPrintDest([['PlaceholderText', 'ABC'], ['PlaceholderNumber', 12345]]);

}

// -- Replace the custom placeholder(s) in any print destination.

DocPlaceholderManager::replacePlaceholder(_reportRunContext.emailPrintDestSettings().parmEmailBody(), 'PlaceholderText', 'ABC');

// -- Change the current print destination (e.g. under special conditions..).

_reportRunContext.parmPrintDestination(DocPrintDestination::File);

// -- Change a print destination settings.

_reportRunContext.filePrintDestSettings().parmIsCalculatedFilename(false);

_reportRunContext.filePrintDestSettings().parmOutputFileFormat(DocOutputFileFormat::DOCX);

_reportRunContext.filePrintDestSettings().parmUseNextFilename(false);

_reportRunContext.filePrintDestSettings().parmSaveToAttachments(false);

_reportRunContext.filePrintDestSettings().parmOpenGeneratedDoc(true);

// -- You can use a value stored in a class member within the overriden generateXmlDataSource() method.

if (storedValueinGenerateXmlDsMethod)

{

_reportRunContext.filePrintDestSettings().parmGeneratedDocFilename(@'\\Share\ReportOutputFile_' + storedValueinGenerateXmlDsMethod + '.docx');

}

else

{

_reportRunContext.filePrintDestSettings().parmGeneratedDocFilename(@'\\Share\ReportOutputFile.docx');

}

return placeHolderMng;

}

Learn more about changing the report execution settings >>
Learn more about Print Destination Standard and Custom Placeholders >>

preRunGenerateDS()
Override this method in order to calculate some data that will be used in the this.generateXmlDataSource() and this.overrideReportRunSettings() methods, or to modify parameters for data source generation and report/document execution that are stored in the this.parmParams(), this.parmParamsMailMerge(), and this.parmParamsReporting() methods. This way you can change, e.g. run-time language: this.parmParams().parmDsLanguageId() that affects label translations, data formats, selection of the report template, etc.
postRunGenerateDS()
Override this method in order to perform some post run actions after the document/report data source is generated, i.e. the this.generateXmlDataSource() method is executed.
The this.overrideReportRunSettings() method will be executed next in report execution pipeline.

Print Report Manager (PRM) class

For Print Report Manager (PRM) class we can override the following methods:

main()
You can change the default implementation (below) of the main()method as needed.

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

    docPrintReport = DocPrintReportBase::constructFromArgs(_args);
    docPrintReport.run();
}

public static void main(Args _args)

{

DocPrintReportBase docPrintReport;

docPrintReport = DocPrintReportBase::constructFromArgs(_args);

docPrintReport.run();

}

defineReportId()
Defines Report ID. Example of use:

public str defineReportId() { return 'PrintSalesOrder'; }

1
2
3
4

public str defineReportId()
{
return 'PrintSalesOrder';
}

addParameters()
Defines and initializes the report parameters. Example of use:

public void addParameters()
{    
    // PurchId.
    docReportParameter = DocReportParameter::constructFromEdt(extendedTypeStr(PurchId));
    docReportParameter.parmIsHidden(true);
    this.addParameter(docReportParameter);

    // IncludeSalesTax.
    docReportParameter = DocReportParameter::constructFromEnum(enumStr(boolean), 'IncludeSalesTax');
    docReportParameter.parmLabelId('Include sales tax'); // Use label ID instead of literal string.
    this.addParameter(docReportParameter);
}

public void addParameters()

{

// PurchId.

docReportParameter = DocReportParameter::constructFromEdt(extendedTypeStr(PurchId));

docReportParameter.parmIsHidden(true);

this.addParameter(docReportParameter);

// IncludeSalesTax.

docReportParameter = DocReportParameter::constructFromEnum(enumStr(boolean), 'IncludeSalesTax');

docReportParameter.parmLabelId('Include sales tax'); // Use label ID instead of literal string.

this.addParameter(docReportParameter);

}

validateReportParameters()
Validates the report parameters before the report runs. If the report parameters are not valid, the report will not be executed. Example of use:

public boolean validateReportParameters()
{
    boolean  ret;

    // Retrieve the parameter values.
    date paramDeliveryDateFrom = this.getParameter(#DeliveryDateFrom).parmValue();
    date paramDeliveryDateTo   = this.getParameter(#DeliveryDateTo).parmValue();

    ret = true;

    // Validate the parameters.
    if (paramDeliveryDateFrom != dateNull() && paramDeliveryDateTo != dateNull())
    {
        if (paramDeliveryDateFrom > paramDeliveryDateTo)
        {
            DocGlobalHelper::handleWarning(
                strFmt('Delivery Date From (%1) is greater than Delivery Date To (%2)',
                       paramDeliveryDateFrom, paramDeliveryDateTo));
        }
        ret = false;
    }

    return ret;
}

public boolean validateReportParameters()

{

boolean ret;

// Retrieve the parameter values.

date paramDeliveryDateFrom = this.getParameter(#DeliveryDateFrom).parmValue();

date paramDeliveryDateTo = this.getParameter(#DeliveryDateTo).parmValue();

ret = true;

// Validate the parameters.

if (paramDeliveryDateFrom != dateNull() && paramDeliveryDateTo != dateNull())

{

if (paramDeliveryDateFrom > paramDeliveryDateTo)

{

DocGlobalHelper::handleWarning(

strFmt('Delivery Date From (%1) is greater than Delivery Date To (%2)',

paramDeliveryDateFrom, paramDeliveryDateTo));

}

ret = false;

}

return ret;

}

buildParameterFormControls()
Changes the default rendering of the report parameters on the report dialog form - rendering order, layout, form control properties, etc. Example of use:

protected void buildParameterFormControls(FormBuildGroupControl _parametersParentBuildGroupControl)
{
    FormBuildGroupControl   vendorFormBuildGroupControl;
    FormBuildGroupControl   deliveryDateFormBuildGroupControl;
    FormBuildDateControl    deliveryDateToFormBuildDateControl;

    // -- Group the parameters OrderAccount and InvoiceAccount in a group control.
    vendorFormBuildGroupControl = 
        _parametersParentBuildGroupControl.addControl(FormControlType::Group, 'VendorGroup');
    vendorFormBuildGroupControl.caption("@SYS80105");
    this.buildSingleParameterFormControl(#OrderAccount, vendorFormBuildGroupControl);
    this.buildSingleParameterFormControl(#InvoiceAccount, vendorFormBuildGroupControl);

    // -- Group the parameters DeliveryDateFrom and DeliveryDateTo in a group control with two columns.
    deliveryDateFormBuildGroupControl = 
        _parametersParentBuildGroupControl.addControl(FormControlType::Group, 'DeliveryDateGroup');
    deliveryDateFormBuildGroupControl.columns(2);
    deliveryDateFormBuildGroupControl.caption("@SYS16056");
    this.buildSingleParameterFormControl(#DeliveryDateFrom, deliveryDateFormBuildGroupControl);

    // -- Change the properties of the FormBuildDateControl.
    deliveryDateToFormBuildDateControl = 
        this.buildSingleParameterFormControl(#DeliveryDateTo, deliveryDateFormBuildGroupControl);
    deliveryDateToFormBuildDateControl.dateSeparator(DateSeparator::Dot);

    // -- Change the right margin of the Parameter (parent) group.
    _parametersParentBuildGroupControl.rightMargin(10);
}

protected void buildParameterFormControls(FormBuildGroupControl _parametersParentBuildGroupControl)

{

FormBuildGroupControl vendorFormBuildGroupControl;

FormBuildGroupControl deliveryDateFormBuildGroupControl;

FormBuildDateControl deliveryDateToFormBuildDateControl;

// -- Group the parameters OrderAccount and InvoiceAccount in a group control.

vendorFormBuildGroupControl =

_parametersParentBuildGroupControl.addControl(FormControlType::Group, 'VendorGroup');

vendorFormBuildGroupControl.caption("@SYS80105");

this.buildSingleParameterFormControl(#OrderAccount, vendorFormBuildGroupControl);

this.buildSingleParameterFormControl(#InvoiceAccount, vendorFormBuildGroupControl);

// -- Group the parameters DeliveryDateFrom and DeliveryDateTo in a group control with two columns.

deliveryDateFormBuildGroupControl =

_parametersParentBuildGroupControl.addControl(FormControlType::Group, 'DeliveryDateGroup');

deliveryDateFormBuildGroupControl.columns(2);

deliveryDateFormBuildGroupControl.caption("@SYS16056");

this.buildSingleParameterFormControl(#DeliveryDateFrom, deliveryDateFormBuildGroupControl);

// -- Change the properties of the FormBuildDateControl.

deliveryDateToFormBuildDateControl =

this.buildSingleParameterFormControl(#DeliveryDateTo, deliveryDateFormBuildGroupControl);

deliveryDateToFormBuildDateControl.dateSeparator(DateSeparator::Dot);

// -- Change the right margin of the Parameter (parent) group.

_parametersParentBuildGroupControl.rightMargin(10);

}

modifyParameterFormBuildControls()
Modifies form controls on the report dialog form bound to the report parameters. Use this method if the form controls' methods such as lookup() or modified() have to be overridden. Example of use:

protected void modifyParameterFormBuildControls(FormBuildGroupControl _parametersParentBuildGroupControl)
{
    FormBuildStringControl fbscOrderAccount;

    super(_parametersParentBuildGroupControl);

    // Override the lookup() method of the form control bound to the OrderAccount parameter.
    fbscOrderAccount = this.getParameterFormBuildControl(#OrderAccount);
    fbscOrderAccount.registerOverrideMethod(methodStr(FormStringControl, lookup),
                                            methodStr(DocPrintPurchOrderListPrintReport, OrderAccount_lookup),
                                            this);

    // Override the modified method() of the form control bound to the OrderAccount parameter.
    fbscOrderAccount = this.getParameterFormBuildControl(#OrderAccount);
    fbscOrderAccount.registerOverrideMethod(methodStr(FormStringControl, modified),
                                            methodStr(DocPrintPurchOrderListPrintReport, OrderAccount_modified),
                                            this);
}

public void OrderAccount_modified(FormStringControl _fscOrderAccount)
{
    FormStringControl fscInvoiceAccount;

    _fscOrderAccount.modified();

    // Write selected value to the InvoiceAccount form control.
    fscInvoiceAccount = this.getParameterFormControl(#InvoiceAccount);
    fscInvoiceAccount.text(_fscOrderAccount.valueStr());
}

public void OrderAccount_lookup(FormStringControl _fscOrderAccount)
{
    SysTableLookup          sysTableLookup  = SysTableLookup::newParameters(tablenum(VendTable), _fscOrderAccount);
    Query                   query           = new Query();
    QueryBuildDataSource    qbds;

    sysTableLookup.addLookupfield(fieldStr(VendTable, AccountNum), true);
    sysTableLookup.addLookupMethod(tableMethodStr(VendTable, name));
    sysTableLookup.addLookupMethod(tableMethodStr(VendTable, countryRegionName));
    sysTableLookup.setLabel('Country');
	
    qbds = query.addDataSource(tablenum(VendTable));
    qbds.addSortField(fieldStr(VendTable, AccountNum));
	
    sysTableLookup.parmQuery(query);
    sysTableLookup.performFormLookup();
}

protected void modifyParameterFormBuildControls(FormBuildGroupControl _parametersParentBuildGroupControl)

{

FormBuildStringControl fbscOrderAccount;

super(_parametersParentBuildGroupControl);

// Override the lookup() method of the form control bound to the OrderAccount parameter.

fbscOrderAccount = this.getParameterFormBuildControl(#OrderAccount);

fbscOrderAccount.registerOverrideMethod(methodStr(FormStringControl, lookup),

methodStr(DocPrintPurchOrderListPrintReport, OrderAccount_lookup),

this);

// Override the modified method() of the form control bound to the OrderAccount parameter.

fbscOrderAccount = this.getParameterFormBuildControl(#OrderAccount);

fbscOrderAccount.registerOverrideMethod(methodStr(FormStringControl, modified),

methodStr(DocPrintPurchOrderListPrintReport, OrderAccount_modified),

this);

}

public void OrderAccount_modified(FormStringControl _fscOrderAccount)

{

FormStringControl fscInvoiceAccount;

_fscOrderAccount.modified();

// Write selected value to the InvoiceAccount form control.

fscInvoiceAccount = this.getParameterFormControl(#InvoiceAccount);

fscInvoiceAccount.text(_fscOrderAccount.valueStr());

}

public void OrderAccount_lookup(FormStringControl _fscOrderAccount)

{

SysTableLookup sysTableLookup = SysTableLookup::newParameters(tablenum(VendTable), _fscOrderAccount);

Query query = new Query();

QueryBuildDataSource qbds;

sysTableLookup.addLookupfield(fieldStr(VendTable, AccountNum), true);

sysTableLookup.addLookupMethod(tableMethodStr(VendTable, name));

sysTableLookup.addLookupMethod(tableMethodStr(VendTable, countryRegionName));

sysTableLookup.setLabel('Country');

qbds = query.addDataSource(tablenum(VendTable));

qbds.addSortField(fieldStr(VendTable, AccountNum));

sysTableLookup.parmQuery(query);

sysTableLookup.performFormLookup();

}

modifyPrintSettings_PrePrompt()
Modifies the report execution settings before the report prompts, i.e. before the report dialog form is shown. Use this method if the default values of settings and parameters depend on values saved with the LastValue framework. Otherwise, the default values of the report parameters should be set in the addParameters() method. Example of use:

public void modifyPrintSettings_PrePrompt()
{
    // Select a special date as a default value for the parameters DeliveryDateFrom and DeliveryDateTo
    // if the selected vendor from LastValue is from USA (before the report dialog form is shown).
    VendAccount paramOrderAccountDefaultValue = this.getParameter(#OrderAccount).parmDefaultValue();

    if (VendTable::find(paramOrderAccountDefaultValue).countryRegionId() == 'USA')
    {
        this.getParameter(#DeliveryDateFrom).parmDefaultValue(systemDateGet() - 30);
        this.getParameter(#DeliveryDateTo).parmDefaultValue(systemDateGet());
    }
}

public void modifyPrintSettings_PrePrompt()

{

// Select a special date as a default value for the parameters DeliveryDateFrom and DeliveryDateTo

// if the selected vendor from LastValue is from USA (before the report dialog form is shown).

VendAccount paramOrderAccountDefaultValue = this.getParameter(#OrderAccount).parmDefaultValue();

if (VendTable::find(paramOrderAccountDefaultValue).countryRegionId() == 'USA')

{

this.getParameter(#DeliveryDateFrom).parmDefaultValue(systemDateGet() - 30);

this.getParameter(#DeliveryDateTo).parmDefaultValue(systemDateGet());

}

modifyPrintSettings_PreRun()
Modifies the report execution settings before the report runs. Use this method if you want to use the display string value of a report parameter instead of its value (e.g. the vendor name instead of VendAccount), to change the selected print destination or template, to set the report parameter value, etc. Example of use:

protected void modifyPrintSettings_PreRun()
{
    DocReportParameter orderAccountParam = this.getParameter(#OrderAccount);

    // Use the display string value of the OrderAccount parameter instead of its value:
    // - in the Parameters Data Section of the report data source
    // - if the standard placeholder %PARAMETER_OrderAccount% is used (and replaced) in the print destinations
    //   in the overrideReportRunSettings() method of the Data Source Provider class.
    orderAccountParam.parmUseDisplayValueStr(true);
    if (orderAccountParam.parmValue())
    {
        orderAccountParam.parmDisplayValueStr(VendTable::find(orderAccountParam.parmValue()).name());
    }
}

protected void modifyPrintSettings_PreRun()

{

DocReportParameter orderAccountParam = this.getParameter(#OrderAccount);

// Use the display string value of the OrderAccount parameter instead of its value:

// - in the Parameters Data Section of the report data source

// - if the standard placeholder %PARAMETER_OrderAccount% is used (and replaced) in the print destinations

// in the overrideReportRunSettings() method of the Data Source Provider class.

orderAccountParam.parmUseDisplayValueStr(true);

if (orderAccountParam.parmValue())

{

orderAccountParam.parmDisplayValueStr(VendTable::find(orderAccountParam.parmValue()).name());

}

printReportCompleted()
Implement if a specific action is needed when printing the report is completed.
printReportCanceled()
Implement if a specific action is needed when printing the report is canceled.

We can also override the collectParameterValues(), printReportFormRun_PostInit(), printReportFormRun_PostRun(), setControlValuesForReportParameters(), etc. methods. Descriptions and the purpose of the methods can be found in the code.

CONTENTS

Docentric Basic Report Execution Hooks Overview

IN THIS ARTICLE

Data Source Provider (DSP) class

Print Report Manager (PRM) class

See also

IN THIS ARTICLE