Friday, 5 June 2026

Mastering fflib Unit of Work in Apex: Insert, Update, and Delete with Clean Transaction Management

 When Salesforce code grows, DML statements can quickly become scattered across triggers, services, and helper classes. The fflib Unit of Work pattern helps by collecting pending database changes and committing them together at the end of a business transaction. This makes code easier to maintain, encourages bulk-safe design, and helps keep related changes inside one managed transaction. The fflib docs also note that Unit of Work is generally created in the Service layer, and the transaction is finalized with commitWork() at the end. [fflib.dev], [deepwiki.com], [fflib.dev]

In fflib, the Unit of Work tracks several categories of record changes before commit: new records for insert, dirty records for update, and deleted records for delete. The framework provides methods such as registerNew, registerDirty, registerDeleted, and commitWork() to manage these changes in a structured way. Documentation and source summaries also highlight that the implementation is designed to bulkify DML, maintain transaction integrity, and apply operations in a consistent sequence. [deepwiki.com], [deepwiki.com], [github.com]

A particularly useful method is registerDirty(...). In the Unit of Work pattern, a dirty record means an existing record that has already been loaded or identified, then modified in memory, and now needs to be updated in the database when commitWork() is called. That gives you a clean way to separate business logic from database execution. [deepwiki.com], [deepwiki.com]

Why use Unit of Work in Apex?

Apex developers often try to keep DML outside loops and avoid mixing persistent operations with business logic. Unit of Work supports this goal by centralizing inserts, updates, and deletes into one place. According to the framework documentation and source summaries, this pattern helps with bulkified DML, atomic transaction handling, and even relationship management for related objects when needed. [deepwiki.com], [deepwiki.com], [github.com]

Another useful detail from the fflib docs is that the order of SObject types passed into the Unit of Work can matter, especially when object dependencies exist. For a simple Account example, that is not a major issue, but it becomes important in multi-object transactions such as Account + Contact or Opportunity + OpportunityLineItem. [fflib.dev]

A simple but proper Apex example

Below is a clean example using a single service class to demonstrate:

  • Insert with registerNew
  • Update with registerDirty
  • Delete with registerDeleted

This example keeps the pattern simple and readable while still reflecting how Unit of Work is intended to be used in a service-oriented design. The class uses Account records only, which makes the learning path straightforward. The code itself below is original and written for this post. The method choices are based on the documented Unit of Work API. [fflib.dev], [deepwiki.com], [deepwiki.com]

Apex Service Class


public with sharing class AccountUnitOfWorkService {

/**
* Inserts new Accounts using Unit of Work.
*/
public static void createAccounts(List<String> accountNames) {
if (accountNames == null || accountNames.isEmpty()) {
return;
}

fflib_ISObjectUnitOfWork uow =
new fflib_SObjectUnitOfWork(
new List<SObjectType>{ Account.SObjectType }
);

for (String accountName : accountNames) {
if (String.isBlank(accountName)) {
continue;
}

Account acc = new Account(
Name = accountName.trim()
);

uow.registerNew(acc);
}

uow.commitWork();
}

/**
* Updates existing Account names using registerDirty.
* Map key = Account Id
* Map value = New Account Name
*/
public static void updateAccountNames(Map<Id, String> accountNamesById) {
if (accountNamesById == null || accountNamesById.isEmpty()) {
return;
}

List<Account> accountsToUpdate = [
SELECT Id, Name
FROM Account
WHERE Id IN :accountNamesById.keySet()
];

fflib_ISObjectUnitOfWork uow =
new fflib_SObjectUnitOfWork(
new List<SObjectType>{ Account.SObjectType }
);

for (Account acc : accountsToUpdate) {
String newName = accountNamesById.get(acc.Id);

if (String.isBlank(newName)) {
continue;
}

String trimmedName = newName.trim();
if (acc.Name != trimmedName) {
acc.Name = trimmedName;
uow.registerDirty(acc);
}
}

uow.commitWork();
}

/**
* Deletes Accounts using Unit of Work.
*/
public static void deleteAccounts(Set<Id> accountIds) {
if (accountIds == null || accountIds.isEmpty()) {
return;
}

List<Account> accountsToDelete = [
SELECT Id
FROM Account
WHERE Id IN :accountIds
];

fflib_ISObjectUnitOfWork uow =
new fflib_SObjectUnitOfWork(
new List<SObjectType>{ Account.SObjectType }
);

for (Account acc : accountsToDelete) {
uow.registerDeleted(acc);
}

uow.commitWork();
}
}

How this class maps to the Unit of Work pattern

