Chapter 06: Template Management, Testing, and Troubleshooting

6.1 Template Import and Export

The Advanced Email App provides XML-based import and export functionality that allows you to transfer email templates between environments, share templates with other organizations, create backups, or deploy standardized templates across multiple Business Central installations.

Understanding XML Template Format

Email templates are stored internally in Business Central tables, but the system can export them to XML format files and import templates from XML files. This XML format is human-readable and includes all template configuration:

• Basic email information (code, description, recipients)

• Email subject and body content

• Attachment configurations (both fixed files and report attachments)

• Linked triggers, scenarios, source references, and actions

• Rule group assignments

When you export an email template, all related configuration exports as a single XML file. When you import, all this configuration is recreated in the target environment.

📋 NOTE: The XML export includes configuration information (what report to attach, what triggers to use) but does NOT include actual file attachments. If you export an email template with fixed file attachments, the import will create the attachment record configuration, but you'll need to manually upload the actual files in the destination environment.

Exporting Templates

To export email templates to XML:

1. Navigate to the Advanced Emails list page.

2. Select one or more email templates you want to export. Use checkboxes or Ctrl+Click to select multiple templates if needed.

3. Click the Create Default Data action. (This action name may vary slightly by version—look for "Export" or "Create XML" or similar if "Create Default Data" isn't visible.)

4. The system generates an XML file containing the selected templates and prompts you to download it.

5. Choose a meaningful filename and location to save the XML file. Use descriptive names like "OrderConfirmation_Templates_2024.xml" or "PurchaseNotifications_Export.xml" that indicate the content and export date.

6. Save the file. You now have an XML backup of your templates that can be imported into another environment or archived for safekeeping.

Use Cases for Export:

• Development to Production Migration - Configure and test email templates in a development or sandbox environment, export them, and import them into production when ready.

• Backup and Version Control - Periodically export your working email templates and store the XML files in version control or backup storage. If templates are accidentally modified or deleted, you can restore from XML.

• Template Sharing - Share email template designs with other organizations, partners, or other Business Central installations in your organization.

• Documentation - The XML file provides a complete record of template configuration that can be reviewed, documented, or audited without accessing the live Business Central system.

Importing Templates

To import email templates from XML:

1. Obtain the XML file containing the templates you want to import. This might be a file you previously exported, a file received from another organization, or a template set provided by a consultant.

2. Review the XML file content if needed to understand what templates it contains. The XML is text-based and can be opened in any text editor.

3. Navigate to the Advanced Emails list page in Business Central.

4. Click the Import action (exact name may vary by version—look for "Import XML" or "Load Template" or similar).

5. Browse to and select the XML file to import.

6. The system reads the XML file and creates or updates email templates based on its content.

7. Review the imported templates in the Advanced Emails list to verify they imported correctly.

⚠️ WARNING: Importing templates with the same Code values as existing templates will typically overwrite the existing templates. Before importing, verify whether the XML contains new templates or is meant to update existing ones. Consider exporting your current templates as a backup before importing, so you can restore if the import has unexpected results.

Import Behavior Details:

New Template Codes - If the XML contains email template codes that don't exist in the current environment, the import creates entirely new email templates with all their configuration.

Existing Template Codes - If the XML contains email template codes that already exist, the import typically updates those templates with the XML's configuration, overwriting current settings.

Referenced Configuration - If the imported templates reference rule groups, tables, fields, or reports by ID, those IDs must exist and be valid in the target environment. For example, if a template references Report ID 50100 (a custom report), that report must exist in the target environment, or the template won't function correctly.

File Attachments - As noted earlier, fixed file attachments don't export in the XML. After importing templates with fixed file attachments, manually upload the actual files through each template's attachment configuration.

Template Deployment Strategy

For organizations managing multiple Business Central environments (development, test, production), establish a disciplined template deployment workflow:

1. Develop and Test - Create and thoroughly test new email templates in a development environment

2. Export Tested Templates - Export working templates to XML files

3. Version Control - Store XML files in version control with documentation

4. Test Import - Import to a test/staging environment and verify behavior

5. Production Deployment - Import to production during a planned change window

6. Validation - Test production templates with non-critical scenarios before enabling for all users

7. Documentation - Update runbooks and user documentation to reflect new templates

6.2 Testing Email Configurations

Thorough testing is essential to ensure email templates send at the right times, to the right recipients, with the correct content and attachments. Testing should occur before deploying templates to production and should be repeated after any significant configuration changes.

Pre-Production Testing Strategy

Before making an email template active for production use, systematically test all its components:

1. Static Content Testing - Verify that fixed elements (static recipient addresses, static subject lines, fixed body text) appear correctly:

• Create a test record that should trigger the email

• Verify recipient To/Cc/Bcc fields contain correct addresses

• Verify subject line text is correct

• Verify body content displays correctly

2. Placeholder Testing - Verify that all placeholders replace with actual data:

• Create test records with known data values

• Trigger the email

• Verify each placeholder in subject and body replaced with expected values

• Check for unreplaced placeholders (still showing [TableID:FieldID] syntax) indicating configuration errors

3. Attachment Testing - Verify that attachments include correctly:

• For fixed file attachments: verify the correct files attach

• For report attachments: verify the report generates and attaches with correct filtering

• Verify attachment filenames are correct and meaningful

4. Trigger Testing - Verify the email sends at correct times:

• Perform actions that should trigger the email and verify it sends

• Perform similar actions that should NOT trigger the email and verify it doesn't send

• Test timing (Before/After) by checking email content reflects correct data state

5. Scenario Testing - Verify scenario conditions work correctly:

• Create test records that meet scenario conditions and verify email sends

• Create test records that don't meet conditions and verify email doesn't send

• Test boundary conditions (values exactly equal to condition thresholds)

6. Rule Group Testing - If using rule groups, verify group membership controls triggering:

• Trigger email as a user who IS in an assigned group and verify it sends

• Trigger email as a user who IS NOT in any assigned groups and verify it doesn't send

7. Complex Logic Testing - For emails with multiple scenarios, multiple conditions, or complex linked table logic:

• Create a test matrix showing different combinations of conditions

• Test each combination

• Document results to verify all logic paths work as expected

✅ EXAMPLE: Order Confirmation Testing Matrix

For an order confirmation email that should send to customers when orders exceed $1,000 and are created by sales representatives:

Testing Tools and Techniques

Validation Log Review - After each test, check the Validation Log (search for "QUA Validation Log" in Business Central) to see detailed information about what rules evaluated, what actions executed, and what data values were present. The log is invaluable for understanding why an email sent or didn't send.

Test Email Addresses - During testing, consider temporarily changing recipient email addresses to test accounts rather than sending test emails to real customers or external contacts. After testing completes, restore real recipient addresses.

Controlled Test Data - Create specific test records with known, controlled data values that make it easy to verify placeholder replacement and scenario logic. For example, create a test customer named "TEST CUSTOMER" with email "test@yourcompany.com" specifically for testing order notifications.

Step-by-Step Triggering - When testing triggers, perform actions slowly and deliberately, one at a time, checking results after each action. Don't create ten test orders simultaneously and then try to figure out which one triggered which email.

Email Client Filtering - When sending many test emails, configure email client rules to filter test emails into a dedicated folder so you can easily review them without cluttering your inbox.

Production Smoke Testing

After deploying email templates to production, conduct "smoke testing" to verify they work in the production environment before announcing them to users:

Limited User Testing - Have a small group of trusted users (or use a restricted rule group) perform real business operations that should trigger the emails. Verify emails send correctly with production data.

Monitor Initial Usage - Watch the Validation Log during the first hours or days after deployment to catch any unexpected errors or behaviors.

User Feedback - Solicit feedback from early users about email content, timing, and usefulness. Be prepared to make refinements based on real-world usage.

6.3 Monitoring and Validation Logs

The QUALIA Rule Engine (which powers the Advanced Email App) maintains detailed validation logs that record every rule evaluation, action execution, and error condition. These logs are essential for monitoring email automation, troubleshooting problems, and understanding system behavior.

Accessing Validation Logs

To view validation logs:

1. Use the search function in Business Central (magnifying glass icon 🔍) to search for "QUA Validation Log" or "Validation Log".

2. Open the QUA Validation Log page.

3. The log displays all rule evaluations and actions, most recent first by default.

Each log entry provides detailed information about what happened during a rule evaluation.

Understanding Log Entries

Validation log entries include extensive information:

Header Information:

• Entry No. - Unique identifier for this log entry

• Validation Set - The validation set (business rule configuration) that evaluated

• Date/Time - When the evaluation occurred

• User ID - Which Business Central user's action triggered the evaluation

• Result - Whether the rule's conditions were met (TRUE/FALSE)

Context Information:

• Source Table - The table where the triggering action occurred (e.g., Sales Header)

• Source Record ID - The specific record that triggered the rule (e.g., order number)

• Action Performed - What action occurred (INSERT, MODIFY, DELETE, VALIDATION)

Evaluation Details:

• Conditions Evaluated - What scenario conditions were checked

• Condition Results - Whether each condition was TRUE or FALSE

• Actions Executed - What actions ran as a result (Send Email, Show Message, etc.)

• Error Information - If errors occurred, detailed error messages

For Email-Specific Entries:

• Email Template Code - Which Advanced Email template was involved

• Recipients - What email addresses the system attempted to send to

• Success/Failure - Whether the email sent successfully

Using Logs for Troubleshooting

When an email doesn't send as expected, the Validation Log reveals why:

Scenario 1: Email Didn't Send

• Look for a log entry for the expected time and record

• If no entry exists: The trigger didn't fire (check trigger configuration, check user's rule group membership)

