Error Message Actions

Error Message Actions (Action Type 1) are the most powerful validation tool in QUALIA Rule Engine because they have the ability to completely prevent invalid transactions from being saved to the database. When an Error Message action executes, Business Central displays the error message to the user and then rolls back the entire transaction, ensuring that invalid data never enters your system. This section explains when Error actions are appropriate, how to configure them correctly, and critical patterns you must understand to avoid common mistakes.

8.1 When to Use Error Message Actions

Error Message actions should be used when you need to enforce mandatory business rules that absolutely must not be violated. The blocking nature of Error actions makes them ideal for data validation, compliance enforcement, and preventing data integrity problems.

Appropriate Use Cases for Error Message Actions

Data Validation and Quality Control: Use Error actions to prevent invalid data values from being saved. This includes preventing negative quantities, invalid date ranges, missing required information, inconsistent field combinations, or data values that violate business rules or database constraints.

Compliance Enforcement: When business rules represent regulatory requirements, legal obligations, or audit controls that must be enforced without exception, Error actions ensure compliance by preventing non-compliant transactions from being completed.

Financial Controls: Use Error actions to enforce financial limits, approval requirements, authorization boundaries, and accounting rules that protect your organization from financial errors or fraud.

Data Integrity Protection: Error actions prevent transactions that would create referential integrity problems, orphaned records, or inconsistent relationships between tables.

Process Gate Requirements: When certain conditions must be met before a transaction can proceed (for example, customer credit checks, inventory availability verification, or prerequisite setup completion), Error actions serve as gates that prevent premature transactions.

When NOT to Use Error Message Actions

Advisory Information: If the information is merely helpful guidance rather than a mandatory rule, use Message actions (non-blocking) or Notification actions instead. Error actions should only be used when the transaction truly must be prevented.

User Discretion Scenarios: When users may have legitimate reasons to override a policy or proceed despite a warning condition, use Confirmation actions that present a Yes/No choice rather than Error actions that provide no option to proceed.

Performance-Intensive Validations: Error actions that require complex calculations or access to many linked tables can cause noticeable performance delays. If validation logic is extremely complex, consider whether the validation is truly necessary at the point of data entry or whether it could be performed asynchronously.

8.2 Configuring Error Message Actions Step by Step

Configuring an Error Message action follows a similar process to Message actions, but with critical differences in behavior and testing requirements.

Step 1: Create the Validation Rule with Condition

Before adding an Error action, you must have a Business Rule with a Condition that identifies when data is invalid:

1. Open your Business Rule Set for editing

2. Navigate to the Rules tab

3. Create or select the Business Rule that should validate data

4. Configure the validation condition that evaluates to TRUE when data is invalid

💡 CRITICAL: Error actions execute when the condition is TRUE. Therefore, your condition formula should be written to detect invalid data, not valid data. For example, to require positive quantities, the condition should be [37:15] is <=0 (detects invalid negative or zero), not [37:15] is >0 (detects valid positive).

Step 2: Add a New Action

From the Actions section:

1. Create a new action line in the Actions section

2. This action will be attached to the condition you configured in Step 1

Step 3: Set the Action Type to Error Message

Configure the action type:

1. Locate the Action Type field in the action line

2. Select Error Message from the dropdown (this is Action Type 1 in the enum)

3. The action is now configured to block transactions when it executes

Step 4: Configure the Error Message Details

Specify the error message text that users will see:

1. Locate the Action Code or Detail ID field in the action line

2. Enter a new ID or select an existing error message from the lookup

3. Open the Error Message Detail card by selecting the Action Code field

4. On the Error Message Detail card, locate the Error Text or Message field

5. Enter a clear, specific error message that explains what is wrong and how users can fix it

6. Include dynamic field values using placeholder syntax if appropriate

7. Save the Error Message Detail card

Step 5: Test Thoroughly Before Enabling

Error actions have the power to block essential business operations if configured incorrectly:

1. Test with data that should fail validation (error should appear, transaction should not save)

2. Test with data that should pass validation (no error, transaction should save successfully)

3. Test boundary conditions (values exactly at the threshold between valid and invalid)

4. Test that error messages are clear and provide actionable guidance

5. Verify that users can successfully correct errors and retry the transaction

⚠️ CRITICAL: Always test Error actions in a sandbox environment before enabling them in production. An incorrectly configured Error action can prevent users from performing essential business functions.

8.3 Required Field Validation Pattern (CRITICAL)

One of the most common business requirements is to enforce that certain fields must be populated before records can be saved. However, implementing required field validation in QUALIA Rule Engine requires understanding a critical technical detail about when data is available during Business Central's record lifecycle.

8.3.1 Why OnInsert Triggers Fail for Required Field Validation

Many users intuitively configure required field validation like this:

❌ INCORRECT CONFIGURATION:

• Trigger Type: Before Insert

• Condition: [18:2] is '' (Customer Name is blank)

• Action: Error Message "Customer Name is required"

Why This Does Not Work: During the Before Insert trigger, Business Central has not yet assigned default values, copied data from related tables, or executed the table's OnInsert trigger code. At this point in the record lifecycle, many fields are legitimately blank because Business Central has not finished initializing the record. If you check for blank required fields on Before Insert, your rule will fail even when users have entered all required information, because Business Central simply has not populated those fields yet.

What Happens: Users attempt to create a customer record, carefully filling in all required fields including Customer Name. When they try to save, your Error action executes and displays "Customer Name is required" even though the user entered a name. From the user's perspective, they did enter a name, but your rule claims they did not. This creates enormous frustration and appears to be a bug in the system.

8.3.2 The Status-Based Validation Approach (CORRECT PATTERN)

The correct approach to required field validation uses the Before Modify trigger combined with a status field that indicates when a record is fully initialized and ready for validation.

✅ CORRECT CONFIGURATION:

• Trigger Type: Before Modify (NOT Before Insert)

• Scenario: [18:102] is >'0' (Customer.Status = Open or higher, meaning record is active)

• Condition: [18:2] is '' (Customer Name is blank)

• Action: Error Message "Customer Name is required. Please enter a customer name before continuing."

Why This Works: By using Before Modify instead of Before Insert, you allow Business Central to complete the record initialization process. By adding a Scenario that checks the status field, you ensure the validation only executes for active records, not for records that are still being set up. When users modify an active customer record and try to clear the Customer Name field, your validation correctly prevents this invalid modification.

Common Status Fields by Table:

Alternative Approach: Conditional Required Fields

If a field should only be required under certain circumstances, combine status checking with condition-specific logic:

Example: Item Description is only required for inventory items, not for service items:

• Trigger Table: 27 (Item)

• Trigger Type: Before Modify

• Scenario: [27:11] is '0' (Item Type = Inventory)

• Condition: [27:3] is '' (Description is blank)

• Action: Error Message "Description is required for inventory items."

8.3.3 When Data Actually Exists in Business Central Lifecycle

Understanding the record lifecycle helps you choose the correct trigger type for validation:

During Before Insert Trigger:

• Field values user entered in UI are present

• Default values from table definition are NOT yet applied

• FlowFields and calculated fields are NOT yet populated

• Related table lookups have NOT yet occurred

• OnInsert trigger code has NOT yet executed

During Before Modify Trigger:

• All field values are present and fully populated

• Previous values can be compared to new values using {OldValue} placeholder syntax

• FlowFields and calculated fields are available

• Related records can be accessed via Linked Tables

Recommendation: Use Before Modify trigger for almost all validation rules except for specific scenarios where you must validate data at the moment of initial creation (and even then, understand that some fields may not be available).

8.4 Writing Effective Error Messages

The error messages you write have a direct impact on user productivity and satisfaction. Well-written error messages help users quickly understand what went wrong and how to fix it. Poorly written error messages frustrate users, increase support costs, and reduce confidence in the system.

