Table of Contents

Event Rules

Event Rules is a framework that enables administrators to configure automatic validation rules that trigger when data is created or modified in Business Central. With Event Rules, you can enforce data quality standards, ensure mandatory fields are completed, validate field values against criteria, and execute automated responses when validation fails.

Overview

Event Rules provide a flexible way to implement data validation without custom code development. You can configure rules that automatically check data quality when users create or modify records, ensuring business requirements are met before data is saved.

Key capabilities:

  • Field validation: Trigger validations when specific fields are modified
  • Criteria filtering: Control when validations apply based on field values or conditions
  • Multiple validation types: Check mandatory fields, validate against filters, verify text length, pattern matching, and more
  • Flexible responses: Block operations with errors, display warnings, send notifications, or execute automated functions
  • Scope control: Restrict rule access to specific users, profiles, or permission sets
  • Testing and logging: Test rules before activation and review validation history

When to Use Event Rules

Event Rules are ideal for scenarios where you need to enforce data quality standards:

  • Mandatory field enforcement: Ensure critical fields are completed before saving
  • Value validation: Verify field values match specific criteria or patterns
  • Data consistency: Check relationships between fields or related records
  • Business rule enforcement: Implement complex validation logic without code
  • User guidance: Display helpful messages or warnings based on data conditions
  • Automated responses: Execute functions automatically when validation fails
Tip

Event Rules complement existing Business Central validations. Use them for business-specific validation requirements beyond standard system validations.

Create an Event Rule

To create a new event rule:

  1. Search for and open the Event Rule List page.

  2. Click New to create a new event rule.

  3. Fill in the required fields:

    • Code: Enter a unique code to identify the rule
    • Description: Provide a clear description of what the rule validates
    • Trigger Type: Select Field Validation (currently the only supported type)
    • Table Caption: Choose the table where validation applies
    • Valid From: Set the date when the rule becomes active

  4. Optionally configure:

    • Validation Field Caption: Specify which field triggers the validation (leave blank to trigger on any field change)
    • Valid To: Set an end date for the rule
    • Max Execution Time (ms): Set a performance threshold (default: 100ms)
Important

Changes to event rules require a session restart to take effect. You'll see a notification with a refresh action when configuring rules.

Trigger Configuration

Event Rules currently support Field Validation triggers, which execute when:

  • A field value changes during record insert operations
  • A field value changes during record modify operations
  • Any field changes (if no validation field is specified)
  • A specific field changes (if validation field is specified)
Note

The Valid From and Valid To dates control when the rule is active. Rules are only evaluated if the current work date falls within this range.

Add Criteria

Criteria control when validation steps are executed. Without criteria, validations run on every trigger. Add criteria to limit when validation occurs:

  1. In the Criteria section of the event rule, click New.

  2. Configure the criterion:

    • Description: Describe what the criterion checks
    • Criterion Type: Choose from:
      • Field: Check a specific field value
      • Calculated Filter: Use dynamic filter expressions
      • Function Set: Execute a criteria function set
      • Related Record: Verify related record existence
    • Configure type-specific settings (field number, filter expressions, etc.)

  3. For multiple criteria, set the Operator:

    • And: All criteria must be true
    • Or: At least one criterion must be true
Tip

Use criteria to make rules context-sensitive. For example, only validate shipping addresses when the document type is "Shipment".

Configure Validation Sets

Validation Sets contain the actual validation steps that check data quality. Each event rule can have multiple validation sets:

  1. In the Validation Sets section, click New.

  2. Fill in:

    • Description: Describe what this validation set checks
    • Blocked: Optionally disable the validation set temporarily

  3. Add Criteria to the validation set if it should only run under specific conditions.

  4. Add Validation Steps (see next section).

Note

Validation sets execute sequentially. If one set fails, remaining sets still execute unless an error action blocks the operation.

Add Validation Steps

Validation Steps define the actual checks performed on data. To add validation steps:

  1. In a validation set, click into the Validation Steps section.
  2. Click New and configure:
    • Description: Describe what this step validates
    • Field Caption: Select the field to validate
    • Validation Type: Choose the validation method (see types below)
    • Action Type: Specify what happens when validation fails
    • Message Template: Define the error/warning message

Validation Types

Validation Type Purpose Configuration
Mandatory Field must have a value Select the field to check
Filter Value must match filter criteria Specify field and filter expression
Length Text length must meet requirements Set field, operator (=, <>, >, <, >=, <=), and limit value
Regex Value must match pattern Select field and regular expression code
Related Field Compare with field in related table Set related table, field, and expected value filter
Related Record Count Verify number of related records Configure related table, operator, and limit value
Calculated Filter Validate using dynamic filter Select calculated filter code

Action Types

When validation fails, you can configure different responses:

Action Type Behavior Use Case
Error Blocks the operation and displays error message Critical validations that must pass
Message Shows a dialog message but allows operation Important warnings users should acknowledge
Notification Displays non-blocking notification Informational messages or reminders
Function Executes a function set macro Automated corrections or complex responses

Message Templates

Message templates support dynamic tokens that are replaced with actual values at runtime:

  • {RuleName}: The event rule code
  • {TableCaption}: Name of the table being validated
  • {FieldCaption}: Name of the field being checked
  • {CheckFieldCaption}: Name of the field in validation step
  • {Value}: The actual field value
  • {ExpectedValue}: The expected value or filter
  • {ActualCount}: Count of related records (for Related Record Count)
  • {RelatedTable}: Name of the related table

