Table of Contents

Regular Expressions

Regular Expressions (regex) provide powerful pattern matching capabilities for validating text fields in Business Central. In 3PL Dynamics, you can define reusable regular expression patterns and apply them in Event Rules, serial number handling, address validation, and other features requiring text pattern validation.

Overview

Regular Expressions enable you to validate that text fields match specific patterns without writing code. Common use cases include:

  • Format validation: Ensure order numbers, customer codes, or reference numbers follow a specific format
  • Pattern matching: Validate phone numbers, postal codes, email addresses, or license plates
  • Character restrictions: Enforce that fields contain only allowed characters
  • Serial number validation: Verify serial numbers match expected patterns
  • Data quality: Ensure consistent data entry across the system
Tip

Regular expressions are defined once and can be reused across multiple validation rules, making them a powerful tool for maintaining data quality standards.

Create a Regular Expression

To create a new regular expression pattern:

  1. Search for and open the Regular Expression List page.

  2. Click New to create a new regular expression.

  3. Fill in the fields:

    • Code: Enter a unique code (up to 10 characters) to identify this pattern
    • Description: Provide a clear description of what the pattern validates
    • Regular Expression: Enter the regex pattern (up to 250 characters)

  4. Click OK to save the regular expression.

Note

3PL Dynamics uses .NET regular expression syntax. The regex engine provides powerful pattern matching with support for character classes, quantifiers, anchors, and more.

Regular Expression Syntax

Regular expressions use special characters to define patterns. Here are the most commonly used elements:

Basic Patterns

Pattern Description Example
. Any single character a.c matches "abc", "a1c", "a-c"
\d Any digit (0-9) \d\d matches "12", "99"
\w Any word character (letter, digit, underscore) \w+ matches "Order123"
\s Any whitespace character \w+\s\w+ matches "Order 123"
[abc] Any character in brackets [ABC]-\d+ matches "A-123"
[^abc] Any character NOT in brackets [^0-9] matches any non-digit
[a-z] Any character in range [A-Z][0-9] matches "A1", "Z9"

Quantifiers

Pattern Description Example
* Zero or more times \d* matches "", "1", "123"
+ One or more times \d+ matches "1", "123" (not "")
? Zero or one time \d? matches "", "1"
{n} Exactly n times \d{4} matches "2024"
{n,} At least n times \d{3,} matches "123", "12345"
{n,m} Between n and m times \d{2,4} matches "12", "123", "1234"

Anchors

Pattern Description Example
^ Start of string ^ABC matches "ABC123" but not "123ABC"
$ End of string \d\d$ matches "Order12" but not "12Order"
\b Word boundary \bcat\b matches "the cat" but not "category"

Special Characters

To match special characters literally, escape them with a backslash:

Character Escaped Example
. \. \d+\. matches "123."
* \* \* matches "*"
+ \+ \+ matches "+"
? \? \? matches "?"
( ) \( \) \(note\) matches "(note)"
[ ] \[ \] \[1\] matches "[1]"
\ \\ \\ matches ""

Common Pattern Examples

Order Number Formats

Pattern: Customer prefix with 6 digits

^CUST-\d{6}$

Matches: "CUST-123456", "CUST-000001" Does not match: "CUST-12345", "CUSTOMER-123456"

Pattern: Any letter followed by dash and 4-6 digits

^[A-Z]-\d{4,6}$

Matches: "A-1234", "Z-123456" Does not match: "AB-1234", "A-123"

Postal Codes

Pattern: Dutch postal code (1234 AB)

^\d{4}\s?[A-Z]{2}$

Matches: "1234 AB", "1234AB" Does not match: "12345 AB", "1234 A"

Pattern: US ZIP code (12345 or 12345-6789)

^\d{5}(-\d{4})?$

Matches: "12345", "12345-6789" Does not match: "1234", "12345-67"

Phone Numbers

Pattern: International format with country code

^\+\d{1,3}\s?\d{1,14}$

Matches: "+31 612345678", "+1 5551234567" Does not match: "0612345678", "+31-612345678"

Pattern: Dutch mobile number

^(06|\+316)\d{8}$

Matches: "0612345678", "+31612345678" Does not match: "06-12345678", "0712345678"

Email Addresses

Pattern: Basic email validation

^[\w\.-]+@[\w\.-]+\.\w{2,}$

Matches: "user@example.com", "first.last@company.co.uk" Does not match: "user@", "@example.com", "user@example"

License Plates

Pattern: Dutch license plate (AB-12-CD format)

^[A-Z]{2}-\d{2}-[A-Z]{2}$

Matches: "AB-12-CD", "XY-99-ZZ" Does not match: "AB-1-CD", "AB-12-C"

Pattern: US license plate (flexible format)

^[A-Z0-9]{1,3}\s?[A-Z0-9]{1,4}$

Matches: "ABC 1234", "XY123", "1ABC234" Does not match: "ABCD 12345"

Container Numbers

Pattern: ISO container number (4 letters + 7 digits)

