Advanced Email Tokens

Starting with v.3.5.1 you can configure and use Advanced email tokens.

When selecting email tokens in the Docentric Email print destination, the following  token types are now available:

• Standard D365FO email tokens: the most commonly used are Customer/Vendor purpose and primary contact.
• Additional Docentric email tokens: these tokens cover most common scenarios that are not supported by standard D365FO tokens. See a list of available tokens >>
• Docentric Advanced email tokens: these tokens support both common and advanced scenarios through flexible configuration.

You can use any combination of these email token types.

The Advanced email token lookup offers a list of Advanced email tokens configured in the Advanced email tokens setup form.

Advanced email tokens setup

Open the Advanced email tokens setup form:

• Go to  Docentric AX Workspace > Related > Print management > Advanced email tokens, or
• Go to Organization administration > Docentric AX > Print management > Advanced email tokens.

An Advanced email token consists of:

• Header, which defines the general properties of the token, and
• Lines, which define how email addresses are resolved.

Header

Important header fields:

• Advanced email token ID: specifies the unique identifier of the Advanced email token. This identifier is used when selecting the token in the Email tokens dialog.
• Enabled: determines whether the token is available for selection. Only enabled tokens are shown in the lookup in the Email tokens dialog.
• Warning level: specifies how the system behaves when some token lines do not return any email addresses. Available options:
  • Detailed: displays detailed diagnostic information. Use this option during configuration and troubleshooting, when you need to understand why certain email addresses were not resolved.
  • Summary: displays a short warning message indicating that some lines did not return any email addresses. Use this option in production when you want to be notified about incomplete results, without showing detailed information.
  • None: no warning message is displayed. Use this option when missing email addresses are expected. This option is typically used together with the Unresolved email tokens handling setting. Learn more about Unresolved email tokens handling >>

Lines

Configure one or more lines for each Advanced email token.

Each line defines how email addresses are resolved. Lines are processed in the order in which they appear in the form.

Line fields:

• Enabled: only enabled lines are processed.
• Source table: defines from which record to start looking for the email addresses. See details below.
• Apply email tokens to: further refines the location of email addresses. See details below.
• Filter address by purpose: enabled when Apply email tokens to is set to Logistics address(es), and multiple resulting logistics addresses are possible. In that case, this field further refines the selection of applicable logistics addresses. See details in Appendix A.
• Use tokens: enabled when multiple email addresses are possible as a result of previous 3 fields setup. In that case, this field further refines the selection of email addresses. See details below.
• Purpose: used in combination with the Use tokens field, if it involves filtering by purpose. See details below.
• When to resolve: controls whether a line is processed, depending on the results of previous lines. This allows you to configure fallback logic.

Line field: Source table

This field defines the starting record used to resolve email addresses. It is a record that is related to the journal being printed, and can be one of the following:

• Invoice account, Order account: related Invoice or Order account. See Appendix C for explanation and exact field names on different journals that are used to identify these two accounts.
• Order, Project, Quote, RFQ: related Order/Project/Quote or RFQ where applicable.
• Legal entity: current legal entity.
• Custom record: if none of the above tables suits your needs, use this option and implement your own logic for identifying the related table.

Line field: Apply email tokens to

This field further refines the location of email addresses. It can have the following values:

• Email(s): one or more email addresses found on the Source table.
  • Some Source table types can have multiple email addresses, found in the Contact information fast tab (see image below). Those are Invoice account, Order account, Legal entity, Prospect and potentially Custom record.
     
    

  • Other Source table types have only one email address, found usually in the Email field of the related form (see image below). Those are Order, Project, Quote, RFQ and potentially Custom record.
     
    

• Contact person(s): email addresses found on Contact persons related to the selected Source table. Contact persons can have multiple email addresses, found in their Contact information fast tab. Applicable to all Source table types except Project, Legal entity and Prospect.
• Logistics address(es): email addresses for one or more Logistics addresses related to the Source table.
  • Some Source table types can have multiple logistics addresses, found in the Addresses fast tab (see image below). Those are Invoice account, Order account, Legal entity, Prospect and potentially Custom record. In this case, you need to additionally specify which logistics addresses to use, by selecting one or more purposes in the Filter address by purpose field (see further explanation below).
     
    

  • Other Source table types have only one logistics address (see image below). Those are Order and potentially Custom record.
     
    