• If entry exists with Result=FALSE: Scenario conditions weren't met (check condition formulas, check actual field values)

• If entry exists with Result=TRUE but no email action: Action configuration problem (check action linking, check action condition formula)

Scenario 2: Email Sent to Wrong Recipients

• Find the log entry for the email that sent

• Review the Recipients field showing what addresses were used

• Trace back to the email template's recipient configuration

• Check placeholder replacement if using dynamic recipients

Scenario 3: Email Content Incorrect

• Log entries don't show full email content, but they show which template was used

• Verify you're looking at the correct template

• Check placeholder configuration in template

• Review source reference configuration if using linked table data

💡 TIP: When troubleshooting, use the Validation Log's filtering capabilities to narrow to specific validation sets, specific date/time ranges, or specific source records. This makes it much easier to find the relevant log entries among potentially thousands of entries.

Log Maintenance

Validation logs grow continuously as rules evaluate. Over time, this can consume database space and slow log queries. Consider implementing log maintenance procedures:

Periodic Archiving - Export old log entries to external storage and delete them from Business Central, retaining only recent logs (e.g., last 90 days) for active troubleshooting.

Selective Retention - Retain logs for critical or high-value email notifications longer than logs for routine notifications.

Performance Monitoring - If log queries become slow, review log size and implement more aggressive retention policies.

