Skip to content

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

apex
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
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
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 ​

  • 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 and other records with a RelatedQuery.
  • Populator wins. A class that also implements BeforeInsert.Validator runs only as a Populator.
  • Exceptions fail the save. Without ContinueOnError, 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.

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.');
}