Line field: Filter address by purpose

When Apply email token to is Logistics address(es), and multiple logistics addresses are possible for a given Source table, then this field allows specifying the purpose of logistics addresses where the email addresses are to be found.

Hint: if any logistics address is acceptable (i.e. no filtering by purpose is needed), select all offered purposes.

See Appendix A for all possible combinations of these 3 fields.

Line fields: Use tokens, Purpose

With the exception of Source table being one of Order/Project/Quote/RFQ when Apply email tokens to is Email(s), all other combinations in the above setup can result in multiple email addresses. In such cases, the combination of Use tokens and Purpose fields specifies how to filter these addresses.

Table below lists all possible Use tokens options:

Use tokens	Purpose	Comment
Only primary	N/A	Retrieves only the primary email address. This option is equivalent to  the standard @@ token.
Only non-primary	N/A	Retrieves all non-primary email addresses.
Only selected purposes	One or more purposes	Retrieves all email addresses having one or more purposes matching at least one purpose specified in the Purpose field, regardless of the primary flag. This option is equivalent to standard @Invoice@ token when e.g. Invoice purpose is selected
Primary having selected purposes	One or more purposes	Retrieves the primary email address that has one or more purposes matching at least one purpose specified in the Purpose field.
Non-primary having selected purposes	One or more purposes	Retrieves all non-primary email addresses that have one or more purposes matching at least one purpose specified in the Purpose field.

Testing

To test the Advanced email tokens, you don’t need to execute the report. Instead, click the Test token button:

A new form is displayed, where you see all lines from the caller token.

1. Select the Journal type and Journal record for which you want to test the result and click the Test button.
2. Results for each line will be displayed in the Line result column.
3. If line cannot be resolved, the reason is printed in the Warning message column. This is the same message that is printed in runtime if Warning level is Detailed.
4. All Line result values are combined, duplicate email addresses are removed and the final result is displayed in the Resolved Advanced email token.

Data management

For export/import scenarios use the Docentric Advanced email tokens data entity.

Appendix A: Possible source combinations

Table below lists all possible combinations of line fields Source table, Apply email tokens to and Filter address by purpose.

Source table	Apply email tokens to	Filter address by purpose
Invoice account	Email(s)
Invoice account	Contact person(s)
Invoice account	Logistics address(es)	e.g.: Delivery
Order account	Email(s)
Order account	Contact person(s)
Order account	Logistics address(es)	e.g.: Unlading
Order	Email(s)
Order	Contact person(s)
Order	Logistics address(es)
Project	Email(s)
Quote	Email(s)
Quote	Contact person(s)
RFQ	Email(s)
RFQ	Contact person(s)
Legal entity	Email(s)
Legal entity	Logistics address(es)	e.g.: Business
Prospect	Email(s)
Prospect	Logistics address(es)	e.g.: Other
Custom record	Email(s)
Custom record	Contact person(s)
Custom record	Logistics address(es)	e.g.: Payment

Appendix B: Examples

Invoice account primary email

Note: this is equivalent to the standard @@ email token in case of reports using Invoice account, i.e. Sales invoice (CustInvoiceJour).

• Source table = Invoice account: find the Customer/Vendor from the Invoice account on the journal. Notice that not all journals have the InvoiceAccount field, and in such case token will be resolved as an empty string. See Appendix C for details.
• Apply email tokens to = Email(s): look for the Email addresses of that Customer/Vendor, found on the Contact information fast tab.
• Use Primary email token = Yes: from the available Email addresses take the one marked as Primary.

Source table	Apply email tokens to	Filter address by purpose	Use token	Purpose	When to resolve
Invoice account	Email(s)	disabled	Ony primary	disabled	Always

Invoice account purpose

Note: this is equivalent to the standard purpose email token in case of Sales/Vendor/Project invoice reports.

• Source table: the same as in the Invoice account primary email example above.
• Apply email tokens to: the same as in the Invoice account primary email example above.
• Use Purpose token = Invoice;Business: from the available Email addresses take those having Invoice and/or Business purpose.

Source table	Apply email tokens to	Filter address by purpose	Use token	Purpose	When to resolve
Invoice account	Email(s)	disabled	Only selected purposes	Invoice;Business	Always

Order account primary email

