Chapter 05: Configuring Workflow Triggers (Initiated By Rules)

Triggers determine WHEN workflows execute. This chapter provides comprehensive coverage of trigger configuration using the Rule Engine validation framework, including scenarios, conditions, and advanced patterns for precise workflow activation.

What You'll Learn:

• Deep understanding of Rule Engine validation architecture

• How to create and configure validation sets for triggers

• Scenario configuration (inclusion filters)

• Condition configuration within validations

• Multiple trigger patterns (OR logic)

• Testing and debugging trigger logic

• Performance optimization

• Common trigger mistakes and solutions

Time Required: 40-50 minutes reading

Prerequisites:

• ✅ Understanding of Chapter 3 (Core Concepts)

• ✅ Completed Chapter 4 tutorial (recommended)

• ✅ Access to Rule Engine configuration pages

• ✅ QUA Business Rules UnLicensed permission set

5.1. Trigger Architecture Overview

Understanding how triggers work requires understanding the Rule Engine validation framework that powers them.

🏗️ The Validation Framework

Key Components:

1. Validation Set: Container for trigger logic (Code: SO-HIGH-VALUE)

2. Scenarios: Inclusion filters that define triggering records

3. Validations: Individual rules within the set (not used for workflow triggers)

4. Workflow Link: Initiated By tab links workflow to validation set

🔍 CODE-VERIFIED: CheckConditions Logic

This is critical to understand for proper trigger configuration.

CheckConditions Function Behavior:

// Simplified logic from Rule Engine
procedure CheckConditions(): Boolean
begin
    // Evaluate all scenarios
    // If ALL scenarios match the current record:
    //   Return FALSE (counterintuitive!)
    // If ANY scenario doesn't match:
    //   Return TRUE
end;

// In ApplyRules procedure:
if CheckConditions() then
    ToBeValidated := false  // Don't trigger
else
    ToBeValidated := true;  // DO trigger

Why This Matters:

• Scenarios define what SHOULD trigger (inclusion logic)

• CheckConditions returns FALSE when record matches (means "conditions met")

• This inverted logic trips up many administrators

• Understanding this prevents configuration errors

🔗 For complete CheckConditions implementation details, see Rule Engine Technical Design Document Section 2.4.

📊 Scenarios as Inclusion Filters

Scenario Logic:

Each scenario is a filter that must match:

Rule 1: High Value Order Trigger
  Scenario 1: [36:0] is <>''
    // [36:0] = Sales Header.All Fields - Ensures we're processing Sales Header table
    
  Scenario 2: [36:179] is >10000
    // [36:179]

Example Evaluation:

Record: Sales Header with Amount = 15000

Rule 1: High Value Order Trigger
  Scenario 1: [36:0] is <>''
    // Evaluation: Sales Header record exists → Match ✓
    
  Scenario 2: [36:179] is >10000
    // [36:179]

Record: Sales Header with Amount = 5000

Rule 1: High Value Order Trigger
  Scenario 1: [36:0] is <>''
    // Evaluation: Sales Header record exists → Match ✓
    
  Scenario 2: [36:179] is >10000
    // [36:179]

Inclusion Filter Principle:

Scenarios define the "positive case" - what records SHOULD be processed, not what shouldn't.

5.2. Creating Validation Sets for Triggers

Validation sets are the foundation of workflow triggers. Let's explore creation patterns.

📋 Basic Validation Set Creation

Step-by-Step:

1. Access Business Rule Sets

   • Search: Business Rule Sets

   • Or: Navigate from Workflow Setup → Initiated By → Rule lookup → New

2. Create New Validation Set

   • Click + New

   • Validation Set Card opens

3. Configure General Fields

"Code" Field:

• Enter: Unique identifier

• Naming convention: Descriptive + purpose

• Examples:

  • SO-HIGH-VALUE (sales orders > threshold)

  • CUST-NEW (new customers)

  • ITEM-PRICE-CHANGE (item price modifications)

  • PO-FOREIGN (purchase orders with foreign vendors)

"Description" Field:

• Enter: Business-friendly explanation

• Be specific about conditions

• Examples:

  • "Sales Orders Over $10,000"

  • "Newly Created Customers"

  • "Item Price Increases > 10%"

  • "Purchase Orders to Non-Domestic Vendors"

