How to Use Placeholders in Print Destination Settings

Use of Print Destination Placeholders applies to both Docentric SSRS and Basic reports. We can use Docentric Placeholders in any print destination where it makes sense (Output File Name, Email address, Email Body, etc.). There are two kinds of Docentric Print Destination Placeholders at our disposal – Standard and Custom Placeholders. The main difference is that you can use Standard Placeholders out-of-the-box with no coding.

Print Destination Standard Placeholders

We can use Standard Placeholders without any coding, i.e. without extending any class from Docentric AX Framework.

Standard Placeholders are:

@FIELD_{Name of field of Report Execution Context table}@ -> extract the value of specified field
@METHOD_{Name of method of Report Execution Context table}@ -> extract the value of specified parameterless method, e.g. display method
@PARAMETER_{Name of the report parameter}@ -> extract the value of the specified report parameter
@REPORTID@
@REPORTCAPTION@
@COMPANYID@
@COMPANYNAME@
@USERID@
@USERNAME@
@USERALIAS@
@USEREMAIL@
@WORKER@
@LANGUAGEID@
@TIMESTAMP@
@CURRENTDATE@
@CURRENTDATETIME@
@GUID@
@BATCHJOBID@
@BATCHJOB_SCHEDULED_STARTDATETIME@
@BATCHJOB_ACTUAL_STARTDATETIME@

For example, we can put this kind of text in Email Body of an Email Print Destination Settings:

Purchase order no. @FIELD_PurchId@ for the vendor @PARAMETER_VendAccount@ is attached to this email.
- - Prepared by @WORKER@ on @CURRENTDATE@.

The result will be:

Purchase order no. 2015/000255 for the vendor Contoso Europe is attached to this email.
- - Prepared by Kevin Cook on 05/25/2015.

Print Destination Custom Placeholders

If Standard Placeholders don’t meet your needs, you can define your own Custom Placeholders for a particular report and implement them by extending the overrideReportRunSettings() method of the report DSP (Data Source Provider) class.
The report execution pipeline consists of the following steps:

Open the report dialog form (if not running a report from code or in batch or in case of a SSRS Print Management report).
Validate the report parameters and other report settings likewise the selected print destination settings.
Get the run-time report data source, i.e. needed data for printing the report.
Override the report execution settings such as Selected Template, Selected Print Destination, Report Caption, Save to Archive flag, etc. and replace Print Destination Placeholders, if any.
Generate the report in the requested format and send it to the selected print destination.

To replace Print Destination Custom Placeholders we need to inject custom business logic at the 4th step in the pipeline by extending the overrideReportRunSettings() method of the report DSP (Data Source Provider) class.

Note that in general we don't have to create a custom DSP class for a SSRS report because in many cases using the base DSP class is sufficient. In case you want to dynamically change the execution report settings, replace Print Destination Custom Placeholders or to add additional data to the report data source, you will need to create a custom DSP class using the wizard. Learn how >>

Take a look at the default implementation of the overrideReportRunSettings() method which basically only handles Standard Print Destination Placeholders:

public DocPlaceholderManager overrideReportRunSettings(
    DocReportRunContext _reportRunContext, boolean _replaceStandardPlaceholders = true)
{
    DocPlaceholderManager placeholderManager =
        new DocPlaceholderManager(_reportRunContext, this.parmParams(), this.parmParamsReporting());

    if (_replaceStandardPlaceholders)
    {
        placeholderManager.replaceStdPlaceholdersInCurrentPrintDest();
    }

    return placeholderManager;
}

public DocPlaceholderManager overrideReportRunSettings(

DocReportRunContext _reportRunContext, boolean _replaceStandardPlaceholders = true)

{

DocPlaceholderManager placeholderManager =

new DocPlaceholderManager(_reportRunContext, this.parmParams(), this.parmParamsReporting());

if (_replaceStandardPlaceholders)

{

placeholderManager.replaceStdPlaceholdersInCurrentPrintDest();

}

return placeholderManager;

}