Business Central administrators can configure log retention policies, or you may need to develop custom maintenance procedures based on organizational requirements.

6.4 Common Issues and Solutions

Even well-designed email templates occasionally encounter problems. This section addresses the most common issues and their solutions.

Email Not Sending

Problem: You expect an email to send, but no email arrives and no error message appears.

Troubleshooting Steps:

1. Check Validation Log - Search the QUA Validation Log for entries matching the expected trigger time and source record.

   • No log entry: The rule didn't evaluate at all. Proceed to step 2.

   • Log entry with Result=FALSE: Scenario conditions weren't met. Proceed to step 5.

   • Log entry with Result=TRUE: Rule evaluated but action didn't execute. Proceed to step 6.

2. Verify Trigger Configuration - Open the email template and check the Triggers section.

   • Is a trigger configured? If not, add appropriate trigger.

   • Is the trigger on the correct table? Verify the table where your action occurred.

   • Is the trigger on the correct field? For MODIFY triggers, verify the field you're modifying is the trigger field.

   • Are the correct timing checkboxes selected (Before/After)?

3. Verify Rule Group Membership - If the email has rule groups assigned, verify the user performing the action is a member of at least one assigned group.

   • Check Rule Groups page to see group assignments

   • Verify user membership in those groups

   • Test with a user who IS in an assigned group

4. Check Validation Set Active Status - Each email template is linked to a validation set in the Rule Engine. Verify that validation set is marked Active.

   • Open the QUA Validation Sets page

   • Find the validation set linked to your email (code should match or be related to email code)

   • Verify the "Active" checkbox is selected

5. Review Scenario Conditions - If log entry exists with Result=FALSE, the trigger fired but scenario conditions weren't met.

   • Check what scenario conditions are configured

   • Review the actual data values in the record that should trigger the email

   • Verify the condition operator (equal, greater than, etc.) is correct

   • Check for subtle issues: text case sensitivity, leading/trailing spaces in text fields, date format mismatches