"Table No." Field:

• Select: The BC table that triggers workflow

• Must match workflow Table No.

• Critical: Cannot be changed after creation

• Common tables:

  • 18 (Customer)

  • 23 (Vendor)

  • 27 (Item)

  • 36 (Sales Header)

  • 38 (Purchase Header)

  • 5050 (Contact)

"Trigger Enabled" Checkbox:

• Check: ✓ (must be enabled for trigger to fire)

• This is separate from workflow Enabled checkbox

• Both must be enabled for trigger to work

"Trigger Type" Field:

• Select event types that trigger validation:

  • Insert: New records

  • Modify: Changed records

  • Delete: Deleted records (rare for workflows)

  • Rename: Primary key changes (very rare)

• Multiple can be selected (common: Insert + Modify)

"Global Processing" Checkbox:

• Usually: Unchecked

• Advanced feature for cross-company validation

• Leave unchecked for standard workflows

✅ Example: High-Value Sales Order Trigger

Complete configuration:

5.3. Configuring Scenarios (Inclusion Filters)

Scenarios define which records trigger the workflow. Understanding scenario configuration is essential for precise triggers.

📋 Scenario Field Reference

Each scenario has these fields:

"Table ID" Field:

• The table being filtered

• Usually same as Validation Set Table No.

• For related tables, can be different

"Field No." Field:

• The field being evaluated

• Leave blank for table-only scenarios

• Use Table Information page to find field numbers

"Filter String" Field:

• Comparison expression using Business Central filter syntax

• Supports comparison operators: =, <>, <, >, <=, >=

• Supports range filters: 10..100 (values between 10 and 100)

• Supports multiple values: A|B|C (A or B or C)

• Supports wildcards: *, ?, @

• Placeholders ARE supported: Can use [TableID:FieldID] to compare fields

• Examples:

  • Fixed value: >10000

  • Field comparison: >[18:39] (greater than Customer Credit Limit)

  • Range: 1000..5000

  • Multiple: Open|Released

  • Wildcard: US* (starts with US)

⚠️ CRITICAL: The scenario configuration uses Business Central filter syntax in a single "Filter String" field, NOT separate "Operator" and "Value" fields. When the UI displays "Sales Header.Amount is >10000", you entered >10000 in Filter String. The word "is" is added by the UI for readability.

"Enabled" Checkbox:

• Check: ✓ to activate scenario

• Uncheck: ☐ to temporarily disable without deleting

📊 Common Scenario Patterns

Pattern 1: Amount Threshold

Pattern 2: Status-Based Trigger

Pattern 3: Field Population Check

Pattern 4: Date Range Filter

Pattern 5: String Match

Pattern 6: Boolean Flag

Pattern 7: New Record Detection

Purpose: Trigger only for new records

Scenario Configuration:
  Table ID: 18 (Customer)
  Field No.: 50000 (Created DateTime) [custom field]

Pattern 8: Multiple Value Match (OR Logic)

⚠️ Scenario Limitations and Workarounds

Limitation 1: Cross-Table Comparisons Require Linked Tables

❌ Incomplete: "Customer Credit Limit >= Sales Order Amount" (without linked table setup)

• Scenarios CAN evaluate related tables

• But you MUST configure Linked Tables (Reference Tables) first

• Then use placeholders in Filter String: >=[18:39]

✅ Correct Configuration:

1. Add Reference Table: 18 (Customer)

2. Add Reference Filter: Customer.No. = Sales Header.Sell-to Customer No.

3. Add Scenario: Field 36:179, Filter String: <[18:39] (order amount < credit limit)

4. Placeholder [18:39] resolves to linked customer's credit limit

🔗 See Rule Engine User Manual Section 6: Using Linked Tables for configuration details

Limitation 2: No Calculated Fields

❌ Cannot do: "Amount * 1.1 > 50000"

• Scenarios only evaluate stored field values

• No mathematical expressions

• No function calls

✅ Workaround Options:

1. Add FlowField to table for calculation

2. Use condition lines with formula

3. Perform calculation in custom field via code

Limitation 3: No Dynamic Values

❌ Cannot do: "Order Date > TODAY"

• Scenario values are fixed at configuration time

• Cannot use system variables (TODAY, USERID, etc.)

• Value field is literal text/number

✅ Workaround:

• Use condition lines (support dynamic values)

• Update scenario values periodically (not recommended)

• Use date range that encompasses future dates

5.4. Using Condition Lines for Advanced Triggers

When scenarios are insufficient, condition lines provide advanced logic including cross-table references, calculations, and dynamic values.

🔧 When to Use Condition Lines

Use condition lines for:

• Cross-table field comparisons

• Mathematical calculations

• Dynamic system values (TODAY, USERID, COMPANYNAME)

• Complex boolean logic

• Field-to-field comparisons within same record

📋 NOTE: Condition lines are configured within Validations (child of Validation Set), not directly in scenarios. This requires understanding the Validation → Validation Line hierarchy.

📋 Condition Line Architecture

📋 Creating Validations with Condition Lines

Step 1: Add Validation to Validation Set

1. Open Validation Set (e.g., SO-HIGH-VALUE)

2. Navigate to Validations tab

3. Click + New

4. Enter:

   • Code: TRIGGER-CHECK

   • Description: Additional Trigger Conditions

5. Save

Step 2: Add Condition Lines

1. Select the validation (TRIGGER-CHECK)

2. Click Validation Lines action

3. Validation Lines page opens

Step 3: Configure Condition Line

Each condition line has:

"Line No." Field:

• Sequential number (10000, 20000, 30000, etc.)

• Determines evaluation order

"Field No." Field:

• The field being evaluated

• Source field for comparison

"Formula" Field:

• The expression to evaluate

• Supports:

  • Placeholders: [TableNo:FieldNo]

  • Operators: =, <>, <, >, <=, >=, +, -, *, /, AND, OR

  • System values: TODAY, W, CT, USERID

  • Constants: Numbers, strings, dates

"Action Type" Field:

• For trigger purposes: Usually empty

• For action execution: Set specific action

✅ Example: Credit Check Trigger

Requirement: Trigger workflow only if customer credit limit >= order amount

Validation Set: SO-CREDIT-CHECK

Reference Tables Tab:
  Reference Table 1:
    Reference Table No.: 18 (Customer)
    Identifier: CUST
  Reference Filters:
    Reference Field No.: 1 (Customer.No.)
    Filter Type: Field
    Filter Value: 2 (Sales Header.Sell-to Customer No.)

Scenarios Tab:
  Scenario 1:
    Table ID: 36 (Sales Header)
    Field No.: 179 (Amount Including VAT)
    Filter String: <[18:39]
    Purpose: Order amount must be less than customer credit limit
    Note: [18:39] resolves to linked customer's credit limit

UI Display: "Sales Header.Amount Including VAT is <Customer.Credit Limit"
      Explanation: Order amount <= Customer credit limit
      
Note: [18:39]

⚠️ IMPORTANT: The formula [18:39] works because Sales Header has table relation to Customer. The Rule Engine follows the relation to retrieve Customer Credit Limit.

✅ Example: Date-Based Trigger

Requirement: Trigger workflow only for orders dated within last 7 days

📋 NOTE: TODAY is a system keyword that evaluates to current date at runtime. This creates dynamic filtering impossible with scenarios alone.

✅ Example: User-Based Trigger

Requirement: Trigger workflow only for orders created by specific salesperson

5.5. Multiple Triggers (OR Logic)

Workflows can have multiple trigger conditions where ANY matching condition triggers the workflow.

📋 Implementing OR Logic

Scenario: Trigger approval workflow if:

• Amount > $50,000 OR

• Customer is new (created < 30 days ago) OR

• Ship-to country is not domestic

Solution: Create three separate validation sets, link all to workflow

Validation Set 1: SO-HIGH-VALUE

Validation Set 2: SO-NEW-CUSTOMER

Code: SO-NEW-CUSTOMER  
Description: Orders for Recently Created Customers

Reference Tables:
  Reference Table 1:
    Reference Table No.: 18 (Customer)
    Identifier: CUST
  Reference Filters:
    Reference Field No.: 1 (Customer.No.)
    Filter Type: Field  
    Filter Value: 2 (Sales Header.Sell-to Customer No.)

Scenarios:
  Table ID: 36 (Sales Header)
  Field No.: 2 (Sell-to Customer No.)
  Filter String: <>''
  Purpose: Ensure customer field populated

