Edit

Change code so users can configure and use named ER destinations

Note

Community interest groups have now moved from Yammer to Microsoft Viva Engage. To join a Viva Engage community and take part in the latest discussions, fill out the Request access to Finance and Operations Viva Engage Community form and choose the community you want to join.

To generate an outbound document, run an ER format mapping. When you use the initial API of the ER framework to call an ER format mapping, it runs all destinations configured for components of the format. To review the sample code for a call of this type, see Add a report service class.

You can also configure action-dependent ER destinations for the ER format. You can then use the extended API of the ER framework to call an ER format mapping that provides a user action code. The action code runs only the destinations configured for the action provided.

In some cases, you must configure print management and select the same ER format for different print management records, so that you can apply different ER destinations for generated documents when you run that format. For example, you might configure print management so that it runs the same ER format to email original documents and to print document copies to a network printer. Use the new API of the ER framework in Microsoft Dynamics 365 Finance version 10.0.21 for this purpose.

API to enable users to configure ER destinations that are print management record specific

Currently, you can open the Print management setup page for every type of business document, to specify how the business document is generated and delivered. For every available record of the print management tree, you can perform the following actions:

  • Use the Report format field to select either a SQL Server Reporting Services (SSRS) report or an ER format that runs.
  • Use the Destination button to open the Print destination settings dialog box, so that you can change the destination of the generated report.
  • Review the Destination field, which shows the defined destination.

Important

If you select an ER format in the Report format field, the configured SSRS destination isn't applied for a generated report.

You can change this behavior and configure ER destinations that are specific to a print management record. Unlike general ER destinations, these destinations are named. You can select a single named destination for several print management records. For more information, see Configure print management record-specific ER destinations.

First, turn on the Allow to set up ER destinations per print management item feature in the Feature management workspace.

Next, enable users to configure print management record–specific ER destinations for a specific type of business document, if this functionality isn't enabled by default. In Finance version 10.0.21, the functionality isn't enabled for every type of business document, because the isNamedDestinationEnabledByDocumentType method of the ERNamedDestinationReportEnabler class returns false for any PrintMgmtDocumentType document type that is provided.

/// <summary>Class for enabling NamedDestinationFeature for current document type.</summary>
/// <remarks>To enable the document type you should wrap a <c>isNamedDestinationEnabledByDocumentType</c> method.</remarks>
public class ERNamedDestinationReportEnabler
{
    /// <summary>Checks that feature enabled for current document type. Make extension for this method.</summary>
    /// <param name = "_typeId">Print mgmt document type</param>
    /// <returns>True if feature enabled.</returns>
    [Wrappable(true), SuppressBPWarning('BPParameterNotUsed', 'Required by signature')]
    public static boolean isNamedDestinationEnabledByDocumentType(PrintMgmtDocumentType _typeId)
    {
        return false;
    }
}

You must wrap the isNamedDestinationEnabledByDocumentType method for a specific document type to enable users to configure print management record–specific ER destinations for documents of that type. The following example shows how to enable the functionality for free text invoices.

[ExtensionOf(classStr(ERNamedDestinationReportEnabler))]
final class ERNamedDestinationReportEnablerContoso_Extension
{
    public static boolean isNamedDestinationEnabledByDocumentType(PrintMgmtDocumentType _typeId)
    {
        var ret = next isNamedDestinationEnabledByDocumentType(_typeid);
        if(_typeId == PrintMgmtDocumentType::SalesFreeTextInvoice)
        {
            return true;
        }
        else
        {
            return ret;
        }
    }
}

API to run a format mapping where the destination that is provided is print management record specific

When you enable users to configure print management record–specific destinations, they expect a named destination configured for a print management record. When you use the print management record to run an ER format and generate an outbound document, you must pass that named destination to the ER framework to force ER to run only that destination, not any other destinations that might be configured for the ER format that is running.

The following code for the ERPrintMgmtReportFormatSubscriber class shows how the ER framework currently gets called to generate a free text invoice.