6. Verify Action Configuration - If log shows Result=TRUE but no action executed:

   • Open the email template's related validation set

   • Check that a "Send Email" action exists and is linked to the validation set

   • Verify the action's condition formula (if any) evaluates to TRUE

   • Check that the Action Code field on the email template matches the action code in the validation set

7. Test Email Infrastructure - Verify Business Central's overall email configuration is working:

   • Try sending a manual email from Business Central (use standard email functionality)

   • Check SMTP settings in Business Central setup

   • Verify network connectivity to email server

   • Check for email server errors or authentication issues

✅ EXAMPLE: Troubleshooting Missing Order Confirmation

A user reports that an order confirmation email didn't send for order SO-12345:

1. Check Validation Log for entries at the time SO-12345 was created → Found no log entry

2. Check email template triggers → Found trigger on Sales Header table, OnInsert timing

3. Check if order was created by inserting new record or by copying existing order → User copied from SO-12300

4. Realize that copying creates a new record through MODIFY of copied record, not INSERT

5. Solution: Add trigger for OnAfter Modify on Sales Header Document Type and No. fields

Placeholders Not Replacing

Problem: Email sends, but placeholders appear in the email as literal text like [18:5050] instead of replacing with actual data.

Troubleshooting Steps:

1. Verify Placeholder Syntax - Check that placeholders use correct syntax: [TableID:FieldID]

   • Verify table ID is correct

   • Verify field ID is correct

   • Ensure brackets are square brackets, not parentheses or other characters

   • Check for spaces inside brackets (should be no spaces: [18:2] not [18 : 2])

2. Check Table and Field Availability - Use the QUA Field page (search for "QUA Field") to verify the table and field IDs exist and are accessible.

3. Verify Source Record Context - Placeholders replace with data from the source record that triggered the rule.

   • For Sales Order emails, source record is the specific sales order

   • Placeholders must reference fields that exist on that source record's table

   • For linked table data, ensure source references are configured correctly

4. Review Linked Table Configuration - If placeholders should pull data from related tables (customer data from a sales order email):

   • Open the email template's validation set

   • Check QUA Source References configuration

   • Verify the linked table relationship is correct

   • Verify the referenced table ID and linked field relationships

5. Check Field Permission - Verify the user running the rule has permission to read the fields referenced by placeholders. Permission issues can prevent placeholder replacement.

6. Test with Simple Placeholder - Create a test email with a simple, known-good placeholder like [18:3] (Sales Header No. field) to verify basic placeholder functionality works, isolating whether the issue is with specific placeholders or all placeholders.

Attachments Not Attaching

Problem: Email sends, but expected attachments are missing.

For Fixed File Attachments:

1. Verify File Uploaded - Open the email template and check the Attachments section. Verify files show in the list and have non-zero file sizes.

2. Re-Upload File - Try deleting and re-uploading the file attachment. Occasionally upload processes don't complete successfully.

3. Check File Size - Very large attachments may fail to attach due to email server or Business Central limitations. Try with a smaller file to verify functionality works.

4. Verify Attachment Enable - Ensure the attachment record is marked as enabled/active (exact field name varies).

For Report Attachments:

1. Verify Report Exists - Check that the Report ID configured in the attachment actually exists in Business Central. Try running the report manually from the Business Central interface.

2. Test Report Filters - Report attachments automatically filter to the source record. Verify this automatic filtering works:

   • Manually run the report

   • Apply the same filtering (e.g., filter to specific order number)

   • Verify the report generates content with that filter

3. Check Output Format - Some reports don't support all output formats. If you've configured Excel output but the report doesn't support Excel, try PDF format.

4. Review Report Parameters - If the report requires parameters, those must be somehow provided or defaulted. Complex reports with required parameters may not work reliably as automatic attachments.

5. Test Without Attachment - Temporarily remove the attachment configuration and verify the email sends successfully. This isolates whether the attachment is causing email failure or just failing to attach while email otherwise sends.

Triggers Firing Too Often

Problem: Email sends more times than expected, or sends for records it shouldn't send for.

Troubleshooting Steps:

