Trigger Framework
D'fflib comes with an extended trigger framework, enabling bulkified, scalable and maintainable trigger handlers.
Highlights & takeaways
D'fflib enforces one trigger per SObject, delegating all orchestration to the Domain class. Handlers are registered per trigger event, executed in a structured three-phase lifecycle (initialize → process → finalize), and share a single Unit of Work commit — keeping your trigger logic bulkified, testable, and free of scattered DML.
Main benefits
Simplified and standardised trigger initiation
Each trigger directly delegates to the Domain class with the one-liner dfflib_SObjectDomain.triggerHandler( [class] ).
Clearer handler separation and management
Handlers are centrally registered in the Domain constructor, defining execution order and event coverage. Encouraging trigger logic to be split to handlers with single- and clear responsibilities.
One Handler can be easily registered to multiple trigger events, encouraging reuse and avoiding duplicate code.
Bulkified architecture
Each handler follows a three-phase lifecycle:
- Single
initialize()for preparing data in bulk (like queries and other loops) - Per record
process()allowing clean execution of the handler's main operation - Single
finalize()for concluding the logic and saving back to the database (in bulk)
This encourages bulkified handlers with no SOQL and DML inside loops and easy to understand and manage logic.
Built-in transaction management
All handlers share the same dfflib_ISObjectUnitOfWork instance injected by the framework. Work is registered
across handlers and committed after all handlers have completed. This enables grouping records and eliminating
repetitive DML round-trips and governor limit pressure.
Additionally, this simplifies testing and mocking, aside from centralised and built-in transaction management. Avoiding the need for Rollback and Exception handling scattered across the trigger.
Execution control
Handlers explicitly implement one or multiple TriggerEvent interfaces and opt. FireOnce to control execution.
Ensuring records are only processed once per transaction and avoiding duplicate work across trigger events.
Isolated, independently testable handlers
Because each handler is a self-contained inner class with a clear interface, it can be instantiated and tested in isolation without firing the full trigger stack. This dramatically reduces test setup complexity.
Metadata-driven handler registration in progress
We're currently finalising the migration for Trigger Handler registrations from Domain constructor to metadata. Simplifying registration and giving more flexibility to enable/disable handlers without code changes.
How to set up a Domain class
Step-by-step guide to configuring your Domain class, including constructor setup and handler registration.
How to build trigger handlers
Walkthrough for creating BaseHandler implementations, applying FireOnce, and structuring the three-phase lifecycle.
What it brings
The Domain as trigger orchestrator
The trigger itself is a one-liner. It delegates immediately to the Domain class, which owns all orchestration:
trigger AccountsTrigger on Account (before insert, before update, before delete, after insert, after update, after delete, after undelete) {
dfflib_SObjectDomain.triggerHandler(DOM_Accounts.class);
}The Domain constructor is where handlers are registered. Each registerHandler call binds a TriggerEvent to a handler class:
public with sharing class DOM_Accounts extends dfflib_SObjectDomain implements IDomain {
public DOM_Accounts(List<Account> records) {
super(records, dfflib.unitOfWork.newInstance());
registerHandler(TriggerEvent.AFTER_INSERT, SyncAccountToERP.class);
registerHandler(TriggerEvent.AFTER_UPDATE, SyncAccountToERP.class);
}
public class Constructor implements dfflib_SObjectDomain.IConstructable {
public dfflib_SObjectDomain construct(List<SObject> sObjectList) {
return new DOM_Accounts(sObjectList);
}
}
}See Domain setup for the full Domain class configuration.
Handler anatomy: initialize → process → finalize
Every handler extends BaseHandler and optionally overrides three lifecycle methods. The framework calls them in order for every trigger invocation:
public class CalculateTotalPrice extends BaseHandler implements BeforeInsert, BeforeUpdate{
// Called once before record iteration — use for bulk queries and setup
public override void initialize( TriggerState ts, dfflib_ISObjectUnitOfWork uow ){
// e.g. pre-load related records from a selector
}
// Called once per record — no SOQL, no DML
public override Boolean process( SObject current, SObject original, dfflib_ISObjectUnitOfWork uow ){
RoomReservation__c newRecord = ( RoomReservation__c ) current;
RoomReservation__c oldRecord = ( RoomReservation__c ) original;
// register work on uow, return true if this record was processed
return true;
}
// Called once after record iteration
public override void finalize( TriggerState state, dfflib_ISObjectUnitOfWork uow ){
// e.g. call Domain method, Log
}
}The process() return value feeds into FireOnce deduplication (see below). Returning true signals the record was handled; returning false leaves it eligible for re-processing in a subsequent trigger invocation.
TriggerState — bulk context across phases
A TriggerState instance is injected into both initialize() and finalize(). It acts as a shared context object for the handler's full lifecycle — allowing data loaded in initialize() (e.g. a map of related records) to be available in finalize() without passing it through process(). This keeps the per-record method signature clean while still supporting bulk patterns.
public class TriggerState{
public final List<SObject> currentList;
public final List<SObject> originalList;
}FireOnce — smart deduplication
Handlers that implement FireOnce are only executed once per record per transaction. If process() returns true for a record, that record is skipped on any subsequent trigger invocation within the same transaction.
public class SyncAccountToERP extends BaseHandler implements FireOnce, AfterInsert, AfterUpdate {
// ...
}Trigger event coverage
Register handlers against any of the following TriggerEvent enum values:
| Enum value | Trigger context |
|---|---|
BEFORE_INSERT | Before insert |
BEFORE_UPDATE | Before update |
BEFORE_DELETE | Before delete |
AFTER_INSERT | After insert |
AFTER_UPDATE | After update |
AFTER_DELETE | After delete |
AFTER_UNDELETE | After undelete |
ALL | All trigger events |
Each enum value has a corresponding interface (BeforeInsert, AfterUpdate, AllEvents, etc.) that the handler implements to declare which events it responds to.
Test Data Builder Framework
D'fflib ships a complete Test Data Builder Framework to quickly set up typed, fluent test data — including parent and child relations, formula fields and read-only fields — without touching the database.
Get started
Learn how to easily install, upgrade or update D'fflib in your Salesforce environment, and what is needed to maximise framework benefits.