Essential Elements of Effective Error Messages

1. State What is Wrong Clearly

Start the error message by explaining exactly what problem was detected:

❌ Vague: "Validation failed."
❌ Technical: "Condition 1 evaluated to TRUE."
✅ Clear: "The quantity you entered is negative or zero, which is not allowed."

2. Explain Why It Matters (Optional but Helpful)

For complex rules, briefly explain why the requirement exists:

✅ "Customer Name is required because all financial reports and invoices must identify the customer clearly."
✅ "Discount percentage cannot exceed 50% because higher discounts require VP approval."

3. Tell Users Exactly How to Fix It

Provide specific, actionable guidance:

❌ Non-actionable: "Please correct the error."
✅ Actionable: "Please enter a quantity greater than zero."
✅ Actionable: "Please obtain approval from your manager, then contact IT to temporarily disable this validation."

4. Use Professional, Non-Accusatory Language

Avoid language that sounds like you are blaming users:

❌ Accusatory: "You entered an invalid value."
❌ Condescending: "You should know that quantities cannot be negative."
✅ Professional: "The quantity value must be a positive number."

5. Include Relevant Context with Placeholders

When appropriate, include the actual value that was invalid:

✅ "The discount percentage you entered ([37:27]%) exceeds the maximum allowed discount of 25%."
✅ "Customer [18:2] has exceeded their credit limit of [18:20]. Current balance is [18:59]."

Error Message Patterns for Common Scenarios

Required Field Pattern:

"[Field Name]

Example: "Customer Name is required. Please enter a value before saving."

Value Range Pattern:

"[Field Name] must be between [MinValue] and [MaxValue]. You entered [CurrentValue]

Example: "Discount % must be between 0 and 25. You entered [37:27]%."

Comparison Pattern:

"[Field Name 1] must be greater than [Field Name 2]. Current values: [Value1] and [Value2]

Example: "Ship Date must be after Order Date. Current values: [36:71] and [36:20]."

Limit Exceeded Pattern:

"[Action] would exceed [Limit Type] of [Limit Value]. Please [Required Action]

Example: "This order would exceed the customer's credit limit of [18:20]. Please obtain credit approval before proceeding."

8.5 Error Actions with Multiple Conditions

When a Business Rule has multiple conditions, each with its own Error action, it is important to understand the execution sequence and what happens when errors occur.

Sequential Condition Evaluation

QUALIA Rule Engine evaluates conditions in the order they are defined (or by Priority if specified). When a condition with an Error action executes:

1. The error message displays to the user

2. The transaction immediately rolls back

3. No subsequent conditions are evaluated

4. No other actions execute

5. Control returns to Business Central with the transaction cancelled

Implication: Only the first error encountered will be displayed to users. If multiple validation failures exist, users will see them one at a time as they correct each issue and retry.

Example Scenario - Multiple Sales Line Validations:

Condition 1: [37:15] is <=0
  └─ Error: "Quantity must be greater than zero."
  
Condition 2: [37:22] is <=0
  └─ Error: "Unit Price must be greater than zero."
  
Condition 3: [37:27]

User Experience:

• User enters Quantity = -5, Unit Price = 0, Discount = 30%

• User tries to save

• Condition 1 executes first: Error displays "Quantity must be greater than zero."

• User corrects Quantity to 10, tries to save again

• Condition 2 executes: Error displays "Unit Price must be greater than zero."

• User corrects Unit Price to 100, tries to save again

• Condition 3 executes: Error displays "Discount percentage cannot exceed 25%."

• User corrects Discount to 20%, tries to save again

• All validations pass, record saves successfully

Design Consideration: This sequential error reporting is generally acceptable because it keeps error messages focused and specific. However, if you want to check multiple fields and report all errors at once, you would need to combine multiple checks into a single condition with a compound error message, or use a custom codeunit action to perform complex validation logic.

