Data should be validated before usage, especially data that is provided by the end-users, for example:
Logic inputs
Pricing Parameters that are updated by the end users
Prices from price-lists
In general, there are two courses of actions to take when a data validation fail.
When an issue can be resolved by the end-user, display a warning. The message in the warning should guide the end-user towards a resolution, for example:
Input is missing a required value.
Text input is incorrectly formatted.
A number input is exceeding a limit.
A pricing parameter is missing.
The result from previous elements are missing, or invalid, due to invalid user input.
When an issue cannot be resolved by the end-user, throw an exception. To recover from these fatal issues, typically a support engineer or a super-user would need to be involved. Examples of fatal issues are:
When a required configuration is missing.
When integration with a third-party service has failed and required data is missing.
Throw exceptions with api.throwException(). The message on the screen will be more end-user friendly than when using throw new Exception()
.
Code Example
Here is is a code example for calculating a margin quotient, MarginPct:
// Value Dependencies BigDecimal invoicePrice = out.InvoicePrice BigDecimal margin = out.Margin // Data Validation if(invoicePrice == null){ api.addWarning("The invoice price is missing") return } if(margin == null){ api.addWarning("The margin is missing") return } if(margin == 0){ api.addWarning( """Margin % cannot be calculated, because the absolute margin is 0 and this would lead to division by 0.""" ) return } // Calculation BigDecimal marginPct = margin / invoice price return marginPct