In this article, you will learn how to extend Electronic reporting print destinations to enable saving reports to Azure Files, external Azure Blob storage or File system (applicable only for on-premises environments). We have also provided the working implementation so you can install it and use it right away 🙂.
Why saving to Azure Files
Azure Files offers fully managed file shares in the cloud that are accessible via the industry standard Server Message Block (SMB) protocol or Network File System (NFS) protocol. Learn more >>
Saving Electronic reporting documents to an Azure file share is useful in cases when you want to sync it with your network folder. One reason behind it could be file-based integration with the governments and legislative authorities, which demand electronic interoperation with D365FO in terms of reporting, submitting, and receiving official information, but it cannot be done through the built-in Electronic messaging functionality.
Why saving to external Azure Blob storage
Integration, integration and integration 😊. External Azure Blob storage used in combination, e.g. with Azure Functions and Azure Event Grid can quickly result in highly-scalable and cost-effective implementation of various integration scenarios. Learn more >>
What if I have on-premises environment
If you have D365FO on-premises, you will probably want to save your Electronic reporting documents to a shared network folder instead of saving them to Azure Files or Azure Blob storage. Therefore, we introduced saving to File system as an additional option.
Microsoft recommendation for extending ER destinations
We were following Microsoft recommendation for extending Electronic reporting destinations via custom Document types. But we took a step further. Namely, we extend the Document types form to provide a new setup form called Electronic reporting destinations for configuration of the saving settings of ER Format documents to Azure Files, Azure Blob storage and File system.
Next, we implemented the event handler for the ERDocuManagementEvents.attachingFile event, which is raised each time when Electronic reporting attaches an ER Format document to a record. So, if the document is attached using the Document type for which we activated and configured distribution to (external) Azure Blob storage, Azure Files or File system, this method will handle the distribution.
Configure Document type to extend ER destinations
Let’s say that we've configured additional Electronic reporting destinations for Document type File ER to enable saving to an external Azure Blob storage. Note that we can also enable saving to Azure Files and File system, whereas File system is supported in on-premises environments only.
Wait, when exactly the attachingFile event is published?
The ERDocuManagementEvents.attachingFile event, which is raised when the Electronic Reporting framework attaches a document to a record.
Let’s focus on printing ER Formats to analyze when this event is published.
Attaching of an ER Format document to a table record occurs and the ERDocuManagementEvents.attachingFile event is published, when the format is printed to an Electronic reporting destination under certain conditions, as follows:
- ER destination: File (on demand) -> Document is attached to the ERFormatMappingRunJobTable table record (Electronic reporting jobs) using Others Document type from Electronic reporting parameters only in case of error, i.e. if sending the document for downloading in browser fails. Otherwise, no document is attached and no event is raised.
- ER destination: File (in batch) -> Document is always attached to the ERFormatMappingRunJobTable table record (Electronic reporting jobs) using Others Document type from Electronic reporting parameters.
- ER destination: Archive with Save in job archive turned off -> Document is always attached to the ERFormatMappingRunJobTable table record (Electronic reporting jobs) using the Document type selected on the Electronic reporting destinations.
- ER destination: Archive with Save in job archive turned on -> Document is always attached to the ERFormatMappingRunJobTable table record with the Archived flag set to True (Electronic reporting archived jobs), using Job archive Document type from Electronic reporting parameters.
- ER destination: Email -> Document is attached to the ERFormatMappingRunJobTable table record (Electronic reporting jobs) using Others Document type from Electronic reporting parameters only in case of error, i.e. if emailing the document fails. Otherwise, i.e. if emailing succeeded, no document is attached and no event is raised.
- ER destination: Printer -> Document is attached to the PrintJobHeader table record (Print archive) using the DocuType::typeFile() Document type if the Save to archive option is turned on. Also, in case of error during PDF conversion using MS Office Conversion Service (since printing is supported only Printing as PDF via DRA and Adobe Acrobat Reader), it is attached to the ERFormatMappingRunJobTable table record using Others Document type from Electronic reporting parameters.
- ER destination: Screen -> Document is attached to the ERFormatMappingRunJobTable tmp table record (Electronic reporting jobs) using Temporary Document type, to enable opening in browser using the temporary URL link. Also, in case of error, it is attached to ERFormatMappingRunJobTable using Others Document type from Electronic reporting parameters.
Event handler for ERDocuManagementEvents.attachingFile
We created an event handler for the ERDocuManagementEvents.attachingFile event, please see the implementation below. The solution is extensible, so you can add support for additional Document Type ER destinations easily. We also created a helper class for logging, so you can log the messages, e.g. in the database, which can be useful when printing ER Formats in batch.
The whole solution you can download and import as a project in your development environment.
[SubscribesTo(classStr(ERDocuManagementEvents), staticDelegateStr(ERDocuManagementEvents, attachingFile))]
public static void ERDocuManagementEvents_attachingFile(ERDocuManagementAttachingFileEventArgs _args)
boolean documentExportedAzureBlobStorage, documentExportedAzureFiles, documentExportedFileSystem = false;
// Execution Id used to trace all ER destinations as a single execution.
str executionId = DocGlobalHelper::guid2strWithoutBraces(newguid());
// Process additional ER destinations as they are configured.
// Try to save to Azure Blob Storage provider if configured so.
DocAdditionalERDestination_DCAERD azureBlobStorageProvider = new DocAdditionalERDestinationAzureBlobStorageProvider_DCAERD(_args, executionId);
documentExportedAzureBlobStorage = azureBlobStorageProvider.exportDocument();
// Try to save to Azure File Share provider if configured so.
DocAdditionalERDestination_DCAERD azureFileShareProvider = new DocAdditionalERDestinationAzureFileShareProvider_DCAERD(_args, executionId);
documentExportedAzureFiles = azureFileShareProvider.exportDocument();
// Try to save to network share provider if configured so.
DocAdditionalERDestination_DCAERD fileSystemProvider = new DocAdditionalERDestinationNetworkShareProvider_DCAERD(_args, executionId);
documentExportedFileSystem = fileSystemProvider.exportDocument();
// If any of the Electronic destinations are enabled:
if (azureBlobStorageProvider.isEnabled() ||
// In this case, check if the saving to all enabled ER destinations succeeded.
// If yes, we can mark the attachment as handled. Otherwise, we will throw an exception.
if ((!azureBlobStorageProvider.isEnabled() || documentExportedAzureBlobStorage) &&
(!azureFileShareProvider.isEnabled() || documentExportedAzureFiles) &&
(!fileSystemProvider.isEnabled() || documentExportedFileSystem))
// Check if the attachment is configured to be marked as handled.
// Note that we can use any of the above providers to check if this option is turned on.
// This options is the same and bound to all providers.
// All ER destinations which were enabled succeeded, we can mark the attachment as handled.
// Marking the attachment as handled will create an entry in Electronic reporting jobs without the attachment file.
// One of the enabled ER destination failed. We will throw the exception.
// NOTE: You can change this behaviour if needed.
DocGlobalHelper::handleException(funcName(), strFmt("@DocAdditionalERDestinations_DCAERD:AtLeastOneElectronicDestinationFailed", azureBlobStorageProvider.docuType().TypeId));
Print ER Format to Archive destination with selected Document type
Let’s now set up Electronic reporting destinations for a sample ER Format and run it from Electronic reporting configurations.
You can see that the ER Format document is saved to both Electronic reporting job (which could be skipped by turning on the Skip saving to original location option on Document type > the Electronic reporting destinations dialog) and configured Azure Blob storage location.
File is always downloaded in the browser
When running an ER Format, the output file is always downloaded in the browser regardless of the configured ER destinations. For example, you did configure Archive as the only target ER destination, but you keep getting the output file in the browser each time the report is printed. For reports created and printed via the ERReportLauncher class, we discovered what could be the reason. Read more >>
Folder is always downloaded in the browser as a ZIP
If your ER Format configuration has Folder as the main node, with child nodes of type, e.g. File or Report, the Folder node will always be zipped and downloaded in the browser when the report is printed, unless you configure an empty ER destination for it.
File is saved two times to the same location
When printing an ER Format to the Archive ER destination, it can happen that the output file is saved two times to the same location that the selected Document type point to, e.g. to a SharePoint folder.
In this case, please check the Archive destination settings, because if the Save in job archive option is turned on, the output file is additionally saved to the location of the Document type selected as Job archive in Electronic reporting parameters.
So, if the Archive destination is enabled, the output file is saved to the location specified trough the Document type selected in the ER destination settings form. If Save in job archive is turned on, the output file gets saved two times.
Thus, if both settings are enabled, the generated file will be sent to both Document types. If both Document types point to the same location, then we will get the duplicated file.
Download the solution (D365FO project) v1.0.1>>
Prerequisites: Installed Docentric AX, version 3.4.3 or above.
Download the solution (D365FO project) v1.0.0 >>
Prerequisites: Installed Docentric AX, from version 3.3.9 to 3.4.2.
Released: March 10, 2022
Bug fixes: Updated APIs for saving to Azure Files
We plan to develop this POC solution further and enable electronic signatures for output files in PDF and XML formats. Do you think this feature would be beneficial for your scenarios? Nevertheless, if you’ve spotted another room for improvement, please reach us at firstname.lastname@example.org. We’re eager to hear your suggestions & ideas!