Canvas sections in D365 Configurable Business Documents

Canvas sections in D365 Configurable Business Documents

Embedding static sections of a fixed width and length into configurable Business documents in Excel seems to be hard to impossible, but it is not. An example can be an American pre-printed Cheque or the notorious French Bill of exchange at the end of the invoice. The section may not span 2 pages, i.e. it should be kept together to be torn off or scanned by the bank OCR system. This cannot be achieved by merging cells but with floating graphical elements only. Follow the below advice how to make it:

Better use Excel. The mapping of an Excel file to an Electronic Reporting format configuration is based on the named ranges (name manager), a mapping of a named Text box in a drawing is also possible. It is not necessary to attach an XML schema to the Excel file, the design of an Excel report is a simple WYSIWYG exercise.
You cannot use the Configurable business documents UI, because the changes needed are intricate and can hardly be made in the online Office 365. You have to locate the exact format in Electronic reporting (here: Sales invoice (Excel) (FR)), open and save the attachment with the template on your computer, amend it, upload it as an attachment and reassign to the root node in the format Designer.
Figure out the exact width of the paper by printing the document. Check at which column the page boundary begins (here: M-N).
Capture a raster image of the section you have to embed and paste it as a template into your document to position the vector elements over it nicely. Send it to the background and resize carefully to match the full page width (here in the background, cyan stained).
The drawing elements get anchored by Excel to the adjacent cell, and to maintain the relative positions they should be floating inside of a large merged cell of the size of the whole section (here: $B$121:$M$121). The outer boundaries of the elements shall not cross the boundaries of this mother sell. Make the row a named range which will be holding all the boxes and images (here: BoE for the bill of exchange).
The Electronic Reporting may only work properly with Text boxes and Images. Everything must be rendered with text boxes.
To address and populate the elements in the Electronic Reporting format definition, they must be named ranges* in Excel (here for the red line: BoE_Line).
* Not really a range but a named/renamed element of a drawing. The ER engine is going to multiply them – in theory – and a BoE_Line element becomes BoE_Line1 etc. in the final output.
The Electronic Reporting cannot currently place circles, lines or any other geometric form properly. The little triangles in this example have been drawn with Unicode symbols like “∇”. If you need to draw a line, it must be an empty Text box with a height of around 0,03 cm and an opaque line around of the given thickness divided by 2. The inner boundaries of the text must be all zero, otherwise the ER will corrupt the width, the position and the line type and make it disappear:
Every element (including the “lines”!) must be explicitly listed (listed, not necessarily mapped!) in the format definition as a cell or range, otherwise the graphical object remains linked to the absolute number of the adjacent cell (e.g. B121) and starts floating all around, appearing in the middle of the invoice when you print it.
The objects must be in the proper order, or the ER Designer is going to warn you that “The range BoE_Line must be preceded by the range XXX“. The sorting order is a bit special. If the cells are sorted by {ROW, COLUMN}, the drawing objects are apparently sorted by the cartesian coordinates {X;Y} of the upper left corner, from left to right, then from the up to the bottom (which is a theoretical aspect, since it is hard to place the elements at exactly the same X coordinate by drag and drop only). See the above enumeration 1-7, the upper line starting the leftmost.
Test and print your report with a proforma document often. If you don’t know how to test an ER configuration in a Draft status, here is the sacred answer: Electronic Reporting (ER) Cookbook 2: new tips from the kitchen.
The raster image shall be removed in the end, of course, it is too cheap a solution for the static texts and lines.

Conclusion

To avoid all this mess, you may try to convince the customer that negotiable instruments from the XVIII-XIX centuries may become obsolete in the XXI (you know: the wire payments, SEPA, blockchains and Co…) Good luck with that.

Electronic reporting blog series

Electronic Reporting (ER) Cookbook 4: References in a model

The “Item reference” in Dynamics 365 Electronic Reporting models has been an elusive concept for me for quite a long time. A reference creates a kind of a cross-link between the ER model parts, but what for? Now I think I have figured out some important use cases:

