---
url: https://trigger.beyondthecloud.dev/before-insert/populator.md
description: >-
  Set, default or normalize fields on records before insert with record.put - no
  DML and no second save.
---

# BeforeInsert.Populator

Set fields on new records before they are saved.

**Signature**

```apex
public interface Populator extends BeforeInsert.Handler {
    Boolean populateOnBeforeInsertWhen(TriggerTypes.InsertRecord record);
    void populateOnBeforeInsert(TriggerTypes.InsertRecord record);
}
```

* `populateOnBeforeInsertWhen(record)`: called once per record in the chunk. Return `true` to populate the record.
* `populateOnBeforeInsert(record)`: called right after its predicate returns true, for that record.

**Example**

::: code-group

```apex [Skeleton]
public with sharing class ContactPopulator implements BeforeInsert.Populator {
    public Boolean populateOnBeforeInsertWhen(TriggerTypes.InsertRecord record) {
        return record.isBlank(Contact.LeadSource);
    }

    public void populateOnBeforeInsert(TriggerTypes.InsertRecord record) {
        record.put(Contact.LeadSource, 'Web');
    }
}
```

```cls \[Normalize]
public with sharing class ContactEmailNormalizationPopulator implements BeforeInsert.Populator {
    public Boolean populateOnBeforeInsertWhen(TriggerTypes.InsertRecord record) {
        return record.isNotBlank(Contact.Email);
    }

    public void populateOnBeforeInsert(TriggerTypes.InsertRecord record) {
        Contact newContact = (Contact) record.getNewSObject();

        record.put(Contact.Email, newContact.Email.trim().toLowerCase());
    }
}

```

```cls \[Default when blank]
public with sharing class OpportunityCloseDatePopulator implements BeforeInsert.Populator {
    public Boolean populateOnBeforeInsertWhen(TriggerTypes.InsertRecord record) {
        return record.isNull(Opportunity.CloseDate);
    }

    public void populateOnBeforeInsert(TriggerTypes.InsertRecord record) {
        record.put(Opportunity.CloseDate, this.endOfCurrentQuarter());
    }

    private Date endOfCurrentQuarter() {
        Date today = Date.today();
        Integer lastMonthOfQuarter = ((today.month() - 1) / 3 + 1) * 3;

        return Date.newInstance(today.year(), lastMonthOfQuarter, 1).addMonths(1).addDays(-1);
    }
}

```

:::

## Rules {#rules}

* **`put` writes to the row being saved.** Handlers listed later see the value.
* **No SOQL in the loop.** The predicate and the action run once per record, so a query there throws. Read parents with a [ParentQuery](/before-insert/add-ons/parent-query) and other records with a [RelatedQuery](/before-insert/add-ons/related-query).
* **Populator wins.** A class that also implements `BeforeInsert.Validator` runs only as a Populator.
* **Exceptions fail the save.** Without [ContinueOnError](/before-insert/add-ons/continue-on-error), an exception fails every record in the chunk. With it, the exception is logged and the save goes on.

::: warning
No DML. If the handler runs DML or publishes an event, the library throws. Change other records from an [AfterInsert.Writer](/after-insert/writer).
:::

## Test {#test}

```apex
@IsTest
static void populateOnBeforeInsertWithPaddedEmail() {
    // Setup
    Contact doe = new Contact(LastName = 'Doe', Email = ' Jane.Doe@Example.com ');

    TriggerOrchestrator.mock().beforeInsertFor(ContactEmailNormalizationPopulator.class).with(doe);

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

    // Verify
    Assert.areEqual('jane.doe@example.com', doe.Email, 'The email should be trimmed and lowercased.');
}
```
