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/