The wizard which create a custom DSP class (for both SSRS and Basic reports) prepares for us the default implementation of the overridden overrideReportRunSettings() method:

public DocPlaceholderManager overrideReportRunSettings(
    DocReportRunContext _reportRunContext, boolean _replaceStandardPlaceholders = true)
{
    DocPlaceholderManager placeHolderMng;

    placeHolderMng = super(_reportRunContext, _replaceStandardPlaceholders);

    return placeHolderMng;
}

public DocPlaceholderManager overrideReportRunSettings(

DocReportRunContext _reportRunContext, boolean _replaceStandardPlaceholders = true)

{

DocPlaceholderManager placeHolderMng;

placeHolderMng = super(_reportRunContext, _replaceStandardPlaceholders);

return placeHolderMng;

}

If we want to handle our Custom Placeholders in the currently selected print destination, we need to invoke the replacePlaceholderInCurrentPrintDest() or replacePlaceholderInCurrentPrintDest() methods on the DocPlaceholderManager object.

This is the sample implementation of the overrideReportRunSettings() method:

public DocPlaceholderManager overrideReportRunSettings(
    DocReportRunContext _reportRunContext, boolean _replaceStandardPlaceholders = true)
{
    DocPlaceholderManager placeHolderMng;

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

    // Replace custom placeholders in the current print destination,
    // in case that Email is the currently selected print destination.
    if (_reportRunContext.parmPrintDestination() == DocPrintDestination::Email)
    {
        placeHolderMng.replacePlaceholderInCurrentPrintDest('PlaceholderText', 'ABC');
        placeHolderMng.replacePlaceholderInCurrentPrintDest('PlaceholderNumber', 12345);
        placeHolderMng.replacePlaceholderInCurrentPrintDest('PRODUCT_NAME', 'Magic Cream');

        // Or we can use the one method instead of the methods for a single placeholder:
        placeHolderMng.replacePlaceholdersInCurrentPrintDest(
            [['PlaceholderText', 'ABC'], ['PlaceholderNumber', 12345], ['PRODUCT_NAME', 'Magic Cream']]);
    }

    return placeHolderMng;
}

public DocPlaceholderManager overrideReportRunSettings(

DocReportRunContext _reportRunContext, boolean _replaceStandardPlaceholders = true)

{

DocPlaceholderManager placeHolderMng;

// Replace standard placeholders in the current print destination.

placeHolderMng = super(_reportRunContext, _replaceStandardPlaceholders);

// Replace custom placeholders in the current print destination,

// in case that Email is the currently selected print destination.

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

{

placeHolderMng.replacePlaceholderInCurrentPrintDest('PlaceholderText', 'ABC');

placeHolderMng.replacePlaceholderInCurrentPrintDest('PlaceholderNumber', 12345);

placeHolderMng.replacePlaceholderInCurrentPrintDest('PRODUCT_NAME', 'Magic Cream');

// Or we can use the one method instead of the methods for a single placeholder:

placeHolderMng.replacePlaceholdersInCurrentPrintDest(

[['PlaceholderText', 'ABC'], ['PlaceholderNumber', 12345], ['PRODUCT_NAME', 'Magic Cream']]);

}

return placeHolderMng;

}

We are assuming that we have three Custom Placeholders named as: PlaceholderText, PlaceholderNumber and PRODUCT_NAME. These placeholders need to be replaced by demo values ‘ABC’, 12345 and ‘Magic Cream’ but only if the currently selected print destination is Email.

Let’s see how we can use these Custom Placeholders on the Print destination settings form.

The sent email will look like this:

Beside customizing email body, subject or attachment name, you can also email reports with additional attachments. See how >>

For your end users you can provide the Print Destination Standard and Custom Placeholder List for particular reports so that they can benefit from it.

CONTENTS

How to Use Placeholders in Print Destination Settings

IN THIS ARTICLE

Print Destination Standard Placeholders

Print Destination Custom Placeholders

See also

IN THIS ARTICLE