1. Review Trigger Timing - Check if both Before and After are selected. This causes the rule to evaluate twice for each action. Usually only After is needed.

2. Check Multiple Triggers - Verify you haven't accidentally configured multiple triggers that all fire for the same action. For example, OnModify for "All Fields" plus OnModify for specific Field No. causes double evaluation.

3. Add Scenario Conditions - If the trigger fires correctly but emails send for records that shouldn't trigger them, add scenario conditions to filter which records actually send emails.

4. Review Modify Triggers - OnModify triggers fire whenever any field in the trigger configuration changes. If you've selected "All Fields" or multiple fields, the trigger fires if any of those fields change, even if others don't. Refine the field list to only fields that should trigger the email.

5. Check Recursive Triggers - In rare cases, an email action might trigger a modification that triggers the same email again, creating a loop. Review whether the action the email performs could cause the same trigger to fire again.

6.5 Performance Optimization

For organizations with high transaction volumes or large email distribution, consider performance optimization to ensure email automation doesn't negatively impact Business Central responsiveness.

Best Practices for High-Volume Scenarios

Minimize Trigger Scope - Configure triggers on specific fields rather than "All Fields" when possible. This reduces how often the rule engine evaluates.

Efficient Scenario Conditions - Simple scenario conditions (direct field comparisons) evaluate faster than complex conditions involving multiple linked tables or calculations. Where possible, use straightforward conditions.

Limit Linked Table Depth - Each source reference that links to another table adds processing overhead. Design email templates to minimize the number of linked table relationships required.

Batch Processing Consideration - Be aware that if users perform batch operations (creating or modifying many records at once), each record may trigger email evaluations. For very large batches, this can cause noticeable delays. Consider whether batch operations should trigger emails at all, or whether summary emails would be more appropriate.

Report Attachment Optimization - Generating report attachments can be time-consuming, especially for complex reports. Test report performance before deploying emails with report attachments in high-volume scenarios.

Attachment Size Management - Large email attachments (multi-megabyte PDFs, for example) take time to generate and transmit, and consume email server resources. Where possible, use reasonably-sized attachments or consider alternatives like links to documents rather than attaching full documents.

Large Attachment Handling

File Size Limits - Be aware of email server attachment size limits (often 10MB-25MB). Attachments exceeding these limits will cause email sending to fail.

Compression - For large document attachments, consider compressing files (ZIP format) before uploading as fixed file attachments.

Alternative Delivery - For very large documents, consider alternatives to direct attachment:

• Upload documents to a shared location (SharePoint, file server) and include links in email body

• Use cloud storage with shared access links

• Implement a document portal where recipients can download large files

Monitoring Performance Impact

Watch for signs that email automation is impacting Business Central performance:

• Noticeable delays when users perform actions that trigger emails

• User complaints about system slowness after email automation deployment

• Increased database CPU or I/O usage correlating with email triggers

• Email processing queues growing (if using queued email sending)

If performance impact is observed, review trigger and scenario configuration to identify optimization opportunities, or consult with a Business Central technical specialist to implement advanced optimization strategies.

6.6 Maintenance and Best Practices

Ongoing maintenance ensures email automation continues to meet business needs and operates reliably.

Regular Review Procedures

Quarterly Email Template Review - Every three months, review all active email templates:

• Are they still needed? Disable or delete obsolete templates.

• Are recipients still correct? Update distribution lists.

• Is content still accurate? Update email body text to reflect current processes.

• Are placeholders still valid? Verify field IDs haven't changed.

• Do attachments still work? Test report attachments to ensure reports haven't been modified in ways that break automation.

User Feedback Collection - Periodically solicit feedback from email recipients and Business Central users:

• Are emails useful?

• Do emails send at appropriate times?

• Is content clear and actionable?

• Are there missing notifications that would be valuable?

Log Review - Monthly, review Validation Logs for patterns:

• Are there frequent errors indicating configuration problems?

• Are there emails that fire very frequently, indicating possible misconfiguration?

• Are there emails that never fire, indicating possible obsolete configuration?

Documentation Standards

Maintain documentation for email automation:

Template Documentation - For each email template, document:

• Business purpose (why this email exists)

• Intended recipients (who should receive it)

• Trigger conditions (when it sends)

• Owner/contact (who to ask if questions arise)

• Change history (what modifications have been made and why)

