›

Create custom validation rules

This procedure shows how to create custom validation rules.

AP Essentials offers many pre-defined validation rules that cover most needs. However, if you have specialized requirements that are not covered by the standard rules, you can create custom rules to ensure accuracy and correctness of your document data. By implementing custom validation rules, organizations can minimize errors, prevent data discrepancies, and streamline financial processes, ultimately enhancing the reliability of their financial reporting and reducing the risk of costly mistakes.

Custom validation rules are currently available only for amount fields, whether predefined or custom. The user interface provides a visual builder to make it easy to specify available fields and common operations. You can create up to 30 custom rules per organization.

To create a custom validation rule:

  1. Navigate to the Validation service on the partner level, click the Custom rules tab and click EDIT.
  2. Click ADD. The Custom Validation rule view appears.
  3. Specify a Name for your custom rule.

    Choose a name that is logical and self-explanatory, as this is the name that appears in the Rules tab of the document type in the Extraction service.

  4. Specify the base document type this rules applies to in the Base type setting. For example, if you select Supplier invoice, this rule will be available for all document types whose base type is supplier invoice.
  5. In the Field to validate setting, select the field that should be marked with a validation error if the rule fails.
  6. Specify your rule logic in the Expression box. Use the Fields, Operators, and Functions boxes to insert elements of you expression by selecting a value and clicking the + button. In addition to the available fields, operators, and functions, you can use parenthesis for grouping.

    Validations can be as easy or complex as your solution requires. See examples later in this topic.

    You cannot create custom rules with field type names that include any of the following characters: / - ( ) = , + *.

  7. Type a Validation error message that is displayed if the validation fails. This message is displayed in AP Essentials Office on the field you specified in the Field to validate setting.
  8. Click OK to return to the Validation view.
  9. Select your new rule in the list and click SAVE.

    If you do not select the rule, it will not appear in the Extraction service settings of the customer accounts.

  10. Navigate to the customer account that has a document type where you want to enable the custom rule and enable it.

    Your custom rule is immediately utilized during extraction, verification, and approval.

Custom rule examples

The following examples depict what is possible with custom rules and are meant for illustrative purposes only. Some examples might mirror existing validation rules. The example formulas show what you enter in the Expression box.

Expression Meaning
InvoiceTotalVatRatePercent == (InvoiceTotalVATAmount / InvoiceTotalVatExcludedAmount) * 100

Ensures the total VAT rate percentage (InvoiceTotalVatRatePercent) is calculated correctly. In this example, you would specify InvoiceTotalVatRatePercent as the Field to validate.

Note: This example is for demonstration only. In practice, we recommend using tolerances to avoid validation errors from small differences.

abs(LIT_VatExcludedAmount - LIT_UnitPriceAmount * LIT_DeliveredQuantity) < 0.5

Ensures the line-item net amount (LIT_VatExcludedAmount) equals the unit price (LIT_UnitPriceAmount) times the quantity (LIT_DeliveredQuantity) and is within an acceptable limit. In this example, you would specify LIT_VatExcludedAmount as the Field to validate.

abs((InvoiceTotalVatIncludedAmount + AmountRounding) - InvoiceTotalVatIncludedAmount) < 0.5

Ensures that the rounding is within an acceptable limit. In this example, you would specify InvoiceTotalVatIncludedAmount or AmountRounding as the Field to validate.

LIT_VatAmount == 0 or abs(LIT_VatAmount - InvoiceVATAmount) < 0.5

Ensures the VAT amount is within an acceptable limit. The rule evaluates to true if there are no line items or if the LIT_VatAmount for all line items is empty or 0. Otherwise, it checks that the absolute difference between sum of all fields of type LIT_VatAmount and InvoiceVATAmount is less than 0.5. In this example, you would specify InvoiceVATAmount as the Field to validate.

Custom rule syntax

AP Essentials validates custom rules whenever you save a rule. This table shows the errors you can encounter if a custom rule has incorrect syntax.

Error Description Example
Unexpected token A character appears at an unexpected position. a +- b < c
Missing token The expression ends unexpectedly. a + b <
Invalid function name A function call references an unknown function. foo(a) < b
Missing parameter One or more parameters of a function are not specified. For example, the function uses two parameters, but only one is specified. min(a,) < b
Invalid number of parameters A function is called with an invalid number of parameters. For example, the function uses one parameter, but two are specified. abs(a, b) < c
Bracket mismatch The number of opening and closing brackets do not match. (abs(a) < b
Return type error The outcome of the expression is not true or false. a + b
Too complex The expression is too complex or uses nested structures that are too deep. a == round(round(round(round(round(round(round(round(round(b)))))))))