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:

Navigate to the Validation service on the partner or customer level and click EDIT.
Click ADD on the Custom rules tab. The Custom Validation rule view appears.
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.

Optionally specify a Description. The description appears in the tooltip of the rule in the Extraction service settings.
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.
In the Field to validate setting, select the field that should be marked with a validation error if the rule fails.
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: / - ( ) = , + *.
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.
Click OK to return to the Validation view.
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.
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 demonstrate what is possible with custom rules and are meant for illustrative purposes only. Some examples might depict unrealistic or existing validation rules. The example formulas show what you enter in the Expression box.

The expression you specify must evaluate to a boolean value, true or false. When an expression evaluates to false, its validation rule fails.

Expression	Meaning
InvoiceTotalVatIncludedAmount < 1000000	Ensures the total amount is less than 1,000,000. If the total amount is 1,000,000 or more, the validation fails, and the field you specify on the Field to validate setting is marked with a validation error. In this example, you would specify InvoiceTotalVatIncludedAmount as the Field to validate. InvoiceTotalVatIncludedAmount — The total price of an invoice, including VAT. < — Means "is less than. " The rule checks if InvoiceTotalVatIncludedAmount is smaller than the number 1,000,000. 1000000 — The upper limit for the total amount. The rule is saying, "Invoices must be below 1,000,000."
InvoiceTotalVatRatePercent == (InvoiceTotalVATAmount / InvoiceTotalVatExcludedAmount) * 100	Ensures the total VAT rate percentage (InvoiceTotalVatRatePercent) is calculated correctly. The percentage is calculated by dividing the total VAT amount by the VAT-excluded amount and multiplying by 100. In this example, you would specify InvoiceTotalVatRatePercent as the Field to validate. InvoiceTotalVatRatePercent — Represents the VAT rate in percentage, like 25%. == — Means "is equal to." The rule checks if the value on the left (InvoiceTotalVatRatePercent) matches the calculation on the right. (InvoiceTotalVATAmount / InvoiceTotalVatExcludedAmount) — Calculates the VAT rate as a decimal. When you divide these, you get a decimal, like 0.25 for 25%. * 100 — Converts the decimal into a percentage. For example, 0.25 becomes 25. 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(...) — Calculates the absolute value of a number, ignoring whether it is positive or negative. LIT_VatExcludedAmount — The total amount for the line item, excluding VAT. LIT_UnitPriceAmount — The price of a single unit for the line item. LIT_DeliveredQuantity — The quantity delivered for this line item. < 0.5 — Ensures the difference is less than 0.5, allowing for small rounding errors.
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 sum of LIT_VatAmount for all line items is empty or 0. Otherwise, it checks that the absolute difference between the sum of all LIT_VatAmount fields and InvoiceVATAmount is less than 0.5. In this example, you would specify InvoiceVATAmount as the Field to validate. Note the use of a header field (InvoiceVATAmount) and a line-item field (LIT_VatAmount) in the calculation. Since Field to validate is set to InvoiceVATAmount, which is a header field, LIT_VatAmount represents the sum of all LIT_VatAmount fields. LIT_VatAmount — The sum of all line-item VAT amount fields. == 0 — Ensures the VAT is zero or empty. or — Allows either condition to pass for the rule to be valid. abs(...) — Calculates the absolute difference, ignoring whether it's positive or negative. LIT_VatAmount - InvoiceVATAmount — Checks the difference between the sum of the line item VAT amounts and the expected invoice VAT. < 0.5 — Permits a small rounding error of less than 0.5.

Custom rule syntax

These functions and operators are available when creating a custom validation rule.

Function/Operator	Description	Example
abs	Returns the absolute value of a number, which is the distance from zero. In other words, the absolute value is the value without regard to whether the number is positive or negative.	abs(-5) returns 5.
max	Returns the largest of the numbers given as input parameters.	max(2, 5, 3) returns 5.
min	Returns the smallest of the numbers given as input parameters.	min(2, 5, 3) returns 2.
round	Returns the value of a number rounded to the nearest integer.	round(3.14) returns 3.
+	Adds two values.	3 + 5 returns 8.
-	Subtracts one value from another.	5 - 3 returns 2.
*	Multiplies two values.	3 * 5 returns 15.
/	Divides the value on the left by the value on the right.	10 / 2 returns 5.
==	Checks if two values are equal. Returns True if they are, False if not.	5 == 5 returns True.
!=	Checks if two values are not equal. Returns True if they are different, False if they are equal.	5 != 3 returns True.
<	Checks if the value on the left is less than the value on the right.	3 < 5 returns True.
>	Checks if the value on the left is greater than the value on the right.	5 > 3 returns True.
<=	Checks if the value on the left is less than or equal to the value on the right.	3 <= 5 returns True.
>=	Checks if the value on the left is greater than or equal to the value on the right.	5 >= 3 returns True.
()	Controls the precedence of evaluation in expressions. Expressions inside the parenthesis are evaluated first. It also acts as a container for arbitrary expressions where ambiguity or syntax errors would otherwise occur.	((1 + 2) * 3) returns 9.
and	Returns True if both conditions are True.	(3 < 5) and (5 > 3) returns True.
or	Returns True if at least one of the conditions is True.	(3 < 5) or (5 < 3) returns True.
not	Reverses the truth value of a condition.	not(3 < 5) returns False.

AP Essentials validates custom rules whenever you save a rule or click TEST. 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)))))))))