^[A-Z]{4}\d{7}$

Matches: "ABCU1234567", "MAEU9876543" Does not match: "ABC1234567", "ABCU123456"

Serial Numbers

Pattern: Alphanumeric with dashes, 8-12 characters

^[A-Z0-9]{2,4}-[A-Z0-9]{2,4}-[A-Z0-9]{2,4}$

Matches: "AB-12-CD", "ABC-1234-DEFG" Does not match: "AB-CD", "AB12CD"

Use in Event Rules

To use a regular expression in an Event Rule validation:

  1. Create or open an Event Rule (see Event Rules).
  2. Add a validation step with:
    • Validation Type: Regex
    • Field Caption: Select the field to validate
    • Regular Expression Code: Choose your regex pattern
    • Action Type: Error, Message, Notification, or Function
    • Message Template: Define the validation failure message

Example validation step message:

Field {CheckFieldCaption} must match format: Customer prefix followed by 6 digits (e.g., CUST-123456). Current value: {Value}
Important

Regex validation executes during record insert or modify operations. Complex patterns can impact performance, so test thoroughly and keep patterns as simple as possible.

Use in Other Features

Regular expressions can be used in several 3PL Dynamics features:

Serial Number Handling

Configure regex patterns in WMS Serial No. Handling to validate serial numbers during warehouse activities. This ensures serial numbers follow expected formats before they're recorded.

Address Validation

Use regex patterns in address records to validate postal codes, phone numbers, or custom reference fields specific to regions or customers.

Forwarding Setup

Configure container number validation in WMS Forwarding Setup to ensure freight forwarding documents use correct container formats.

Testing Regular Expressions

Before using a regex pattern in production, test it thoroughly:

Online Testing Tools

Use online regex testers to validate patterns:

  • regex101.com - Provides detailed explanations and testing
  • regexr.com - Visual testing with reference guide
  • Ensure you select .NET (C#) flavor, as 3PL Dynamics uses .NET regex

Test Cases

Create test cases covering:

  • Valid values that should match
  • Invalid values that should not match
  • Edge cases (empty strings, very long values)
  • Special characters and spacing

Example test cases for ^CUST-\d{6}$:

  • ✅ Should match: "CUST-123456", "CUST-000001"
  • ❌ Should not match: "CUST-12345", "CUSTOMER-123456", "cust-123456", "CUST-1234567"

Event Rule Testing

Use the Test Rule action on Event Rules to verify regex validations work correctly with actual records before activating the rule.

Tip

Start with simple patterns and add complexity gradually. Test each addition to ensure the pattern still works as expected.

Common Mistakes

Avoid these common regex pitfalls:

Missing Anchors

Bad:  \d{4}        # Matches "1234" anywhere in "ABC1234XYZ"
Good: ^\d{4}$      # Only matches exactly "1234"

Forgetting to Escape Special Characters

Bad:  CUST-\d{4}.  # Period matches any character
Good: CUST-\d{4}\. # Period matches literal period

Incorrect Quantifiers

Bad:  \d{4-6}      # Invalid syntax
Good: \d{4,6}      # 4 to 6 digits

Case Sensitivity

Bad:  ^[a-z]{2}$   # Only matches lowercase
Good: ^[A-Z]{2}$   # Matches uppercase (if that's required)

Overly Greedy Patterns

Bad:  .*@.*        # Matches too much
Good: [\w\.-]+@[\w\.-]+\.\w{2,}  # More specific

Advanced Patterns

For complex validation scenarios, regular expressions support advanced features:

Groups and Alternation

Use | for "or" logic:

^(CUST|VEND|CONT)-\d{6}$

Matches: "CUST-123456", "VEND-789012", "CONT-456789"

Non-Capturing Groups

Use (?:...) for grouping without capturing:

^(?:CUST|VEND)-\d{6}$

Same matching behavior, better performance.

Lookahead Assertions

Ensure a pattern exists without including it in the match:

^\d{4}(?=\s[A-Z]{2})

Validates that 4 digits are followed by space and 2 letters.

Note

Advanced patterns require careful testing. Consult the .NET regular expression documentation for detailed information on advanced features.

Troubleshooting

If a regular expression isn't working as expected:

  1. Test online first: Use regex101.com with .NET flavor to verify pattern logic
  2. Check escaping: Ensure special characters are properly escaped with backslash
  3. Verify anchors: Confirm ^ and $ are used if you want exact matches
  4. Review case sensitivity: .NET regex is case-sensitive by default
  5. Check field length: Ensure the pattern can fit within the field's maximum length
  6. Review logs: Use Event Rule logs to see actual field values and validation results

Common Error Messages

Error Cause Solution
"Invalid pattern" Regex syntax error Verify pattern syntax in online tester
"Pattern matches empty" Pattern allows empty strings Add + quantifier or ensure minimum length
"Performance warning" Complex pattern taking too long Simplify pattern or optimize with non-capturing groups

Reference

For complete .NET regular expression syntax documentation, see:

Edit this page