Skip to content

BeforeInsert.Validator ​

Reject new records before they are saved, like a validation rule written in Apex.

Signature

apex
public interface Validator extends BeforeInsert.Handler {
    Boolean addErrorOnBeforeInsertWhen(TriggerTypes.InsertRecord record);
    void addErrorOnBeforeInsert(TriggerTypes.RejectableInsertRecord record);
}
  • addErrorOnBeforeInsertWhen(record): called once per record in the chunk. Return true to reject the record.
  • addErrorOnBeforeInsert(record): called right after its predicate returns true; it must attach an error to the record, or the library throws.

Example

apex
public with sharing class ContactValidator implements BeforeInsert.Validator {
    public Boolean addErrorOnBeforeInsertWhen(TriggerTypes.InsertRecord record) {
        return record.isBlank(Contact.Email);
    }

    public void addErrorOnBeforeInsert(TriggerTypes.RejectableInsertRecord record) {
        record.addError(Contact.Email, 'Email is required.');
    }
}
cls
public with sharing class OpportunityAmountValidator implements BeforeInsert.Validator {
    public Boolean addErrorOnBeforeInsertWhen(TriggerTypes.InsertRecord record) {
        return record.isNotNull(Opportunity.Amount) && record.lessThanOrEqualTo(Opportunity.Amount, 0);
    }

    public void addErrorOnBeforeInsert(TriggerTypes.RejectableInsertRecord record) {
        record.addError(Opportunity.Amount, 'Amount must be greater than zero. Leave it empty until the deal value is known.');
    }
}
cls
public with sharing class ContactEmailFormatValidator implements BeforeInsert.Validator {
    public Boolean addErrorOnBeforeInsertWhen(TriggerTypes.InsertRecord record) {
        if (record.isBlank(Contact.Email)) {
            return false;
        }

        return record.doesNotContain(Contact.Email, '@') || this.isSharedMailbox(record);
    }

    public void addErrorOnBeforeInsert(TriggerTypes.RejectableInsertRecord record) {
        if (record.doesNotContain(Contact.Email, '@')) {
            record.addError(Contact.Email, 'Email must be a full address, for example jane.doe@example.com.');
            return;
        }

        record.addError(Contact.Email, 'A shared mailbox cannot be used as a contact email. Use the person\'s own address.');
    }

    private Boolean isSharedMailbox(TriggerTypes.InsertRecord record) {
        for (String prefix : new List<String>{ 'info@', 'sales@', 'support@', 'contact@', 'admin@', 'noreply@', 'no-reply@' }) {
            if (record.startsWith(Contact.Email, prefix)) {
                return true;
            }
        }

        return false;
    }
}

Rules ​

  • Field errors add up. addError does not stop the run. Later handlers still run for the record, and each Validator that rejects it on a field adds its own message. A second record-level error replaces the first, so the library sees no new error and throws.
  • Name and address fields lose the field. On Name or a compound address field such as BillingCity, record.addError(field, message) shows the message at record level. Use ((Account) record.getNewSObject()).Name.addError(message) instead.
  • Populator wins. A class that also implements BeforeInsert.Populator runs only as a Populator. List Validators after the Populators, so they check the final values.
  • No DML. If the handler runs DML or publishes an event, the library throws.

WARNING

Every qualified record must get an error. If one gets none, the whole chunk fails, even with ContinueOnError.

Test ​

apex
@IsTest
static void addErrorOnBeforeInsertWithNegativeAmount() {
    // Setup
    Opportunity renewal = new Opportunity(Amount = -100);

    TriggerOrchestrator.mock().beforeInsertFor(OpportunityAmountValidator.class).with(renewal);

    // Test
    TriggerOrchestrator.runTestFor(new OpportunityAmountValidator());

    // Verify
    Assert.areEqual(new List<String>{ 'Amount' }, renewal.getErrors()[0].getFields(), 'The error should be attached to Amount.');
}