Intro to Configurable Business Documents – Part 3 of 3
In part 1 of this series of blogs we learned what exactly are configurable business documents and what is the required setup. In part 2 we saw where to start and we created a derived version of a format configuration. In this last part we will customize our derived format configuration, derive related configurations and run the result.
Customize the Format configuration
As the format configuration tree structure at this moment still displays the out-of-the-box Excel template layout structure, you should now start modifying the Excel document downloaded earlier. The first thing to do is enabling the checkboxes on the View tab:
Then you are ready to create a fancy layout which meets the customer’s needs. You should know that the names of the cells and ranges in the template are used in the format configuration to bind the data from the model data sources to it. Therefore when you move a field to another position, make sure you cut and paste it so the name of the field is moved together with the other information. Also, when creating a new field make sure to define a suitable name for it. The Name Manager will become your best friend to manage all names and references:
Note that the names of all fields within a range should be prefixed with the name of this range. So if you move a field to another section, the field should be renamed. Otherwise this will result in validation errors in the business document format configuration.
Once you have finished your initial version of the template, you attach it to the business document format configuration. You could use the import functionality from within the format designer via Import > Update from Excel. However, I do not recommend doing this because you are at great risk of losing all your existing mappings. A safer way to link your new template is to go to the Attachments, create a new attachment record and link your template. Then delete the old attachment record, open the Designer and select the newly attached attachment in the Template field.
After this you can start mapping the new format data to the data model in the Designer. When you think you are done, press the Validate button. If there is something wrong in the format mapping or the format is not in line with the Excel template, you will get a list of errors you will need to solve. Sometimes a Fix button is there by which you can automatically fix one or more of the errors. Note that this will not always give the desired result, so be careful with using that button!
Model and model mapping configurations
It might be that the result of the existing data model binding is not completely what you want to be displayed on your business document. To solve this you can adjust the model mapping configuration. You do this by selecting the out-of-the-box model mapping configuration and then Create configuration from the menu. Again we select Derive from to create our own draft version of the model mapping configuration which we then can adjust to meet our requirements. Sometimes we have added a new field to our format configuration which cannot be mapped to any element in the existing data model. In that case you can create a derived configuration of the data model, add the missing element and after that map it to the right data source in your custom model mapping configuration. And at last in your custom format configuration the new data field can be bound to the new element you have just added in your model mapping.
Note that the changes in the data model and mapping might not be immediately visible in the format configuration. Then you should first set the Status of the model and/or mapping to Completed. There is however a workaround, so you do not have to set the status to Completed or Shared after each change you do. Via Configuration > Advanced settings > User parameters…
you can set the Run settings radio button to Yes:
This results in a Run Draft option on your configurations which you can set to Yes. This is very handy during the development and testing of your configurations.
Testing the end result
Now we have done our customizations we are of course very curious what the business document will look like at running it. To test the format there is a Run option on the format configuration. However, this will almost always result in runtime errors because of missing input data. So the best way to test your business document is doing this by using the functionality in the application itself, by generating a pro forma version or viewing it from an existing journal. Make sure that you first link your new business document to the print management Report format field via [module] > Setup > Forms > Form setup > Print management > [business document].
And because you do not want to send your business document as an Excel document which can be edited, you should also setup an electronic reporting destination which includes PDF conversion. Note that besides in the ER workspace, the menu option for this is also available in the Organization administration > Electronic reporting submenu next to a lot of other ER menu options.
In the Electronic reporting destinations form you create a new record, give it a recognizable name and create a new File destination record for it in which you check the Convert to PDF checkbox:
Via the Settings button the required Destination settings can be specified:
Conclusion
This brings us to the end of this series of blogs. You will have noticed that I did not discuss Word as format configuration template, although for some of the business document format configurations besides Excel also Word template versions are available. I guess this is my personal taste because the layouts of Excel are completely WYSIWYG where the layouts of Word are not (at least for me). If Word has no secrets for you and you know your way around while creating templates using content controls and things like that, feel free to eat your heart out.
Anyway, as they say: “The proof of the pudding is in the eating”. So I would suggest you dive into the exciting world of Electronic Reporting yourself. There is a lot to learn… have fun!
Please read the other related articles on this link https://kaya-consulting.com.tr/category/Business-Documents/
Intro to Configurable Business Documents – Part 2 of 3
From the first blog of this series you now know what configurable business documents are and what is the minimally required setup. In this blog you will learn how to derive configurations, we discuss repositories and we take a look at the format designer.
Where do we start?
Of course, we could start from scratch… but because Microsoft provides us with out-of-the-box business document configurations, it is much easier to start from an existing business document and adjust it according to the customer’s requirements. In that way we can make use of the existing model and format mappings, which saves us a lot of time.
Lets start
So, the first thing we do now is import the latest version of the out-of-the-box business document configurations we want to customize. In the ER workspace we select the Repositories link on the Microsoft Configuration provider tile and open the Global repository. At this point you might be presented with a logon dialog so you must make sure your account has sufficient access rights to be able to proceed. In the Global repository you will find a big list with ER configurations grouped by model. The easiest way to locate the business document configurations you need is to press the Expand all button and then CTRL-F:
Select the configuration you need and press the Import button. If the configuration already exists in your environment, also indicated by a flag in the Exists column, the button will be disabled. Note that often country-specific configurations are available which meet the local regulations. When you import the desired format configuration, the necessary related model and model mapping configurations will automatically be imported with it, so it is always good to start with that one.
Having done this,
The business document will appear in the Business Document Management workspace. From here you could start customizing your imported business document:
I will not go into detail on this entry point. A description for it can be found on Microsoft docs: Business document management overview. Next to some security considerations you can also read there that additional SharePoint setup is needed to be able to use the “Open in Desktop App” functionality. Without this the user experience is not very good, you have to scroll more than you would like to do. Besides the fact that it is not user-friendly, I would not suggest this way of work anyway because it unfortunately still is a bit unstable and not flawless. Having said that, my advice would be to get into the ER workspace and start working from there. This will also give you a lot more advanced options and flexibility to really get a grip on this matter.
ER workspace
In the ER workspace you press the Reporting configurations tile:
This will open the following form displaying all related business document configurations you have imported before:
Derive a Format configuration
It is always a good idea to start the customization process with the format configuration. Because in the output format layout of the out-of-the-box business document we can easily analyze what fields we have available, what fields already meet the customer’s requirements, what fields are missing, what has to be rearranged, what has to be adjusted to transform the layout into the style of the corporate identity, etc. etc. So first we download a copy of the out-of-the-box Excel template. This can be done by pressing the Attachments button and selecting Open in the appeared form:
This action will save a copy of the Excel document in your Downloads folder. Besides using this document for analyzing purposes, it can of course also be used as a starting point to create your own customized Excel template version for the business document.
So let us go back to the Reporting configurations form. You never edit directly an out-of-the-box ER configuration, but always create a so-called derived configuration from the existing one. You do this by selecting the Create configuration menu option and providing the necessary input parameter information:
This will create a Draft configuration version which you can take a look at by selecting the Designer menu option:
At the left you will see a tree structure which represents all Excel ranges and cells, that is all fields in the order from top to bottom and from left to right. The expandable tree nodes represent an Excel range of one or more lines. In the lower right bottom of the form, you can enter an Enabled condition which specifies if the section should be shown or not during runtime execution of the business document. The presence of such a condition is indicated by a question mark at the end of the tree node name. Tree nodes displayed in bold indicate that the tree node, the Excel cell or range, is bound to a data model element on the right of the form. The value of this mapping can be shown in the tree by activating the Mapping tab on the upper right, as is the case in the picture above. To take a closer look at the mapping formula, which can be as complex as you want, you press the Edit formula button.
Labels….
Note that labels are no longer coming from the application but are created and stored inside the configuration itself. Via the Edit formula button and then the Translate button you can create your own labels in multiple languages. The resulting formula will look like @”GER_LABEL:YourCustomLabelName”. It is also possible to export and import labels from the configuration menu: Exchange > Export labels and Load labels, which might become useful in case you need to add translations of all your custom labels into additional languages.
That is it for now. In the last blog of this series we will customize our derived format configuration and Excel template, take a look at the related model and model mapping configurations and run the result of our efforts. Till next time!
Please read the other related articles on this link https://kaya-consulting.com.tr/category/Business-Documents/
Intro to Configurable Business Documents – Part 1 of 3
How do we generate configurable business documents for our customers in Dynamics 365 for Finance and Operations? You will find only very basic documentation on Microsoft Docs, so you will need to watch quite some available webinars on the internet to get a bit of an idea.
The big advantage of configurable business documents lies clearly in the word “configurable”. Configurable business documents are not part of the software anymore, they are not a matter of development but rather of setup. Creating and updating business documents is no longer part of the software development and release process. Adding or removing fields, adjusting the document layout and formatting, changing the document data sources and designs, it can all be done at any time directly from within the D365FO production environment itself. So configurable business documents provide much more flexibility than SSRS reports and there is no more need for deployments!
The business document management audience targeted by Microsoft are business users. No knowledge of the Electronic Reporting (ER) framework is supposed to be required and as usual it is all very simple and fast… OK, back to reality! The out-of-the-box business documents hardly ever meet the customer’s requirements and the layouts usually need to be completely turned upside down. Because generating configurable business documents proves to be a quite complex and therefore time-consuming process the business user will soon hand it over to a functional consultant, who in turn will seek help from a developer because a deep understanding of the data structure is needed. Apart from that, the user experience is not yet very friendly, the design is difficult, troubleshooting is not easy and some of the features are still unstable resulting in errors like “Something went wrong, but we were able to recover your session”. Let us say there is room for improvement…
In this small series of blogs I will share my first experience with configurable business documents on a customer project and summarize and briefly explain the necessary steps to be taken. But before doing so I will try to answer the following question.
What are Configurable Business Documents?
Configurable business documents are built on top of the ER framework and basically consist of ER configurations plus templates. The following three types of reporting configurations are always involved, working closely together:
Data Model
This defines the logical data tree structure with the necessary data fields as required by the business domain for which it will be used. Good examples are the Order model, Waybill model, Invoice model and Reminder model.
Data Model Mapping
This connects the data model elements with its data sources in database, classes, calculated fields, etcetera, from where the data will come at runtime.
Format
This defines the output data tree structure for the template and its mapping to the data model. It includes templates in Excel and Word.
The data model is in fact in the center, with on the one side the mapping with the data sources and on the other side the output mapping with the format template. The flow looks like this:
At execution time the configurable business documents still use the known Print Management functionality and the SSRS execution pipeline. But instead of generating an SSRS report and sending it to an SSRS print destination, the configurable business documents flow as depicted above is executed, generating an output document and sending it to one or more ER destinations.
The main purpose of configurable business documents is to replace the SSRS reports and to make customization of business documents like order confirmations, invoices, collection letters, etcetera much easier and less costly.
Required setup
Before we can make our hands dirty, we must first do some minimal configuration activities:
• Make sure that in the Feature Management workspace the following features are enabled:
o Business document management.
o Convert Electronic Reporting outbound documents from Microsoft Office formats to PDF.
• In the Electronic Reporting workspace, we create a configuration provider for our customer besides the one for Microsoft. After this we set it active and define a configuration repository for the newly created configuration provider via the Repositories link on the new tile (see picture below).
My favorite type of repository used to be LCS, because it worked fine for me to do maintenance and distribution to other environments. But recently Microsoft decided to deprecate LCS as an ER configuration storage type and now recommends us to use the Global repository instead. Via the below link in the ER workspace a special Regulatory Configuration Services environment (RCS, nothing more than a stripped down D365FO environment) can be provisioned in which the customer’s ER configurations will have to be maintained.
This forces us to move all existing business document configurations to this new provisioned environment. A migration option like for example importing these configurations directly from LCS does not exist. Another thing is that the new environment does not contain any D365FO metadata. So, in addition to the business document configurations also metadata configurations need to be created and moved over to the new environment. Hopefully, Microsoft will come up soon with a solution to support this imposed migration to RCS.
• Setup the following ER parameters:
o Set Enable design mode to Yes, otherwise we cannot do anything.
o Define a File document type and assign it on the Attachments tab.
After this has been done, we should be ready to go!
In the next blog of this series you will learn where to start and how to derive configurations, we discuss repositories and take a look at the format designer. Till next time!
Please read the other related articles on this link https://kaya-consulting.com.tr/category/Business-Documents/