Understanding the PXSetPropertyException in Acumatica

When building customizations for Acumatica ERP, providing clear and immediate feedback to users is essential for a good experience. The PXSetPropertyException is the primary tool in the Acumatica Framework for achieving this, allowing you to validate data and communicate issues directly on the user interface.

This exception is typically thrown within a FieldVerifying event handler to cancel an update and restore a field's previous value when a validation rule fails [citation:1][citation:2]. More broadly, it's the framework's way of notifying the user about a problem with their input, whether it's an error, a warning, or simply informational text [citation:3].

Core Use Cases

1. Basic Field Validation

The most common use case is to prevent invalid data from being entered into a specific field. The PXSetPropertyException is thrown directly in a FieldVerifying handler to notify the user and revert the field to its previous valid state [citation:1].

protected virtual void _(Events.FieldVerifying<MyDAC.myField> e)
{
    // Validate that the new value is not negative
    if ((decimal)e.NewValue < 0)
    {
        throw new PXSetPropertyException("The value cannot be negative.");
    }
}

2. Displaying Warnings with Auto-Correction

Sometimes, rather than throwing an error, you might want to automatically correct a user's input to a valid value. In this case, you shouldn't throw an exception. Instead, you can set the corrected value and use the RaiseExceptionHandling method to display a warning message to inform the user of the change [citation:1][citation:2].

protected virtual void _(Events.FieldVerifying<MyDAC.myField> e)
{
    // If the value is too low, correct it
    if ((decimal)e.NewValue < 10)
    {
        e.NewValue = 10;
        sender.RaiseExceptionHandling<MyDAC.myField>(
            e.Row, e.NewValue,
            new PXSetPropertyException(
                "The value has been corrected to the minimum of 10.",
                PXErrorLevel.Warning)
        );
    }
}

3. Row-Level Validation

For validation that involves multiple fields on a data row, the PXSetPropertyException is often used in overridden Persist methods or row-level event handlers [citation:10][citation:7]. This ensures the user cannot save a record that is in an invalid state.

public class MyGraph_Extension : PXGraphExtension<MyGraph>
{
    [PXOverride]
    public void Persist(PersistDelegate baseMethod)
    {
        // Check if validation condition is met
        if (Base.MyView.Select().Count == 0)
        {
            throw new PXSetPropertyException(
                "At least one record is required.",
                PXErrorLevel.RowError);
        }
        baseMethod();
    }
}

Error Levels and Notification Types

The PXSetPropertyException constructor accepts a PXErrorLevel parameter that determines how the message is displayed to the user [citation:4].

Best Practices & Key Considerations

Conclusion

The PXSetPropertyException is a fundamental building block for creating robust and user-friendly Acumatica customizations. By using it correctly, you can provide clear, immediate feedback, prevent data corruption, and guide users through complex business processes.