Data should be validated before usage, especially data that is provided by the end users, for example:

Logic inputs
Company 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 company parameter is missing.
The results from previous elements are missing, or invalid, due to invalid user input.

In case a quote, a contract, or a rebate agreement cannot be calculated, collect the warning and throw an exception to force the user to fix the inputs first.

When an issue cannot be resolved by the end user or a calculation cannot be finalized, throw an exception. To recover from these fatal issues, typically a super user or support engineer would need to be involved. Examples of fatal issues are:

Required configuration is missing.
Integration with a third-party service has failed and required data is missing.

The error message should be descriptive and ideally referring to the record which is causing the failure, e.g.:

“Customer 10000123 is missing ShipTo location”
Target margin is not defined for product family D123 in PP TargetMargin“

Throw exceptions with api.throwException(). The message on the screen will be more user friendly than when using throw new Exception().

Code Example

Here 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