Note: this is equivalent to the standard @@ email token in case of the reports using Customer/Vendor (i.e. Order) account, e.g. Sales confirmation report (CustConfirmJour), Sales packing slip (CustPackingSlipJour), etc.

• Source table = Order account: find the Customer/Vendor from the Customer/Vendor account on the journal.
• Apply email tokens to = Email(s): look for the Email addresses of that Customer/Vendor, found on the Contact information fast tab.
• Use Primary email token = Yes: from the available Email addresses take the one marked as Primary.

Source table	Apply email tokens to	Filter address by purpose	Use token	Purpose	When to resolve
Order account	Email(s)	disabled	Only primary	disabled	Always

Invoice account’s Contact person’s primary email

Configuration:

• Source table = Invoice account: find the Customer/Vendor from the Invoice account on the journal.
• Apply email tokens to = Contact person(s): for that Customer/Vendor find the linked Contact persons. On the linked Contact persons look for the Email addresses in the Contact information fast tab.
• Use Primary email token = Yes: from available Email addresses take those marked as Primary.

Source table	Apply email tokens to	Filter address by purpose	Use token	Purpose	When to resolve
Invoice account	Contact person(s)	disabled	Only primary	disabled	Always

Invoice account’s Logistics address having Invoice purpose, its Invoice purpose email 😊

Configuration:

• Source table = Invoice account: find the Customer/Vendor from the Invoice account on the journal.
• Apply email tokens to = Logistics addresses; Filter address by purpose = Invoice: for that Customer/Vendor find the Logistics addresses having the Invoice purpose.
• Use Purpose token = Invoice: for the Logistics addresses identified in the previous step, take their Email addresses having the Invoice purpose.

Source table	Apply email tokens to	Filter address by purpose	Use token	Purpose	When to resolve
Invoice account	Logistics addresses	Invoice	Only selected purposes	Invoice	Always

Note 1: this allows for any combination of purposes to be used for identifying the Logistics addresses and Email addresses.

Invoice account’s Logistics address having Delivery purpose, its Delivery purpose email 😊

Configuration:

• Source table = Invoice account: find the Customer/Vendor from the Invoice account on the journal.
• Apply email tokens to = Logistics addresses; Filter address by purpose = Delivery: for that Customer/Vendor find the Logistics addresses having the Delivery purpose.
• Use Purpose token = Delivery: for the Logistics addresses identified in the previous step, take their Email addresses having the Delivery purpose.

Source table	Apply email tokens to	Filter address by purpose	Use token	Purpose	When to resolve
Invoice account	Logistics addresses	Delivery	Only selected purposes	Delivery	Always

Note: How is this different from the Docentric @DLV_Delivery@ token? Instead of the first two steps above, we always identify the Logistics address as the value from the Delivery address field on a journal. There can be multiple Logistics addresses with Delivery purpose, and only one of them is stored on the journal. For that Logistics address specifically we take its Email addresses having the Delivery purpose.

Order email

Note: this is equivalent to Docentric @OrderEmail@ token.

• Source table = Order: find the related Sales/Purchase order.
• Apply email tokens to = Email(s): take the value from the Email field on Sales/Purchase order header.

Source table	Apply email tokens to	Filter address by purpose	Use token	Purpose	When to resolve
Order	Email(s)	disabled	disabled	disabled	Always

Order email, fallback to Order Contact's email

First line is resolved based on this setup:

• Source table = Order: find the related Sales/Purchase order.
• Apply email tokens to = Email(s): take the value from the Email field on Sales/Purchase order header.

If the result of first line is empty string, then process the next line:

• Source table = Order: find the related Sales/Purchase order.
• Apply email tokens to = Contact person(s): On that Sales/Purchase order use the value from the Contact person field. On that Contact person look for the Email addresses in the Contact information fast tab.
• Use Primary email token = No, Use Purpose token = Invoice: from the available Email addresses take those having the Invoice purpose, ignoring the Primary flag (i.e. both primary and non-primary email addresses are considered).

Source table	Apply email tokens to	Filter address by purpose	Use token	Purpose	When to resolve
Order	Email(s)	disabled	disabled	disabled	Always
Order	Contact person(s)	disabled	Only selected purposes	Invoice	If previous results are empty

Projects’ emails + Invoice account’s Contact’s primary email

