---
url: https://trigger.beyondthecloud.dev/before-update/populator.md
description: >-
  Set, derive or clear fields on records being updated, usually when another
  field changed - no DML and no second save.
---

# 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**

::: code-group

```apex [Skeleton]
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 \[Set on change]
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 \[Read the old row]
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 {#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](/before-update/add-ons/recursion-guard) 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](/after-update/writer).
:::

## Test {#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.');
}
```