Example message template:

Field {CheckFieldCaption} of {TableCaption} must match filter {ExpectedValue}, but value is {Value}.
Tip

Click the Show Message Template Help action on a validation step to see available tokens and examples.

Scope Configuration

Scope settings restrict which users can access the validation. Use this to apply different validation rules for different user groups:

  1. In the Scope section, click New.

  2. Select the scope type:

    • Profile: Specific Business Central profiles
    • Permission Set: Users with specific permission sets
    • User: Individual users
    • User Group: User group members

  3. Select the specific profile, permission set, user, or user group.

Note

If no scope is configured, the validation applies to all users. With scopes defined, validation applies to users matching ANY of the defined scopes.

Test Event Rules

Before activating an event rule, test it to ensure it works correctly:

  1. Open the event rule you want to test.
  2. Click Test Rule in the actions.
  3. Select a record from the target table to test against.
  4. Review the test results showing:
    • Whether each validation step passed or failed
    • Criteria evaluation results
    • Scope check results
    • Performance metrics
Important

Testing runs validations in test mode without actually modifying data or executing actions. Use this to verify rule configuration before activation.

Copy Event Rules

To create a new rule based on an existing one:

  1. Open the event rule you want to copy.
  2. Click Copy Rule in the actions.
  3. Enter a code for the new rule.
  4. The new rule is created with all criteria, validation sets, and steps copied.

This is useful for creating variations of similar validation rules.

View Log Entries

Event Rules log validation executions and failures for troubleshooting:

  1. Open an event rule.
  2. Click Log Entries to view the log.
  3. Review entries showing:
    • Date/Time: When the validation executed
    • User: Who triggered the validation
    • Severity: Information, Warning, or Error
    • Message: Validation result details
    • Record ID: The record that was validated
    • Execution Time: Performance metrics
Tip

Use log entries to identify frequently failing validations or performance issues with rules.

Performance Considerations

Event Rules execute during record insert and modify operations, so performance is important:

  • Set Max Execution Time: Configure the Max Execution Time (ms) field to log warnings when rules take too long
  • Use specific field triggers: Specify a validation field instead of triggering on any field change
  • Optimize criteria: Use criteria to limit when validations run
  • Disable unused rules: Block rules that are no longer needed
  • Monitor logs: Review log entries for performance warnings
Warning

Complex validation steps with many related record checks can impact system performance. Test thoroughly and monitor execution times.

Advanced Validation Features

Regular Expressions

For text pattern validation, use the Regex validation type with predefined regular expression patterns. This enables validation of:

  • Order numbers and reference formats
  • Postal codes and phone numbers
  • Serial numbers and license plates
  • Email addresses and custom patterns

See Regular Expressions for detailed pattern syntax and examples.

Calculated Filters

Calculated Filters enable dynamic filter expressions that automatically insert runtime values such as:

  • Current user ID (for user-specific validation)
  • Today's date (for date range checks)
  • Work date (for accounting period validation)
  • Static text values

See Calculated Filters for comprehensive examples and configuration guidance.

Best Practices

When configuring Event Rules:

  1. Start simple: Begin with basic mandatory field validations before complex rules
  2. Clear messages: Write message templates that clearly explain what's wrong and how to fix it
  3. Test thoroughly: Use the test function before activating rules in production
  4. Document rules: Use the Extended Description field to document business logic
  5. Performance monitoring: Set appropriate max execution times and monitor logs
  6. Scope appropriately: Apply rules only to users who need them
  7. Date ranges: Use Valid From/To dates for time-bound validations
  8. Progressive enforcement: Start with notifications, move to errors once users are trained

Examples

Example 1: Mandatory Field Validation

Scenario: Ensure the shipping address is filled when document type is "Shipment"

  1. Create event rule for WMS Document Header table
  2. Add criterion: Document Type = "Shipment"
  3. Add validation step:
    • Validation Type: Mandatory
    • Field: Shipping Address Code
    • Action Type: Error
    • Message: "Shipping Address is required for shipment documents"

Example 2: Filter Validation

Scenario: Customer No. must start with "CUST-"

  1. Create event rule for Customer table
  2. Add validation step:
    • Validation Type: Filter
    • Field: No.
    • Value Filter: CUST-*
    • Action Type: Error
    • Message: "Customer numbers must start with CUST-"

Example 3: Length Validation

Scenario: Order reference must be at least 10 characters

  1. Create event rule for WMS Document Header
  2. Add validation step:
    • Validation Type: Length
    • Field: External Document No.
    • Operator: >= (Greater or Equal)
    • Limit Value: 10
    • Action Type: Warning
    • Message: "Order reference should be at least 10 characters for tracking purposes"

Scenario: Ensure at least one document line exists before status change

  1. Create event rule for WMS Document Header
  2. Trigger on Status Code field
  3. Add validation step:
    • Validation Type: Related Record Count
    • Related Table: WMS Document Line
    • Operator: >= (Greater or Equal)
    • Limit Value: 1
    • Action Type: Error
    • Message: "Document must have at least one line before changing status"
Edit this page