Extend Electronic Reporting Destinations and Enable Custom Integrations

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.

Please bear in mind that this is only a POC, so you can redesign this setup and the functionality in general in any direction that suits your needs.

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.

 

When the Skip saving to original location option is turned on, the generated document is sent only to the selected destinations and it is not saved to the original location (which is usually Electronic reporting jobs).

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.

 

CONCLUSION: If we want to use a specific Document type to extend Electronic reporting destinations to save ER Format documents to (external) Azure Blob storage, Azure Files or File system, the best choice is to use the Archive destination with this Document type selected on the Electronic reporting destinations form or selected as Job archive Document type in 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.

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.

 

Troubleshooting

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.

Resources

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.


- - 
RELEASE NOTES
Version: 1.0.1
Released: March 10, 2022
Bug fixes: Updated APIs for saving to Azure Files

Download Docentric AX >>

Note that you can use this solution with Docentric Free Edition. However, for saving documents to external Azure storage, a valid license is required.

Further improvements

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 support@docentric.com. We’re eager to hear your suggestions & ideas!

Leave a Reply

Your email address will not be published. Required fields are marked *

*

Docentric respects your privacy. Learn how your comment data is processed >>

Docentric respects your privacy. Learn how your comment data is processed >>