Apex Developer Guide

Apex Developer Guide
Getting Started with Apex
Writing Apex
Running Apex
Invoking Apex
Anonymous Blocks
Triggers
Asynchronous Apex
Queueable Apex
Transaction Finalizers (Pilot)
Apex Scheduler
Batch Apex
Future Methods
Exposing Apex Methods as SOAP Web Services
Exposing Apex Classes as REST Web Services
Apex Email Service
Using the InboundEmail Object
Visualforce Classes
JavaScript Remoting
Apex in AJAX
Apex Transactions and Governor Limits
Using Salesforce Features with Apex
Integration and Apex Utilities
Debugging, Testing, and Deploying Apex
Apex Language Reference
Appendices
Glossary
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Transaction Finalizers (Pilot)

The Transaction Finalizers feature enables you to attach actions, using the System.Finalizer interface, to asynchronous Apex jobs that use the Queueable framework. A specific use case is to design recovery actions when a queueable job fails.

The TransactionFinalizers feature is available as a pilot program only in scratch orgs that have enabled the feature during org creation. The functionality of this feature is subject to change, and is not available for production organizations while in pilot. Pilot programs are subject to change. This feature isn’t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. We can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features. You can provide feedback and suggestions for this feature in the TransactionFinalizers group in the Trailblazer Community.

Note

Because finalizers are currently in pilot and are available only in scratch orgs that have enabled the feature, do not attempt to package finalizers.

Note

Before Transaction Finalizers, there was no direct way for you to specify actions to be taken when asynchronous jobs succeeded or failed. You could only poll the status of AsyncApexJob using a SOQL query, and re-enqueue the job if it failed. With transaction finalizers, you can attach a post-action sequence to a queueable job and take relevant actions based on the job execution result.

System.Finalizer Interface

The System.Finalizer interface includes the execute method:
This method is called on the provided FinalizerContext instance for every enqueued job with a finalizer attached. Within the execute method, you can define the actions to be taken at the end of the queueable job. An instance of System.FinalizerContext injected by the Apex runtime engine as an argument to the execute method.

System.FinalizerContext Interface

The System.FinalizerContext interface contains four methods.
  • getAsyncApexJobId method:
    Returns the ID of the queueable job for which this finalizer is defined.
  • getRequestId method:
    Returns the request ID, a string that uniquely identifies the request, and can be correlated with Event Monitoring logs. To correlate with the AsyncApexJob table, use the getAsyncApexJobId method instead. The Queueable job and the Finalizer execution both share the (same) request ID.
  • getResult method:
    Returns the System.ParentJobResult enum, which represents the  result of the parent asynchronous Apex queueable job to which the finalizer is attached. The enum takes these values: SUCCESS, UNHANDLED_EXCEPTION.
  • getException method:
    Returns the exception with which the queueable job failed when getResult is UNHANDLED_EXCEPTION, null otherwise.
To attach actions to your queueable jobs, implement the FinalizerContext interface as follows.
  1. Define a class that implements the System.FinalizerContext interface.
  2. Attach a finalizer within a queueable job’s execute method. To attach the finalizer, invoke the System.attachFinalizer method, using as argument the instantiated class that implements the System.FinalizerContext interface.

Only one finalizer instance can be attached to any queueable job. You can enqueue a single asynchronous Apex job (queueable, future, or batch) in the finalizer’s implementation of the execute method. Callouts are allowed in finalizer implementations.

Note

Example