Re-use structures and record list definitions within the model, especially for UNIONs
Map the same model in different ways and export similarly structured files from different sources

References to facilitate LISTJOINs

The LISTJOIN ER function is an analogue to the SQL UNION. It combines heterogenous record lists into one list of a common type. For example, a LISTJOIN(model.PurchaseLines, model.SalesLines) creates a typed single record list with their common fields: Product no, Quantity, Delivery date, Warehouse etc. However, for the LISTJOIN to recognize the common fields, the fields must be aligned, i.e. follow in exactly the same order, bear exactly the same names.

Here is where the references come into play. One can organize a “Dictionary” root entry in the model, define the most elementary composite entries there, then click the Switch item reference button elsewhere and include this small “brick” into a larger record. From the small bricks one may build larger bricks and so on. Such cross references are indicated by the asterisk (*):

In the above example, an Order record includes the CategoryComposite, Coverage order, Item order nested 1:1 records, and uses fields of the Category type and Line status enumerations. The resulting common Order record type is further assigned to the Sales and Purchase record lists, and this makes their structure in the model identical. The LISTJOIN() then produces a list of records with the following fields:

@.Amount
@.’Qty avail’
@.Category.Group
@.Category.’Category ID’

and so on.
By the way, the root node Item dictionary here is a Container. A Container is used simply to put together diverse artefacts, a way to make the model definition more readable.

References to apply different mappings to the same model

Imagine you need to export sales order lines and purchase order lines into 2 different files, similar in structure. You need a model to abstractly describe a generic Order line list, then a Sales line format export definition, a Purch line format definition both preferrably derived from a common Order line format, and 2 mappings: Sales line to model and Purch line to model to populate the Order line list model from 2 different data sources in Dynamics 365.

Try to run the Sales line format file. It is going to start complaining about 2 models present: “More than one model mapping exists. Set one of the configurations as default.” You set the Sales line to model as Default for model mapping = Yes and the export starts working.
No try to run the Purch line format. It is going to export sales order lines in the purchase order line format, because a link between the format and the outbound mapping is through the model node they use:

Format → Model [node] → [default] Model mapping

To fix this, the 2 formats should be mapped to different nodes in the model!

I’ve got a similar issue when I was trying to use the same model both for the export and for the import of data. There was a Counting journal model and 2 formats: Export to Kardex and Import from Kardex. There was a Counting model mapping for the export and a Counting model to destination mapping for the import.

Tried to run the export Export to Kardex and it asked to “Set one of the configurations as default“, which I did.
Then I tried to run the Counting model to destination mapping but it was not prompting any files for the upload, because a link between the inbound mapping to the import format was established through the model and it was pointing to the export format:

Model mapping to destination → Model [node] → Format

The trick is to use different nodes! The import format should write the data from the inbound file into one Record list in the model, while the export format should read data from another Record list in the model. The mappings then bind the same table to the one node and another, respectively. To reuse the data types and the structure, one node references the other (Switch item reference).

Electronic reporting blog series

Electronic reporting for data migration

Intro

There are still dozens of important tables in Dynamics 365 for Finance and SCM not exposed by any entity. Sometimes simple solutions like my Copy-paste with a keyboard script from Excel don’t work due to the volume or complexity of the data, and sometimes there is no UI at all.

One of the notorious examples is the table EcoResCatalogControl which is associated with product attributes bound to procurement categories, see the Searchable flag in my blog Searchable product attributes. An import of these “Product category attributes” through the entity EcoResProductCategoryAttributeEntity leaves the attributes dysfunctional: the internal table EcoResCategoryAttributeLookup is left out of sync and the new attributes remain invisible in the product master.

The only form where the EcoResCatalogControl is editable and visible is the Procurement category form, but an attempt to update the flag fails with a “Missing reference” error: the system expects a EcoResCatalogControl record to exist already. Dead end.

Electronic reporting: the last resort