8.6 Comprehensive Examples of Error Message Actions

The following examples demonstrate common validation scenarios implemented with Error Message actions.

Example 1: Negative Quantity Validation (Tutorial Example)

Business Requirement: Prevent users from entering zero or negative quantities on sales lines.

Rule Configuration:

• Trigger Table: 37 (Sales Line)

• Trigger Type: Before Insert, Before Modify

• Trigger Field: [37:15] (Quantity)

• Condition: [37:15] is <=0

• Action: Error Message

• Error Text: "Quantity must be a positive number. You entered [37:15]. Please enter a quantity greater than zero."

Why This Works: The condition detects invalid quantities (zero or negative), the trigger types ensure validation happens both when creating new lines and modifying existing lines, and the trigger field optimization ensures the rule only executes when Quantity changes.

Example 2: Credit Limit Enforcement

Business Requirement: Prevent sales orders from being saved if they would cause the customer to exceed their credit limit.

Rule Configuration:

• Trigger Table: 36 (Sales Header)

• Trigger Type: Before Insert, Before Modify

• Linked Table: Customer (18) linked via Sell-to Customer No. (field 2)

• Scenario: [36:120] is '0' (Document Status = Open)

• Condition: {[36:61] + [18:59]} is >[18:20] (Order Amount + Current Balance > Credit Limit)

• Action: Error Message

• Error Text: "This order cannot be saved because it would exceed the customer's credit limit. Customer [18:2] has credit limit of [18:20] and current balance of [18:59]. This order adds [36:61] for total of {[36:61] + [18:59]}. Please obtain credit approval or reduce the order amount."

Why This Works: The linked table provides access to customer credit information, the scenario ensures we only check open orders (not posted documents), and the calculation determines whether the total exposure would exceed the limit. The detailed error message provides all information users need to understand the situation.

Example 3: Required Field Validation with Status Check

Business Requirement: Customer Phone No. must be populated before the customer record can be used for transactions.

Rule Configuration:

• Trigger Table: 18 (Customer)

• Trigger Type: Before Modify

• Trigger Field: [18:9] (Phone No.)

• Scenario: [18:39] is '' (Customer is not blocked, meaning active)

• Condition: [18:9] is '' (Phone No. is blank)

• Action: Error Message

• Error Text: "Phone No. is required for all active customers. Please enter a phone number before saving."

Why This Works: By using Before Modify instead of Before Insert, we avoid the initialization problem described in Section 8.3. The scenario ensures we only enforce this requirement for active customers, allowing setup records to exist temporarily without phone numbers.

Example 4: Date Range Validation

Business Requirement: On sales orders, the Shipment Date must be equal to or later than the Order Date.

Rule Configuration:

• Trigger Table: 36 (Sales Header)

• Trigger Type: Before Insert, Before Modify

• Scenario: [36:120] is '0' (Status = Open)

• Condition: [36:71] is <[36:20] (Shipment Date < Order Date)

• Action: Error Message

• Error Text: "Shipment Date ([36:71]) cannot be earlier than Order Date ([36:20]). Please enter a shipment date that is on or after the order date."

Why This Works: The condition directly compares the two date fields using placeholder syntax. The error message displays both dates so users can see the conflict clearly.

Example 5: Percentage Range Validation

Business Requirement: Discount percentages on sales lines cannot exceed 25%.

Rule Configuration:

• Trigger Table: 37 (Sales Line)

• Trigger Type: Before Insert, Before Modify

• Trigger Field: [37:27] (Line Discount %)

• Condition: [37:27] is >25

• Action: Error Message

• Error Text: "Discount percentage cannot exceed 25%. You entered [37:27]%. Discounts above 25% require manager approval. Please reduce the discount or contact your manager for approval override."

Why This Works: The condition detects when the discount exceeds the threshold, and the error message provides both the invalid value and clear guidance about the approval process.