Use the Description fields in email template configuration to store key documentation, and maintain separate detailed documentation in a knowledge base or shared document repository.

Architecture Documentation - Document the overall email automation architecture:

• How many email templates exist and their general categories

• Rule group structure and purpose

• Integration with other systems (if any)

• Custom modifications (if any)

This documentation helps new administrators understand the system and supports troubleshooting and planning.

Change Management

Treat email template changes as configuration changes subject to change control:

Testing Required - Always test email template changes in a non-production environment before deploying to production.

Deployment Windows - Deploy email template changes during planned maintenance windows or low-activity periods to minimize risk of disrupting business operations.

Rollback Plans - Before deploying changes, export current templates to XML as a backup. If changes have unexpected effects, you can quickly roll back by importing the previous configuration.

Communication - Notify affected users when email templates change, especially if recipients, timing, or content change in ways users will notice.

Version Control - Store exported XML template files in version control systems with commit messages documenting what changed and why. This provides an audit trail and history of template evolution.

6.7 Getting Help and Support

When you encounter issues beyond the scope of this manual's troubleshooting guidance, multiple resources are available for assistance.

Documentation Resources

This User Manual - You're reading the primary user documentation for the Advanced Email App. Refer back to relevant chapters for detailed information on features and configuration.

Rule Engine User Manual - Since the Advanced Email App is built on the QUALIA Rule Engine, the Rule Engine User Manual provides additional context on validation sets, formulas, triggers, and scenarios. Many concepts in the Advanced Email App directly correspond to Rule Engine concepts explained in that manual.

Rule Engine Technical Design Document - For developers or technical users needing deep technical details, the Rule Engine Technical Design Document explains the underlying architecture, database structures, and code implementation.

Advanced Email Technical Design Document - Technical specifications specific to the Advanced Email App, including database schema, object IDs, and integration details.

Business Central Community

Microsoft Dynamics Community - The online Microsoft Dynamics community includes forums, blogs, and user groups where Business Central users share knowledge. While the Advanced Email App is a third-party extension, general Business Central automation questions often receive helpful responses.

Partner Networks - If your organization works with a Microsoft Dynamics partner for Business Central implementation and support, that partner may have expertise with the Advanced Email App or be able to provide configuration assistance.

Technical Support

QUALIA Support - For issues specific to the Advanced Email App or Rule Engine, contact QUALIA technical support. Provide detailed information when requesting support:

• Description of the issue and expected vs. actual behavior

• Relevant email template codes and configuration screenshots

• Validation log entries showing the problem

• Steps to reproduce the issue

• Business Central version and Advanced Email App version

Business Central Support - For issues related to Business Central's underlying email infrastructure (SMTP configuration, email sending failures unrelated to the app), contact your Business Central support provider or Microsoft support.

Self-Help Strategies

Before requesting external support, exhaust self-help options:

1. Review This Manual - Search for relevant topics in this manual's table of contents

2. Check Validation Logs - Most issues leave traces in logs that point to the root cause

3. Simplify and Test - Create a minimal test email template with simple configuration to isolate whether the issue is with specific configuration or general functionality

4. Compare Working Examples - If you have other email templates that work correctly, compare their configuration to the problematic template to identify differences

5. Review Recent Changes - Consider what changed recently—did the problem start after a template modification, a Business Central upgrade, or a user change?

Systematic self-troubleshooting often resolves issues faster than external support and builds your expertise with the system.

Conclusion

The QUALIA Advanced Email App transforms Business Central's email automation capabilities, making sophisticated triggered email notifications accessible to business users without requiring developer involvement. By mastering the concepts and procedures in this manual—email templates, placeholders, triggers, scenarios, rule groups, and testing—you can implement powerful automation that improves communication, reduces manual work, and ensures timely, accurate information delivery.

Start with simple email templates to build confidence and understanding, then progressively add complexity as your needs evolve. Test thoroughly before deploying to production, monitor validation logs to understand system behavior, and maintain documentation to support long-term success.

With the Advanced Email App, your Business Central system becomes a proactive communication platform, automatically keeping customers, vendors, and internal stakeholders informed of the events that matter to them.

End of Advanced Email App User Manual v1.0

Document Version: 1.0
Date: 2024
QUALIA Advanced Email App - Powered by QUALIA Rule Engine v1.1.0.4