Skip to content · Zum Inhalt

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:Validation Set: Container for trigger logic (Code: SO-HIGH-VALUE)

Scenarios: Inclusion filters that define triggering records

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

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:Access Business Rule Sets

Search: Business Rule Sets

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

Create New Validation Set

Click + New

Validation Set Card opens

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: =, &lt;&gt;, &lt;, &gt;, &lt;=, &gt;=

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: &gt;10000

Field comparison: &gt;[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 &gt;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: &gt;=[18:39]

✅ Correct Configuration:

Add Reference Table: 18 (Customer)

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

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

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:

Add FlowField to table for calculation

Use condition lines with formula

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

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

Navigate to Validations tab

Click + New

Enter:

Code: TRIGGER-CHECK

Description: Additional Trigger Conditions

Save

Step 2: Add Condition Lines

Select the validation (TRIGGER-CHECK)

Click Validation Lines action

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:

Create test records that SHOULD trigger

Verify workflow instance created

Check Validation Log for TRUE/FALSE results

Confirm all scenarios matched

Create test records that should NOT trigger

Verify no workflow instance created

Check Validation Log shows CheckConditions = TRUE (no match)

Confirm which scenario failed

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:

Use production copy sandbox

Test with actual user IDs

Verify date calculations work correctly

Check cross-table references resolve

Confirm multiple validation OR logic works

Phase 3: Performance TestingReading 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:

Check Validation Log for validation set evaluation

Verify CheckConditions result (should be FALSE for trigger)

Review each scenario MATCH/NO MATCH result

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:

Review Validation Log entries

Check if multiple validation sets linked

Verify scenario values are correct

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:

Check Validation Log Duration column

Count number of scenarios (complex evaluations slower)

Check for cross-table references in condition lines

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.