This blog post will explain the concept of data models in Electronic Reporting and how to set up your own data model. Whether you are creating a new output document in Business Document Management or a new file output via Electronic Reporting, a Data Model is always the root component.
As Business Document Management configurations are nothing more than Electronic Reporting configurations, I will speak of Electronic Reporting configurations in the rest of this post.
Creating a Data Model
A data model is the key element in an Electronic Reporting Configuration, providing the structure for the data sources to be bound to via a model mapping and providing the source for format configurations to have the output elements bound to.
Before creating a custom data model, it is recommended to check if a similar data model already is provided by Microsoft in LCS. If a configuration is provided by Microsoft and this is not fitting for your needs, you can create a custom configuration based on the Microsoft Data model.
This Data Model is then called a derived configuration. The main advantage is that you do not have to start from scratch and if the data source is updated, you can use the updated model from Microsoft, you only have to worry about the fields you have changed.
To create a Derived data model, select the data model you want to derive from and click on create configuration. Select Derive from Name: <data model> and click Create. If you see the configuration provider Microsoft here, you first have to create your own configuration provider as described in this post. Enter a name and description and click on create.
Alternatively, if you do not see any data source suitable from the Microsoft LCS or other sources, you can create a brand-new data model. To do this click on create configuration (it does not matter if you have selected any existing configuration) and select Root and give in a name and description. A new root is a data model by default, this can not be changed.
Configuring a data model – Root nodes
A data model is comprised out of nodes. When configuring a derived model, you have the option to modify or expand existing nodes, when configuring a new data model you start out without any nodes. As a data model can get large it is recommended to think beforehand of the structure. A Data model is configured in a tree structure. In this structure nodes can be referenced saving you set up time for repeating nodes.
A good example of this is the address node, this is often reused in a customer account, vendor account, company account, delivery address, and so on. Within a data model you only have to create the address node once and you can reference this node under other nodes.
To create a new node, click the new button and give in a name. At this point you can only select Model root. Give in a name and click on Add. When using the data model for either model mapping or format mapping you select a top-level node to use for the mapping. You can use multiple top-level nodes for different mapping purposes. Performance wise this does not matter (significantly), as the Electronic Reporting engine only loads what it is using.
This should create your first node. Alternatively, you could have chosen for an enumeration as well. An enumeration is a predefined list of values you can either reference from formulas or as a user parameter input. The label in this case is the value the user sees; the name is the value used in the formula. So, in this case the user can select yes or no and the enumeration would return 1 or 0 to formula’s.
Configuring a data model – Child nodes
After configuring a main node, you can configure child nodes to it. Please note that you can only create child nodes for regular nodes, enumeration nodes can not have child nodes. To create a child node, select the model root node you want to create it for and click on new. Select Child of an active node and select the item type. This type is very important, as selecting the wrong node type will prevent you from mapping it to data sources if there is a type mismatch.
Select the item type, give in a name and select Add.
You have the option to select from the following node item types:
- Void, ignore this type as you can not create nodes with the item type Void
- Boolean, an item type for a true or false value
- GUID, an item type for GUID (Globally Unique Identifier) values, a GUID value typically looks like this bcbc7f68-9516-40ac-9434-60b0a44a8f3d
- Int64, an item type for integers (whole numbers), with a range from – 9.223.372.036.854.775.808 to 9.223.372.036.854.775.807
- Integer, an item type for integers (whole numbers), is a short int with a range from -32.768 to 32.767
- Real, an item type for decimal values
- String, an item type for text
- Date, an item type for dates (dates only)
- Time, an item type for time
- Enum, this item type creates an enumeration root node on the background and sets the created child node as a reference node. It is recommended to create enum nodes as root nodes first and not from the child nodes, as the auto generated root nodes can clump up your model configuration.
- Record, an item type for facilitating records. A record is a combined list of fields of one or multiple data sources. Easiest way to compare this type is with a row in Excel. When creating a record type node, Electronic Reporting expects you to define the child nodes (relevant fields) as well. A record node on its own can generally not be used in format mappings.
- Record List, an item type for facilitating multiple records. This can be compared to a table. When you create a record list node, like with a record node Electronic Reporting expects the child nodes to be defined. Unlike a record node, Electronic Reporting will repeat the output for each field in the record list.
- Container, an item type used to structure and group nodes instead of making the sub nodes a long list. You can’t bind anything to container nodes
- DateTime, an item type for a date and time value (only use this if the value is including both a date and a time value)
Configuring a data model – Referenced nodes
In order to create efficiency in the data model setup it is possible to create referenced nodes. This prevents repeating the same node setup at multiple places. Below is an overview from one of my data models where I used the address as a referenced node.
In here you see that I included a # in front some of my nodes as well. The reason for this is to indicate that these are indirect nodes, this is not required but it is an ease of life thing when your data model definition grows very large. When selecting the definition in the model or format mapping you will see the indirect nodes grouped together.
In my current setup I made the error of setting a name instead of the city in the Address node. Note that when I change this in the address node, all reference nodes are updated as well.
To create a referenced node, first you must create a root node. This will be the node which will be referenced. Set this up as you like. After this you will have to create your “main” node where you will be using the reference node. Create a root node and under this root node create a child node of either the type Record, Record List or Container. You can not use any other node type for referencing. After creating the node click on Switch Item reference and select the reference node and press ok.
Please note that that it is not possible to edit the fields in the node you switched the reference for. To edit the fields for this node you must go to the reference node by clicking the go to referenced item in the parent node screen.
Configuring a data model – Labels and Translations
In the data model each node has 3 fields; a name, a label, and a description. The name is the actual field name used by child configurations, in general, the name field is more technical in nature. Using labels, you can create an alternative name for this field which is more user-oriented in nature. Another big benefit of labels is the fact that you can translate them in other languages.
A name is required for a node; labels and descriptions are optional. When configuring both a name and a label the node name in the data model tree will be defined as <Label (name)>. In older versions of D365 translations were defined with @GER_LABEL:<label name> in the data model, in newer versions the translation is directly visible. To create a new translation, select either the label or description field and click the translate button on the top menu bar. In this menu, you can enter the default text, which is used if no specific language can be found, and the language and translated text. My recommendation would be to keep the system and user translation fields equal. After you are done click on translate to insert the translation.
Using labels, descriptions and translations help your users a lot when they are working with your data model. When using the data model in a format mapping or data model mapping you will see the label and description field translated into the languages you have defined.
Translations can be set up for each configuration individually. However, an undocumented feature is that the translations for a data model are shared throughout all child configurations. So, if you plan on creating multiple child configurations and are expecting the same translations in these child configurations it is worth to consider moving these translations to the data model for ease of maintenance. To do this, just select a field in the data model and create a new translation. Translations are stored in a separate section of the data model after creation, so even if you do not use the translation in the data model you can create it for use in child configurations.
Configuring a data model – Natural key
The natural key field is a field you can define on the root nodes. The natural key is a field that is related to how Electronic Reporting defines the primary key for the data set you have configured under this node. By default, Electronic Reporting uses a surrogate key, which is basically an int64 value which is randomly generated (like a RecID on a table is). You can replace this surrogate key with a natural key, which is a value in your data set which meets the requirements for a primary key (unique, does not change and is never null).
The reason why you would want to do this is that this could increase performance. However, the benefits of natural keys over surrogate keys is a discussion that is been going on for a very long time. Simply saying that a natural key is faster than a surrogate key is not true, there are many factors to consider and it could even be so that a surrogate key is faster than a natural key depending on data types. Use this option only if you really know what you are doing and have investigated all other performance increasing methods you could try have failed.
Conclusion
You now should have an idea on how the data model is set up and what components are in the data model. This should help you in creating your own custom data model. The payment model is a good model for getting a general idea of the setup of a data model and its capabilities, with this guide in hand you should be able to understand the components and the setup of the payment model. In the next part we will go into model mappings.