Async-First Pattern with Platform Events (DoWork)

Overview

When to use this pattern: When trigger operations need to run asynchronously to avoid governor limits, prevent record locking, or ensure immediate trigger completion while deferring complex processing.

Purpose

The DoWork pattern provides a clean abstraction for moving synchronous trigger operations to asynchronous execution using Platform Events. This solves the common challenge of triggers that need to perform operations that would either hit governor limits, cause record locking issues, or need to run after the initial transaction commits.

Context

In complex Salesforce implementations, triggers often need to:

• Update the same record that triggered them (after auto-number generation)

• Perform callouts to external systems

• Execute operations that exceed governor limits when bulkified

• Avoid holding database locks during long-running operations

Platform Events provide immediate publication (before transaction commit) with separate execution context, making them ideal for async processing.

Problem Statement

The Challenge

Trigger operations that modify the triggering record or perform complex operations face several challenges:

1. Record Lock Contention: Direct updates during afterInsert cause UNABLE_TO_LOCK_ROW errors in high-concurrency scenarios

2. Governor Limits: Complex calculations or callouts may exceed limits when processing bulk records

3. Auto-Number Timing: Auto-number fields are not populated until after insert, requiring a separate update

4. Transaction Rollback Risk: Long-running operations increase the risk of entire transaction failure

Why Traditional Approaches Fall Short

• @future methods: Cannot accept SObject parameters, limited to 50 calls per transaction

• Queueable Apex: Better than @future but still counts against limits and has delay

• Batch Apex: Too heavyweight for simple trigger-initiated operations

• Direct DML in trigger: Causes record locking and transaction coupling

Solution

Core Concept

The DoWork pattern uses Platform Events as a lightweight message bus. Work items serialize themselves, publish as events, and a trigger deserializes and executes them in a separate transaction. This provides immediate asynchronous execution with automatic retry capabilities.

Implementation Strategy

1. Define the Work Interface

The interface defines the contract that all async work items must fulfill:

public interface IDoWork {
    /**
     * Executes all the work of the work item
     */
    void doWork();

    /**
     * @return Returns the name of the work item, used for logging purposes
     */
    String getClassName();

    /**
     * When the maximum retries has been reached this method is invoked
     * @param e The last thrown exception
     */
    void onException(Exception e);

    /**
     * Logic to execute on finally (after possible exception handling)
     */
    void onFinally();

    void publish();
    void publish(Integer retries);
}

2. Create the Abstract Base Class

The abstract class handles serialization and Platform Event publication:

public abstract class DoWorkAbstract implements IDoWork {

    public virtual void publish() {
        publish(0);
    }

    /**
     * @param retries The number of retries
     */
    public virtual void publish(Integer retries) {
        String serialized = JSON.serialize(this);
        if (serialized.length() > 131072) {
            throw new WorkException('Work item is too large');
        }

        Database.SaveResult results = EventBus.publish(
            new DoWork__e(
                Work__c = serialized,
                ClassName__c = getClassName(),
                Retries__c = retries
            )
        );

        if (results.isSuccess() == false) {
            String errorMessage = 'Unable to publish work item: ';
            for (Database.Error err : results.getErrors()) {
                errorMessage += err.getStatusCode() + ' - ' + err.getMessage();
            }
            throw new WorkException(errorMessage);
        }
    }

    /**
     * Override this method with your own logic if required
     * @param e The thrown exception to deal with
     */
    public virtual void onException(Exception e) {
        // Intentionally left blank
    }

    /**
     * Override this method with your own logic if required
     */
    public virtual void onFinally() {
        // Intentionally left blank
    }

    abstract public String getClassName();

    public class WorkException extends Exception {}
}

3. Platform Event Trigger Handler

The trigger deserializes and executes work items with retry logic:

trigger DoWorkTrigger on DoWork__e (after insert) {
    for (DoWork__e workItem : Trigger.new) {
        if (String.isBlank(workItem.Work__c)) continue;

        Type className = System.Type.forName(workItem.ClassName__c);
        if (className == null) {
            Logger.error('Workitem has an incorrect class name: ' + workItem.ClassName__c, workItem);
            continue;
        }

        IDoWork work;
        try {
            work = (IDoWork) JSON.deserialize(workItem.Work__c, className);
        } catch (Exception e) {
            Logger.error('Invalid JSON for work item #' + workItem.Id + ': ' + workItem.Work__c);
            continue;
        }

        try {
            work.doWork();
        } catch (Exception e) {
            if (workItem.Retries__c > 0) {
                work.publish(Integer.valueOf(workItem.Retries__c) - 1);
                Logger.info('Retrying work item ' + work.getClassName() + ' due to: ' + e.getMessage());
            } else {
                Logger.error('Failing to execute work item ' + work.getClassName() + ' due to: ' + e.getMessage());
                work.onException(e);
            }
        } finally {
            try {
                work.onFinally();
            } catch (Exception e) {
                // Ignore finally error
            }
        }
    }
    Logger.saveLog();
}

Key Components

Component	Purpose	Responsibility
IDoWork	Interface	Defines the contract for async work items
DoWorkAbstract	Abstract Base	Handles serialization and event publication
DoWork__e	Platform Event	Carries serialized work data between transactions
DoWorkTrigger	Event Handler	Deserializes and executes work items with retry

Implementation Details

Required Setup

1. Create Platform Event: DoWork__e with fields:

   • Work__c (Long Text Area, 131072 chars) - Serialized work item

   • ClassName__c (Text, 255) - Fully qualified class name

   • Retries__c (Number) - Remaining retry attempts

