The core concepts to create a template considered for XML or text are the same as for any other template you create with DocumentsCorePack. However, since the generation process for these files is handled differently, this article will cover those differences, along with providing examples on how to create templates for XML or plain text files.
Prerequisites:
- DocumentsCorePack Server: Version 2024.2 or higher (learn how to update here)
Differences from normal templates
When creating templates for XML or plain text, there are a few things to keep in mind, as certain features are not recommended for use in the document generation process:
- XML Templates
- Headers/footers, tables, shapes, images and content controls should not be added to XML templates. Including any of the aforementioned elements will result in an XML validation error during the document generation process.
- Plain Text Templates
- Headers and footers may be added, though they will only appear at the top and bottom of the text file respectively.
- Tables, shapes, images and content controls are removed when the document is converted to plain text, though text within these will remain.
- These items can be used in a template, but they will be removed during the conversion process as these elements do not exist in text files.
Tables created via DocumentsCorePack can still be included in templates for XML or text, since they form a line item structure during the generation process that allows data to be filled in which is later removed during file conversion. Similarly, condition fields along with other complex fields (such as advanced string fields, calculated fields and prompts) can still be used.
It is important to be mindful of these limitations while creating XML/plain text templates, especially for XML templates used for E-Invoicing.
Create a template considered for plain text (.txt)
In this example, we will create a simple CSV (comma-separated values) file that displays an account’s contacts, as shown below.
We will begin by adding text and establishing a relationship to our contact entity.
Then, we’ll create the table starting with the Full Name field, followed by the First Name, Last Name, and Company Name fields.
We will save and upload this template to our Dataverse environment. When we go to generate a document based on this template in the DocumentsCorePack Dialog, we will select text as the Filetype.
Click Create Document to generate a document. The resulting downloadable file will be in plain text (.txt).
You can download this sample in the Attached Files section of this article (“CSV-Sample”) to try this template yourself.
Create a template considered for XML (.xml)
XML Description
While XML is incredibly useful, it can also be challenging for non-technical users because it requires attention to detail and understanding of structured data. If you’re comfortable with technology and already know what XML is, feel free to skip this section.
XML stands for eXtensible Markup Language, and it’s a way to organize and store data in a structured format that’s easy for both humans and computers to understand. XML can be thought of like a set of labeled boxes, where each box has a clear name that tells you what’s inside.
<?xml version="1.0" encoding="utf-8" ?>
<Invoice>
<InvoiceNumber>12345</InvoiceNumber>
<Date>2024-09-25</Date>
<CustomerName>John Doe</CustomerName>
<TotalAmount>500.00</TotalAmount>
</Invoice>In the above example:
- <Invoice> is like the outer box that holds everything about the invoice.
- Inside, you have smaller boxes like <InvoiceNumber>, <Date>, <CustomerName>, and <TotalAmount>—each holding specific pieces of information.
More information on XML can be found here.
Example
In this example, we will create an invoice template designed for generating a complex UBL xml file.
You will first need to prepare an XML file, with placeholders or sample data included where normal data would be. These will be replaced with dynamic fields later. We will be using the following XML.
Formatting our XML for Word
We would need to copy and paste this XML into Word, however, in doing so, we would notice that text would lose its color and formatting, making it difficult to read.
To fix this, we will make use of a code editor known as NotePad++, which can be downloaded here. Once installed, open the program and paste the XML into the editor. After changing the language to XML under Language > XML, the color will be reapplied.
Next, navigate to Plugins > NppExport > Export to HTML to save the file.
Once saved, copy the full file path of the file and return to Word. Under the Insert tab, navigate to Text > Quick Parts > Field. In the opened window, select IncludeText under Field names. In the Filename or URL field, paste the file path and click OK.
This will add the correctly-formatted contents of the file via field code. Highlight the newly added content and enter CTRL + SHIFT + F9 to convert the content to actual text. This will convert the field code to proper text, allowing you to freely edit the content.
Note: Change the view to Web Layout for an easier overview. This can be accessed via the View tab under Views.
With the XML added, you can now replace the placeholders/sample data in your template with dynamic fields from the DocumentsCorePack Template Designer.
Replacing our fields and testing our template
Standard fields can be inserted like usual. For numerical values or date fields, formatting may be required depending on the desired value.
Dynamic tables can also be inserted by selecting a field from a relation within the Template Designer, but with only one cell and no headers or footers, as shown below.
To create repeating blocks of XML in the result document, copy and paste the desired XML content into the table. Be mindful of your XML tags before inserting them into a block.
Note that in this example, the SEQ field code is used to increment the item number for each table row.
After replacing your sample data and creating any needed tables, save your template to your environment. From the DocumentsCorePack Dialog, select your template and choose the XML Filetype.
Once the document has been generated, you can open the newly-created XML file to view the result.
You can download this sample in the Attached Files section of this article (“InvoiceTemplate-xml-UBL_2.1”) to try this template yourself. Another template (“InvoiceTemplate-xml-CII_D16B”) can be downloaded as well.
Validation
If your template is intended to be used for e-invoicing in a specific standard we recommend you verify your result with a validation tool to check for your specific compliance. In the event any issues are detected, simply adjust your template based on the conformity checks. Validation tools can be found available online.
Note: In XML, special characters like <, >, &, ', and " are not allowed directly because they interfere with the document’s structure and parsing. They must be escaped to ensure proper processing. If such characters appear in data, CDATA sections can be used to include them without escaping (see here for more information).
XML Snippets
XML snippets can also be added to existing XML templates, but must be added and formatted following the same instructions as above. Under Attached Files is .zip containing two snippets (“XML-Snippets.zip”) that you can add to your own templates for testing purposes, one for the UBL template and one for the CII template.
Dealing with Byte Order Marks
Some XML files may contain Byte Order Marks, which can cause problems with the document generation process. In case such issues occur, the encoding can be modified by creating the following SettingsKey in your environment:
- Name: XmlEncoding
- Product: AutoMerge
- Value: UTF8
Alternatively, the encoding can be modified for the problematic template by manually adding the following document property:
- Name: WordMailMergeXmlEncoding
- Value: UTF8
External Links
Extensible Markup Language (XML), World Wide Web Consortium (W3C)
That’s it! We appreciate your feedback! Please share your thoughts by sending an e-Mail to support@mscrm-addons.com.