/// <summary>
/// Runs a format mapping based on incoming arguments.
/// </summary>
/// <param name = "_args">Event arguments object.</param>
public static void runFreeTextInvoiceReport(NonSSRSPrintMgmtAdapterReportExecutedEventArgs _args)
{
    ERIFormatMappingRun formatMappingRun = ERPrintMgmtReportFormatSubscriber::buildFreeTextInvoiceReportMappingRun(_args);

    if (_args.parmArgs() && _args.parmArgs().parmEnumType() == enumNum(PrintCopyOriginal))
    {
        Args args = _args.parmArgs();
        boolean doUsePrintManagement = true;

        if (args.caller() is SalesFormLetter)
        {
            SalesFormLetter caller = args.caller();
            doUsePrintManagement = caller.usePrintManagement();
        }

        ERDestinationAction action;
        if (doUsePrintManagement || !isFlightEnabled(LocalizationFlights::ForcePrintJobSettings))
        {
            action = ReportDestinationContract::getPrintDestinationAction(args.parmEnum());
        }
        else
        {
            action = ERDestinationAction::View;
        }

        ERIFormatMappingRunWithDestinationAction mappingRunWithAction = formatMappingRun as ERIFormatMappingRunWithDestinationAction;

        if (mappingRunWithAction && action != ERDestinationAction::NoAction)
        {
            mappingRunWithAction.withDestinationAction(action);
        }
    }

    formatMappingRun.withCreatingObjectParameter(
        CustomersInvoicingModelName,
        classStr(PrintMgmtPrintSettingDetail),
        _args.parmSettingDetail());
    formatMappingRun.run();
}

The following example shows how you can change the sample code to use the new API to run an ER format and provide an ER named destination that is print management record specific.

/// <summary>
/// Runs a format mapping based on incoming arguments.
/// </summary>
/// <param name = "_args">Event arguments object.</param>
public static void runFreeTextInvoiceReport(NonSSRSPrintMgmtAdapterReportExecutedEventArgs _args)
{
    ERIFormatMappingRun formatMappingRun = ERPrintMgmtReportFormatSubscriber::buildFreeTextInvoiceReportMappingRun(_args);

    if (_args.parmArgs() && _args.parmArgs().parmEnumType() == enumNum(PrintCopyOriginal))
    {
        Args args = _args.parmArgs();
        boolean doUsePrintManagement = true;

        if (args.caller() is SalesFormLetter)
        {
            SalesFormLetter caller = args.caller();
            doUsePrintManagement = caller.usePrintManagement();
        }

        ERDestinationAction action;
        if (doUsePrintManagement || !isFlightEnabled(LocalizationFlights::ForcePrintJobSettings))
        {
            action = ReportDestinationContract::getPrintDestinationAction(args.parmEnum());
        }
        else
        {
            action = ERDestinationAction::View;
        }

        ERIFormatMappingRunWithDestinationAction mappingRunWithAction = formatMappingRun as ERIFormatMappingRunWithDestinationAction;

        if (mappingRunWithAction && action != ERDestinationAction::NoAction)
        {
            mappingRunWithAction.withDestinationAction(action);
        }

        // Check whether a named destination is provided.
        // If so, pass it to ER to specify a single destination for a generated document

        RefRecId NamedDestination;
        if (doUsePrintManagement || !isFlightEnabled(LocalizationFlights::ForcePrintJobSettings))
        {
            NamedDestination = ReportDestinationContract::getNamedDestination(args.parmEnum());
        }
        else
        {
            NamedDestination = 0;
        }

        ERIFormatMappingRunWithNamedDestination RunWithNamedDestination = formatMappingRun as ERIFormatMappingRunWithNamedDestination;

        if (RunWithNamedDestination && NamedDestination)
        {
            RunWithNamedDestination.withDestinationNamed(NamedDestination);
        }
    }

    formatMappingRun.withCreatingObjectParameter(
        CustomersInvoicingModelName,
        classStr(PrintMgmtPrintSettingDetail),
         _args.parmSettingDetail());
    formatMappingRun.run();
}

The NamedDestination field of the PrintMgmtSettings table includes the reference to a named destination. You must pass this reference to the runFreeTextInvoiceReport method from the processed print management record that extends ReportDestinationContract.

Applicability

To set up named destinations and force the ER framework to use the named destination, first turn on the Allow to set up ER destinations per print management item feature in the Feature management workspace.

The feature enables named ER destinations for all types of business documents that can be generated in Finance by using the ER framework. For more information, see the Configurable business documents – specific destinations via printer management settings in the reports feature in the "Globalization" section for the "Dynamics 365 Finance" application in the Dynamics 365 and industry clouds release plan for the 2021 release wave 2.

Additional resources

Electronic reporting (ER) overview

Electronic reporting (ER) destinations

Configure action-dependent ER destinations

Configure print management record-specific ER destinations

Electronic reporting framework API changes for Application update 10.0.21

  • Last updated on