First line is resolved based on this setup:

• Source table = Project: find the related Projects.
• Apply email tokens to = Email(s): use the value from the Email field on all related Projects.

Then continue with processing the next line and append its results to the results of the first line:

• Source table = Invoice account: find the Customer from the Invoice account on the journal.
• Apply email tokens to = Contact person(s): find all Contact persons linked to that Customer. On the linked Contact persons find the Email addresses on the Contact information fast tab.
• Use Primary email token = Yes: from the Email addresses filtered as above, take those marked as primary.

Source table	Apply email tokens to	Filter address by purpose	Use token	Purpose	When to resolve
Project	Email(s)	disabled	disabled	disabled	Always
Invoice account	Contact person(s)	disabled	Only primary	disabled	Always

Note: similar examples can be tested for Quote and RFQ source tables.

Legal entity’s primary email

Configuration:

• Source table = Legal entity: find the current Legal entity.
• Apply email tokens to = Email(s): for that Legal entity find Email addresses on the Contact information fast tab.
• Use Primary email token = Yes: from the available Email addresses take the one marked as Primary.

Source table	Apply email tokens to	Filter address by purpose	Use token	Purpose	When to resolve
Legal entity	Email(s)	disabled	Only primary	disabled	Always

Legal entity’s Business Logistics address primary email

Configuration

• Source table = Legal entity: find the current Legal entity.
• Apply email tokens to = Logistics addresses; Filter address by purpose = Business: for the current Legal entity find the Logistics addresses having the Business purpose.
• Use Primary email token = Yes: from the Email addresses belonging to the Logistics addresses filtered as above, take the ones marked as Primary.

Source table	Apply email tokens to	Filter address by purpose	Use token	Purpose	When to resolve
Legal entity	Logistics addresses	Business	Only primary	disabled	Always

Appendix C: Invoice account vs. Order account

In some scenarios it can happen that one account orders the goods/services and another account is to be invoiced. First one is displayed in D365FO as Customer account field, and the second one as Invoice account.

Note: Docentric uses the Order account name instead of Customer/Vendor account, as it better describes its purpose.

Standard D365FO logic for resolving the email tokens uses:

• Invoice account for invoices (CustInvoiceJour, ProjInvoiceJour, VendInvoiceJour) and vendor packing slip (VendPackingSlipJour)
• Order account for all other journals

Table below shows the field names for Order and Invoice account on different journals. Bold formatted fields are used by standard D365FO logic for resolving the email tokens. For example, @@ token on Sales invoice (CustInvoiceJour journal) will take the Customer from the InvoiceAccount field and look for its primary email. On the other hand, @@ token on Sales packing slip (CustPackingSlipJour journal) will take the Customer from the OrderAccount field and look for its primary email.

Journal name	Order (Customer/Vendor) account field name	Invoice account field name
CustInvoiceJour	OrderAccount	InvoiceAccount
ProjInvoiceJour	OrderAccount	InvoiceAccount
VendInvoiceJour	OrderAccount	InvoiceAccount
VendPackingSlipJour	OrderAccount	InvoiceAccount
CustCollectionLetterJour	OrderAccount
CustConfirmJour	OrderAccount	InvoiceAccount
CustInterestJour	OrderAccount
CustPackingSlipJour	OrderAccount	InvoiceAccount
CustQuotationJour	OrderAccount	InvoiceAccount
CustTable	OrderAccount	InvoiceAccount
PurchAgreementHeaderHistory	VendAccount
PurchConfirmationRequestJour	OrderAccount
SalesAgreementHeaderHistory	CustAccount
VendPurchOrderJour	OrderAccount
VendReceiptsListJour	VendAccount
VendRFQJour	VendAccount
VendTable	OrderAccount	InvoiceAccount
WMSBillOfLading	OrderAccount
WMSPickingRoute	customer

Note: all journals where standard uses Invoice account have also the Order account field. The opposite is not true: only some Order account – based journals have the Invoice account field too.

Note for nerds: we extracted this information by opening the CustVendAccountMap map and searching for all references to the Account field. The result showed us which account types (Customer/Vendor i.e. Order or Invoice) are used by standard D365FO when resolving the email tokens.

See also

Unresolved Email Tokens Handling >>
Report Email Sending Settings >>
How to Use Report Email Templates >>