Firing Platform Events from Batch Apex

Batch Apex classes can fire platform events when encountering an error or exception. Clients listening on an event can obtain actionable information, such as how often the event failed and which records were in scope at the time of failure. Events are also fired for Salesforce Platform internal errors and other uncatchable Apex exceptions such as LimitExceptions, which are caused by reaching governor limits.

An event message provides more granular error tracking than the Apex Jobs UI. It includes the record IDs being processed, exception type, exception message, and stack trace. You can also incorporate custom handling and retry logic for failures. You can invoke custom Apex logic from any trigger on this type of event, so Apex developers can build functionality like custom logging or automated retry handling.

For information on subscribing to platform events, see Subscribing to Platform Events.

The BatchApexErrorEvent object represents a platform event associated with a batch Apex class. This object is available in API version 44.0 and later. If the start, execute, or finish method of a batch Apex job encounters an unhandled exception, a BatchApexErrorEvent platform event is fired. For more details, see BatchApexErrorEvent.

To fire a platform event, a batch Apex class declaration must implement the Database.RaisesPlatformEvents interface.

1public with sharing class YourSampleBatchJob implements Database.Batchable<SObject>, 
2   Database.RaisesPlatformEvents{ 
3   // class implementation 
4}

Example

This example creates a trigger to determine which accounts failed in the batch transaction. Custom field Dirty__c indicates that the account was one of a failing batch and ExceptionType__c indicates the exception that was encountered. JobScope and ExceptionType are fields in the BatchApexErrorEvent object.

1trigger MarkDirtyIfFail on BatchApexErrorEvent (after insert) {
2    Set<Id> asyncApexJobIds = new Set<Id>();
3    for(BatchApexErrorEvent evt:Trigger.new){
4        asyncApexJobIds.add(evt.AsyncApexJobId);
5    }
6    
7    Map<Id,AsyncApexJob> jobs = new Map<Id,AsyncApexJob>(
8        [SELECT id, ApexClass.Name FROM AsyncApexJob WHERE Id IN :asyncApexJobIds]
9    );
10    
11    List<Account> records = new List<Account>();
12    for(BatchApexErrorEvent evt:Trigger.new){
13        //only handle events for the job(s) we care about
14        if(jobs.get(evt.AsyncApexJobId).ApexClass.Name == 'AccountUpdaterJob'){
15            for (String item : evt.JobScope.split(',')) {
16                Account a = new Account(
17                    Id = (Id)item,
18                    ExceptionType__c = evt.ExceptionType,
19                    Dirty__c = true
20                );
21                records.add(a);
22            }
23        }
24    }
25    update records;
26}

Apex Developer Guide

Firing Platform Events from Batch Apex

Example