Since the table browser is not an option anymore in a sandbox or production environment, the number of tools available to the consultant reduces to just one: Electronic reporting. Despite the name, the Electronic reporting module is able not only to read, but also freely insert, update or delete voluntary tables in D365FO.
In essence, the idea is to make a CSV text file and import it into the EcoResCatalogControl with the help of the Electronic reporting (ER).

This requires a so-called Mapping to destination where the “destination” is one or many tables or entities in D365FO. The concept is nicely outlined in the blog of Mr. Ties Philippi. In total, 4 “components” are required in at least 2 ER configurations (the Mapping to destination may in theory be detached into a separate – third – configuration).

Model
Model mapping “To destination”
[CSV file] Format
Model mapping [from format] ”To model”

The execution flows in the order (3) -> (4) -> (1) -> (2).
The 2 configurations I used can be downloaded here.

First, create a model, for the simplification its structure may follow exactly the table.

Next, create a mapping with the Direction = To destination. Add the target table to the right with the button Destination, then bind the model from the left to the table at the right side of the Model mapping designer. Change the status of the configuration to Complete.

Next, create a format configuration based on the model. It should describe the CSV file structure, namely a set of records (Lines) separated by CRLF, with 2 fields in every line, separated by the semicolon “;” (in a German version of the Excel; in an English version the comma “,” is more appropriate). The encoding of the CSV format should better be UTF-8 (Excel is able to produce UTF-8 encoded files).

Do not bind the format to the model, but use the button Map format to model to create a mapping of the same name. Bind the format to the model as shown on the screenshot below. The button Run can be used to test the mapping ad hoc: it takes a CSV file, interprets it according to the format definition, translates to the model internal container and exports this container to an XML file.

Once tested, update the format status to Completed. Make note that the import is started from the artefact (2) Model mapping to destination (with the button Run). The system looks for a format based on the model the mapping belongs to, and inside of that format it looks for a “To model” mapping.

Having found an appropriate format, the system asks for a CSV file and unleashes the import, there is no way back.

Update route

Added on 31.01.2020
Electronic reporting destination mappings can also be used to launch X++ code. If you have ever worked with production routes, you may have noted the Update route button. The class behind is called RouteUpdate and it is executed by the system automatically from the UI on any change in the order of operations. On plain production routes, it updates the Next operation numbers, and multiplies the variable scrap percentages to cache and store accumulated scrap factors. The problem is, this class cannot be run over all routes in the batch mode; in the Route headers entity they forgot to use it. Opening every single route out of thousands imported is obviously not an option.

I took the same CSV file and created a new destination mapping which updates the RouteTable. One column in the CSV file (Attribute) contains the key RouteId, the other (Category) bears the route name. I am updating the name by the key, but in the middle I am injecting the following code
RouteSearch.newRouteId(@.Attribute).routeId
like this
LEFT(RouteSearch.newRouteId(@.Attribute).routeId,0)&@.Category
It instantiates and executes the RouteSearch class which as a by-product calls RouteUpdate in its constructor method, then gives a routeId() value back which I neglect. Thousands of routes are updated blazing fast, and the Next operation and the Accumulated scrap is set everywhere:

The ER configuration can be downloaded here: RouteUpdateMapping.zip.

Open project milestones

Added on 16.04.2020
Finally, I have designed a data model and mappings for the fixed fee project On-account transactions aka Billing milestones. The configuration may take a project TransId from the CSV file, or it may create its own from the standard number sequence in the Project module parameters. Both the related tables ProjOnAccTrans + ProjOnAccTransSale are generated.

The ER configuration can be downloaded here: ProjOnAccTransModel.zip
Fun fact: a DMF entity for this existed in AX2012, but not D365.

Epilogue

The above crude trick works, but it is dangerous. Fixing a broken import might be a challenge, because to delete the data and start all over you need to change the destination Record action to Delete and then hope to find the right record by the primary key from the CSV file.

I would love to use standard entities, and make Microsoft add them to the application. Please vote for my 2 “favourites”:

the management of EcoResCatalogControl in an entity and…
the open (not invoiced) project milestones ProjOnAccTrans + ProjOnAccTransSale.