Skip to content

BeforeUpdate.Populator ​

Set fields on records being updated before they are saved.

Signature

apex
public interface Populator extends BeforeUpdate.Handler {
    Boolean populateOnBeforeUpdateWhen(TriggerTypes.UpdateRecord record);
    void populateOnBeforeUpdate(TriggerTypes.UpdateRecord record);
}
  • populateOnBeforeUpdateWhen(record): called once per record in the chunk; with a RecursionGuard, a record past its limit is skipped without a call. Return true to populate the record.
  • populateOnBeforeUpdate(record): called right after its predicate returns true, for that record.

Example

apex
public with sharing class ContactPopulator implements BeforeUpdate.Populator {
    public Boolean populateOnBeforeUpdateWhen(TriggerTypes.UpdateRecord record) {
        return record.isChanged(Contact.Email);
    }

    public void populateOnBeforeUpdate(TriggerTypes.UpdateRecord record) {
        record.put(Contact.HasOptedOutOfEmail, false);
    }
}
cls
public with sharing class OpportunityForecastPopulator implements BeforeUpdate.Populator {
    public Boolean populateOnBeforeUpdateWhen(TriggerTypes.UpdateRecord record) {
        Opportunity newOpportunity = (Opportunity) record.getNewSObject();

        return record.isAnyChanged(Opportunity.Amount, Opportunity.StageName) &&
            !new Set<String>{ 'Closed Won', 'Closed Lost' }.contains(newOpportunity.StageName) &&
            record.lessThan(Opportunity.Amount, 5000);
    }

    public void populateOnBeforeUpdate(TriggerTypes.UpdateRecord record) {
        record.put(Opportunity.ForecastCategoryName, 'Omitted');
    }
}
cls
public with sharing class AccountShippingSyncPopulator implements BeforeUpdate.Populator {
    public Boolean populateOnBeforeUpdateWhen(TriggerTypes.UpdateRecord record) {
        Boolean billingMoved = record.isAnyChanged(Account.BillingStreet, Account.BillingCity, Account.BillingState, Account.BillingPostalCode, Account.BillingCountry);

        return billingMoved && this.shippingFollowedBilling((Account) record.getOldSObject());
    }

    public void populateOnBeforeUpdate(TriggerTypes.UpdateRecord record) {
        Account newAccount = (Account) record.getNewSObject();

        record.put(Account.ShippingStreet, newAccount.BillingStreet);
        record.put(Account.ShippingCity, newAccount.BillingCity);
        record.put(Account.ShippingState, newAccount.BillingState);
        record.put(Account.ShippingPostalCode, newAccount.BillingPostalCode);
        record.put(Account.ShippingCountry, newAccount.BillingCountry);
    }

    private Boolean shippingFollowedBilling(Account oldAccount) {
        if (String.isBlank(oldAccount.ShippingStreet) && String.isBlank(oldAccount.ShippingCity)) {
            return true;
        }

        return oldAccount.ShippingStreet == oldAccount.BillingStreet &&
            oldAccount.ShippingCity == oldAccount.BillingCity &&
            oldAccount.ShippingPostalCode == oldAccount.BillingPostalCode &&
            oldAccount.ShippingCountry == oldAccount.BillingCountry;
    }
}

Rules ​

  • put counts as a change. Handlers listed later see the value, and isChanged is true for them. Putting the old value back makes the field unchanged.
  • Gate on a change. The Populator runs again when the same records are updated again in the transaction. There, isChanged compares with the values the previous update saved. When a record comes back after 3 passes, each run logs an error; a RecursionGuard sets its own depth and also skips the record.
  • Never write to getOldSObject(). The FinalException cannot be caught and fails the update.
  • Populator wins. A class that also implements BeforeUpdate.Validator runs only as a Populator.

WARNING

No DML. If the handler runs DML or publishes an event, the library throws. Change other records from an AfterUpdate.Writer.

Test ​

apex
@IsTest
static void populateOnBeforeUpdateWithSmallAmount() {
    // Setup
    Opportunity renewal = new Opportunity(StageName = 'Prospecting', Amount = 4000);

    TriggerOrchestrator.mock().beforeUpdateFor(OpportunityForecastPopulator.class).with(renewal, new Opportunity(StageName = 'Prospecting', Amount = 9000));

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

    // Verify
    Assert.areEqual('Omitted', renewal.ForecastCategoryName, 'The forecast category should be Omitted.');
}