The createAccounts method builds new Account records in memory and registers each one with registerNew(...). These records are not inserted immediately; instead, they are staged inside the Unit of Work until commitWork() runs. That aligns with the documented behavior of Unit of Work tracking new records and then inserting them in a single managed commit. [deepwiki.com], [deepwiki.com]

The updateAccountNames method demonstrates the most important concept for many developers: dirty records. First, it queries existing Accounts, then updates the Name field in memory, and finally uses registerDirty(acc) to tell the Unit of Work that the record must be updated when the transaction is committed. This follows the documented purpose of registerDirty(...) for existing modified records. [deepwiki.com], [deepwiki.com]

The deleteAccounts method selects existing records and adds them to the Unit of Work using registerDeleted(...). The actual delete does not happen until commitWork() is called, which matches how the framework tracks deleted records before commit. [deepwiki.com], [deepwiki.com]

Example usage

Here is a simple example of how the service methods could be called from anonymous Apex or another orchestration layer:

// Insert
AccountUnitOfWorkService.createAccounts(
new List<String>{ 'Acme UK', 'Cloud Nova Ltd', 'Northwind Services' }
);


// Update
Map<Id, String> nameUpdates = new Map<Id, String>();
nameUpdates.put('001XXXXXXXXXXXXAAA', 'Acme UK - Updated');
nameUpdates.put('001YYYYYYYYYYYYAAA', 'Cloud Nova Ltd - Updated');
AccountUnitOfWorkService.updateAccountNames(nameUpdates);


// Delete
Set<Id> accountsToDelete = new Set<Id>{
'001XXXXXXXXXXXXAAA',
'001YYYYYYYYYYYYAAA'
};
AccountUnitOfWorkService.deleteAccounts(accountsToDelete);

This style keeps calling code clean and leaves DML orchestration in one dedicated service class, which is consistent with the service-layer guidance in the fflib docs. [fflib.dev], [fflib.dev]

Optional test class

A blog post is much stronger when it includes a working test. Here is a compact example:

@IsTest
private class AccountUnitOfWorkServiceTest {


@IsTest
static void testInsertUpdateDeleteUsingUnitOfWork() {
// Insert
Test.startTest();
AccountUnitOfWorkService.createAccounts(
new List<String>{ 'Original Account' }
);
Test.stopTest();


Account inserted = [
SELECT Id, Name
FROM Account
WHERE Name = 'Original Account'
LIMIT 1
];
System.assertNotEquals(null, inserted.Id);


// Update using registerDirty
Test.startTest();
AccountUnitOfWorkService.updateAccountNames(
new Map<Id, String>{
inserted.Id => 'Updated Account'
}
);
Test.stopTest();


Account updated = [
SELECT Id, Name
FROM Account
WHERE Id = :inserted.Id
];
System.assertEquals('Updated Account', updated.Name);


// Delete
Test.startTest();
AccountUnitOfWorkService.deleteAccounts(
new Set<Id>{ inserted.Id }
);
Test.stopTest();


Integer remaining = [
SELECT COUNT()
FROM Account
WHERE Id = :inserted.Id
];
System.assertEquals(0, remaining);
}
}

This test validates the three major flows in one place: insert, update via registerDirty, and delete. Because Unit of Work collects changes and applies them on commit, it becomes much easier to reason about the transaction boundary in testing as well. [deepwiki.com], [deepwiki.com]

Best practices to mention in your blog

If you publish this article, here are a few practical recommendations worth calling out:

  1. Create the Unit of Work in the service layer and commit once at the end of the business transaction whenever possible. That is consistent with the fflib usage guidance. [fflib.dev], [fflib.dev]

  2. Use registerDirty(...) only for existing records that need an update. For brand-new records, use registerNew(...); for deletes, use registerDeleted(...). [deepwiki.com], [deepwiki.com]

  3. Think in bulk, even for simple examples. One of the key benefits of the pattern is reducing scattered DML and keeping operations bulk-friendly. [deepwiki.com], [github.com]

  4. Be mindful of SObject ordering when multiple object types participate in the same Unit of Work, because the docs note that order can matter for dependency handling. [fflib.dev]

Conclusion

The fflib Unit of Work pattern gives Apex developers a cleaner way to manage database operations. Instead of inserting, updating, and deleting records directly throughout your code, you can track all pending changes and commit them together in one controlled place. For updates specifically, registerDirty(...) is the key method to remember: it represents an existing record that has been modified and should be saved during commitWork(). This approach improves readability, supports bulkification, and makes transaction boundaries much easier to understand. [fflib.dev], [deepwiki.com], [deepwiki.com]

Reference

Primary reference used for this article: fflib Unit of Work documentation — https://fflib.dev/docs/unit-of-work [fflib.dev]

Additional supporting references:


Posted by at
Subscribe to: Posts (Atom)