Chapter 14: Troubleshooting and Maintenance
Chapter Objectives:
Diagnose common workflow issues
Use diagnostic tools effectively
Optimize workflow performance
Perform regular maintenance tasks
Handle upgrades and migrations
Access support resources
Prerequisites:
Experience operating workflows
Familiarity with workflow configuration
Basic understanding of Rule Engine
Access to troubleshooting tools
14.1. Common Issues and Solutions
Issue 1: Workflow Not Triggering
Symptoms:
Record modified, but no workflow entry created
Expected task not appearing
Workflow seems inactive
Common Causes & Solutions:
Cause 1: Workflow Disabled:
Cause 2: Trigger Conditions Not Met:
Cause 3: Validation Set Disabled:
Cause 4: Table/Field Mismatch:
Cause 5: Subscriber Not Active:
Issue 2: Task Not Releasing
Symptoms:
Task created with Status = Open
Task never becomes Released
User can't process task
Common Causes & Solutions:
Cause 1: Release Conditions Not Met:
Cause 2: Prerequisite Task Not Completed:
Cause 3: Status Rule Disabled:
Cause 4: Validation Formula Error:
Issue 3: Placeholder Not Resolving
Symptoms:
Placeholder shows as literal text: "[18:102]"
Field empty when placeholder expected
Error message about placeholder
Common Causes & Solutions:
Cause 1: Syntax Error:
Check: Placeholder format
Incorrect:
18:102 (missing brackets)
[18-102] (wrong separator)
[18:102 (missing closing bracket)
Correct:
[18:102]
Solution:
Correct syntax to [TableNo:FieldNo]Cause 2: Field Not Available:
Cause 3: Table/Field Doesn't Exist:
Check: Valid table and field numbers
Example:
[18:999999] Field 999999 doesn't exist in Customer
[999999:1]
Cause 4: Type Mismatch:
Check: Field type matches placeholder location
Example:
Contact No.: [18:5700]
Cause 5: Record Context Missing:
Check: Placeholder table matches workflow table
Example:
Workflow Table: Customer (18)
Placeholder: [36:3]
Issue 4: Permission Errors
Symptoms:
"You do not have permission" error
User can't see workflow entries
Can't process tasks
Solutions:
Error: Can't Read Workflow Entries:
Error: Can't Modify Task Status:
Error: Can't Execute Process Action:
Solution:
Grant user Execute permission:
Object Type: Codeunit
Object ID: [Process action codeunit]
Error: Can't See Source Record:
14.2. Diagnostic Tools
Workflow Entries Analysis
Purpose: Investigate workflow instance state and history.
Access:
Key Fields for Diagnosis:
Common Diagnostic Queries:
Query 1: Why isn't my task Released?
Filter:
Workflow No. = [your workflow]
Workflow Step Code = [your task]
Status = Open
Check:
Released at = empty Check Line 9999 conditions
Query 2: Which tasks are overdue?
Filter:
Status = Released
Due Date < TODAY
Result: All overdue tasks
Query 3: Who completed this workflow?
Filter:
Workflow No. = [your workflow]
Source Primary Key Value = [record ID]
Validation Log
Purpose: See Rule Engine formula evaluation results and errors.
Access:
Search: QUA Validation Log
Filter:
Validation Set ID: [Workflow No.]
Log Fields:
Using Log for Troubleshooting:
Interpreting Common Errors:
Rule Engine Debugging
Purpose: Test formulas and scenarios independently.
Access:
Testing Scenarios:
Using Formula Designer:
Status Rule Testing
Procedure:
14.3. Performance Optimization
Workflow Entry Growth Management
Issue: Entries table grows over time, impacting performance.
Monitoring:
Query: Count of Workflow Entries
SELECT COUNT(*) FROM "QUA WorkFlow Entries"
Thresholds (guidelines):
< 10,000 entries: Good
10,000-50,000: Monitor
50,000-100,000: Plan archival
> 100,000: Archival recommendedImpact of Large Entry Table:
Slower workflow entry queries
Slower assignment lookups
Slower validation rule execution
Increased backup/restore time
Mitigation:
Efficient Validation Formulas
Optimization Strategies:
1. Minimize Scenarios:
2. Avoid Broad Filters:
3. Limit Linked Tables:
4. Index-Friendly Conditions:
Workflow Configuration Optimization
Task Count Optimization:
Trigger Frequency:
14.4. Data Maintenance
Archiving Completed Workflows
Purpose: Remove old completed workflow entries to improve performance.
Recommended Schedule:
Manual Archival Process:
Automated Archival (If Available):
** IMPORTANT**: Always backup database before large deletions.
Cleaning Orphaned Entries
Issue: Entries exist for deleted source records.
Identification:
Cleanup:
Backup Best Practices
What to Backup:
Backup Schedule:
Export Process:
14.5. Upgrades and Migration
Version Upgrades
Pre-Upgrade Checklist:
Upgrade Process:
Post-Upgrade Validation:
Migrating Workflows Between Environments
Scenario: Move workflows from DEV TEST PROD.
Migration Methods:
Method 1: RapidStart Configuration Package:
Method 2: Manual Re-Creation:
Migration Checklist:
14.6. Getting Help and Support
Documentation Resources
This Manual:
Rule Engine User Manual:
Business Central Documentation:
Support Channels
Internal Support:
Vendor Support:
QUALIA Technik GmbH:
- Support portal: [Contact vendor for details]
- Email support: [Contact vendor for details]
- Phone support: [Contact vendor for details]
Reporting Issues
Effective Issue Reports Include:
Community Resources
Knowledge Sharing:
Best Practices:
Chapter 14 Complete: Troubleshooting and Maintenance
