Merge Fields in Document Output
This article describes how to use and set up merge fields in Continia Document Output. Merge fields enable the solution to fetch data from Microsoft Dynamics 365 Business Central fields or codeunits. The fetched data can then be used in email templates to dynamically populate content with relevant master data or contextual values.
For example:
- Add a document number to the naming convention for attached report PDFs.
- Include the output of a codeunit that counts the number of documents included in an email.
- Fetch and display the name of the recipient.
How merge fields work
Continia Document Output uses the Document Output Field Table to establish a path from the source data to the merge field in the email template. The path depends on the Business Central table linked to the email template. Since the path can vary based on table relations, merge fields must be set up individually for each email template.
Merge fields are configured on each individual email template. A unique number must be assigned to each merge field.
For signature templates, any merge fields used in the signature must also be configured on the email templates where the signature templates are applied.
To configure merge fields
In the following section, you'll find the procedure for how to configure merge fields. By following these steps, you can set up and manage merge fields effectively to enhance the dynamic capabilities of your email templates in Continia Document Output.
- Search () for and select Email Templates.
- Select an email template, and select the number in No. of Merge Fields in the General FastTab to access the field table.
- Select New and assign a unique number in the Number field.
- Provide a description in Description.
- Choose a type in Type. The options are:
- Text: Inserts the value as plain text.
- Hyperlink: Inserts the value as a clickable web link.
- Link to Email Address: Inserts a clickable email link.
- Picture: Inserts an image.
- Set the data source in Get Field From. The options are:
Table: Fetches data from the table linked to the email template or its relations.
Setup Table: Fetches data from a setup table with a single record.
Sales Person: Fetches data from the Salesperson/Purchaser table linked to the current user.
Employee: Fetches data from the Employee table via the Salesperson/Purchaser link.
Note
While the "Sales Person" uses the link to current user for fetching a field value from the "Salesperson/Purchaser" table, the "Employee" does not have a direct link like that. It also relies on the "Salesperson/Purchaser" link to the current user for identifying the correct employee record using the Salesperson/Purchaser code.
UserID: Fetches the current user ID.
Company Name: Fetches the name of the current company.
Codeunit: Fetches the output of a specified codeunit (see the developer guide for custom codeunits). If you select Codeunit, be sure to fill in Codeunit ID in step 7 below.
User Full Name: Fetches the full name of the current user.
- Configure additional settings:
- Get From Table: Automatically populated, blank, or offers a table choice based on the selected data source.
- Get From Field: Select the specific field to fetch data from. Click Finish to add the field or Next to open related tables if applicable.
- Format String: Enter formatting codes to specify how fetched data is presented.
- Web Address: Enter the URL for a hyperlink or email link.
- Show Text: Enter static text to overwrite or append data using
%1as a placeholder for field or codeunit data. - Width and Height: Specify dimensions for images inserted into the email.
- Codeunit ID: Enter the codeunit ID (see the developer guide for details). The built-in merge-field codeunit is 6175282.
- Codeunit Parameter: Specify the value to extract from the codeunit. For a list of built-in codeunit parameter values, see Built-in codeunit parameter values below.
Built-in codeunit parameter values
Codeunit parameter values are used when you configure a merge field with Get Field From: Codeunit and a Codeunit ID (see steps 6-7 in the guide above under To configure merge fields). Document Output comes with a built-in merge-field codeunit – 6175282 – which includes the parameter values listed in the table below.
If you enter or select codeunit 6175282 under Codeunit ID in step 7 of the guide above, enter one of the following values under Codeunit Parameter, depending on what you want to merge:
| Parameter value | Description |
|---|---|
| PackTrack | A tracking link/text for a shipment, built from the shipping agent's tracking template combined with the package tracking number, ship-to country, shipment date, and shipping agent account number. Only works on shipment documents that have a shipping agent assigned; returns nothing otherwise. |
| ShippingAgent | The name of the shipping agent linked to the document. |
| SalespersonName | The name of the salesperson/purchaser linked to the document. |
| SalespersonJobTitle | The job title of the salesperson/purchaser linked to the document. |
| SalespersonPhoneNo | The phone number of the salesperson/purchaser linked to the document. |
| SalespersonEMail | The email address of the salesperson/purchaser linked to the document. |
| Contact1FirstName | The first name of the document's primary contact (such as the sell-to contact). |
| Contact2FirstName | The first name of the document's secondary contact, for documents that carry two separate contact fields (such as sell-to contact and bill-to/ship-to contact). |
| Contact1Surname | The surname of the primary contact. |
| Contact2Surname | The surname of the secondary contact. |
| Contact1FormalSalutation | A formal salutation for the primary contact (such as "Dear Mr. Smith"), generated from the salutation setup for that contact's language. Falls back to the contact's plain name if no salutation is set up. |
| Contact2FormalSalutation | The same as Contact1FormalSalutation, but for the secondary contact. |
| Contact1InformalSalutation | An informal salutation for the primary contact (such as "Hi John"). Falls back to the contact's plain name if no salutation is set up. |
| Contact2InformalSalutation | The same as Contact1InformalSalutation, but for the secondary contact. |
| VATAmount | The VAT amount on the document (Amount Including VAT minus Amount). Only available on sales and purchase orders, invoices, and credit memos; returns nothing on other document types. |
| BalanceDue | The customer's outstanding balance as of the document/statement date and formatted in the customer's currency. Works directly on customer records, and on sales documents, reminders, and finance charge memos linked to a customer. |
| BalanceDueLCY | The same as BalanceDue, but shown in the local currency (LCY) regardless of the customer's currency |
| Count | The number of records included in the current email (such as the number of documents being sent together). Reflects whatever set of records the template is currently processing, not a fixed total. |
| NextStatementNo | The next statement number for a customer (last statement number + 1). Only works on customer records. |
Hinweis
If a merge field has no value to draw from – for example, because no salesperson, shipping agent, contact, or customer is linked to the document, or because the field isn't supported on that document type – it returns blank rather than an error. This is expected behavior.