2. Deploy Abstract Classes: IDoWork interface and DoWorkAbstract class

3. Create Trigger: DoWorkTrigger on DoWork__e

Code Structure - Concrete Worker Example

/**
 * Async worker that sets account number from auto-number field.
 * Must run async because auto-number is only available after insert.
 */
public without sharing class AsyncAccountNumberSetter extends DoWorkAbstract {

    private final Set<Id> accountIds;

    public AsyncAccountNumberSetter(Set<Id> accountIds) {
        this.accountIds = accountIds;
    }

    public void doWork() {
        List<Account> accounts = [
            SELECT Auto_Account_Number__c, AccountNumber__c
            FROM Account
            WHERE Id IN :accountIds
            FOR UPDATE  // Obtain a record lock
        ];

        for (Account record : accounts) {
            record.AccountNumber__c = record.Auto_Account_Number__c;
        }

        // Disable triggers to prevent recursion
        fflib_SObjectDomain.getTriggerEvent(AccountTriggerHandler.class).disableAll();
        update accounts;
    }

    public override String getClassName() {
        return 'AsyncAccountNumberSetter';
    }
}

Preventing Duplicate Scheduling

When working with triggers, prevent the same async job from being scheduled multiple times in the same transaction:

public with sharing class AccountTriggerHandler extends fflib_SObjectDomain {

    // Static set to track scheduled jobs in current transaction
    private static Set<String> scheduledAsyncTasks = new Set<String>();

    private static void setAccountNumber(IAccounts accounts) {
        // Check if already scheduled
        if (scheduledAsyncTasks.contains('AsyncAccountNumberSetter')) return;

        // Schedule the async work
        new AsyncAccountNumberSetter(accounts.getRecordIds())
            .publish();

        // Mark as scheduled
        scheduledAsyncTasks.add('AsyncAccountNumberSetter');
    }
}

Configuration Requirements

• Platform Event: DoWork__e must be created with appropriate field limits

• Permissions: Users/contexts publishing events need "Publish" permission on DoWork__e

• Dependencies: Logger utility for error tracking (optional but recommended)

Best Practices

Do's

• Use FOR UPDATE in queries when updating records to prevent concurrent modification issues

• Disable triggers when performing DML to prevent recursion

• Include meaningful class names for debugging and monitoring

• Keep work items as small as possible to stay under the 131KB serialization limit

• Use static tracking sets to prevent duplicate scheduling within transactions

• Implement onException for critical workflows that need failure notification

Don'ts

• Do not serialize large object graphs (query fresh data in doWork())

• Do not rely on execution order - Platform Events may be processed out of order

• Do not store sensitive data in the event payload (it's visible in Event Monitoring)

• Do not use for operations that must complete synchronously with the user action

Considerations

Governor Limits

• Platform Events have their own limits separate from the triggering transaction

• Event payload is limited to 1MB total, but individual Long Text fields max at 131,072 characters

• Maximum 250,000 platform event allocations per 24 hours (varies by edition)

Performance Impact

• Platform Events are highly performant for async processing

• Events are published immediately, not at transaction commit

• Parallel processing of events provides horizontal scalability

Security Implications

• Event payload is stored temporarily and visible in Event Monitoring

• Use appropriate sharing settings (with sharing vs without sharing) in work classes

• Consider field-level security when updating records

Variations

Variation 1: Base Worker with Common State

For domain-specific workers, create an intermediate abstract class:

public abstract class AsyncAccountWorker extends DoWorkAbstract {
    protected final Set<Id> accountIds;

    public AsyncAccountWorker(Set<Id> accountIds, String className) {
        this.accountIds = accountIds;
        AccountTriggerHandler.scheduledAsyncTasks.add(className);
    }

    abstract public override String getClassName();
}

Variation 2: Worker with Retry Configuration

For operations that may fail transiently:

public void scheduleWithRetries() {
    new AsyncExternalSync(recordIds).publish(3);  // Allow 3 retries
}

Testing Approach

Unit Test Strategy

@IsTest
private class AsyncAccountNumberSetterTest {

    @IsTest
    static void itShouldSetAccountNumber() {
        // Disable trigger to set up test data cleanly
        fflib_SObjectDomain.getTriggerEvent(AccountTriggerHandler.class).disableAll();
        insert new AutomationBypass__c(TR_Account_Trigger_Disabled__c = true);

        // GIVEN an account without account number
        Account account = new Account(Name = 'Test');
        insert account;

        // WHEN the async worker is published and events are delivered
        System.Test.startTest();
        new AsyncAccountNumberSetter(new Set<Id>{account.Id}).publish();
        System.Test.getEventBus().deliver();  // Critical: deliver events in test
        System.Test.stopTest();

        // THEN the account number should be populated
        Account result = [SELECT AccountNumber__c FROM Account WHERE Id = :account.Id];
        System.Assert.isNotNull(result.AccountNumber__c, 'Account number should be set');
    }
}

Test Scenarios

1. Happy Path: Verify work executes successfully and updates records

2. Retry Logic: Verify retries occur on transient failures

3. Error Handling: Verify onException is called when retries are exhausted

4. Duplicate Prevention: Verify same work item is not scheduled twice

Trade-offs

Benefit	Cost
Immediate trigger completion	Eventual consistency (not real-time)
Separate governor limit context	Added complexity in testing
Built-in retry mechanism	Requires Platform Event monitoring
Prevents record locking	Cannot return values to caller
Horizontal scalability	Event ordering not guaranteed