⚠️ Note: Cannot use TODAY in scenarios (system values not supported in Filter String)
For date-based triggering, use:
  - Fixed date: >=01/01/2025
  - Linked field: >=[18:50]

Validation Set 3: SO-INTERNATIONAL

Link to Workflow:

5.6. Testing and Debugging Triggers

Proper testing ensures triggers fire correctly and don't fire incorrectly.

📋 Testing Strategy

Phase 1: Scenario Testing

Test each scenario independently:

1. Create test records that SHOULD trigger

   • Verify workflow instance created

   • Check Validation Log for TRUE/FALSE results

   • Confirm all scenarios matched

2. Create test records that should NOT trigger

   • Verify no workflow instance created

   • Check Validation Log shows CheckConditions = TRUE (no match)

   • Confirm which scenario failed

3. Test boundary conditions

   • Exactly at threshold (Amount = 10000)

   • Just below threshold (Amount = 9999)

   • Just above threshold (Amount = 10001)

   • Empty/null field values

   • Zero values

Phase 2: Integration Testing

Test with realistic data:

1. Use production copy sandbox

2. Test with actual user IDs

3. Verify date calculations work correctly

4. Check cross-table references resolve

5. Confirm multiple validation OR logic works

Phase 3: Performance Testing Reading Log Entries:

Entry Example:

Entry No.: 12345
Validation Set Code: SO-HIGH-VALUE
Table No.: 36
Source Record: Sales Header: SO-12345

Rule 1: High Value Order Check
  Scenario 1: [36:0] is <>''
    // [36:0] = Sales Header.All Fields
    // Result: MATCH (record exists)
    
  Scenario 2: [36:179] is >10000
    // [36:179]

Common Log Patterns:

Success Pattern:

Rule 1: Example Rule
  Scenario 1: [36:120] is Released
    // Result: MATCH (filter matches)
    
  Scenario 2: [36:179]

Failure Pattern:

Rule 1: Example Rule
  Scenario 1: [36:120] is Released
    // Result: MATCH (filter matches)
    
  Scenario 2: [36:179]

Common Log Patterns:

Success Pattern:

Failure Pattern:

🐛 Troubleshooting Common Issues

Issue: Workflow Not Triggering

Diagnosis steps:

1. Check Validation Log for validation set evaluation

2. Verify CheckConditions result (should be FALSE for trigger)

3. Review each scenario MATCH/NO MATCH result

4. Identify which scenario filter didn't match

Common causes:

• Validation Set "Trigger Enabled" unchecked

• Workflow "Enabled" unchecked

• Scenario value incorrect (typo, case sensitive)

• Field number wrong

• Operator backwards (used < instead of >)

• Value type mismatch (text vs number)

Issue: Workflow Triggering Incorrectly

Diagnosis steps:

1. Review Validation Log entries

2. Check if multiple validation sets linked

3. Verify scenario values are correct

4. Test with minimal scenarios (eliminate one by one)

Common causes:

• Multiple validation sets creating unwanted OR logic

• Scenario operator wrong (<> instead of =)

• Missing required scenario

• Table relation resolving to unexpected value

Issue: Performance Problems

Symptoms:

• Slow record creation/modification

• Timeout errors

• Validation Log shows long duration (>100ms)

Diagnosis:

1. Check Validation Log Duration column

2. Count number of scenarios (complex evaluations slower)

3. Check for cross-table references in condition lines

4. Review table indexes

Solutions:

• Reduce number of scenarios

• Add indexes to filtered fields

• Simplify condition line formulas

• Consider batch processing instead of real-time

5.7. Trigger Best Practices

✅ Configuration Best Practices

1. Use Descriptive Naming

2. Document Trigger Purpose

3. Keep Scenarios Simple

4. Test Before Enabling

5. Use OR Logic for Alternatives

✅ Performance Best Practices

1. Filter Early

2. Index Filtered Fields

3. Avoid Expensive Operations

4. Use Appropriate Trigger Types

✅ Maintenance Best Practices

1. Document Trigger Logic

2. Version Control

3. Regular Review

4. Monitor Performance

This concludes Chapter 5: Configuring Workflow Triggers. You now understand how to create precise, performant trigger conditions using validation sets, scenarios, and condition lines.

Continue to Chapter 6 for comprehensive task design and configuration patterns.