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 recommended

Impact 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