Replace a Future method with Queueable Apex
Move existing Apex code that runs Record Health Check in an @future method to Queueable Apex,
without changing which Checks run or how their results are used. Queueable Apex returns a job ID,
accepts typed state, and supports a Finalizer for failures. Write new background work as Queueable
or Batch Apex, not as a future method.
Why replace the future method
Section titled “Why replace the future method”Queueable Apex makes background work easier to monitor and maintain:
| Capability | Future method | Queueable Apex |
|---|---|---|
| Returned Apex job ID | No | Yes |
| Typed constructor state | Limited to future-method parameter types | Yes |
| Finalizer for uncaught failure handling | No | Yes |
| Supported pattern for new Record Health Check work | No | Yes |
This change affects how work is submitted and monitored. It should not change the meaning of the Check, the records evaluated, or the handling of business results.
Example: Replace an Account import future method
Section titled “Example: Replace an Account import future method”An existing @future method receives Account IDs after an import and runs a Check Set. Replace it
with a Queueable that accepts the same IDs. The import caller now receives an Apex job ID, and a
Finalizer reports an uncaught job failure. The selected Check Set and result handling stay the same.
The caller changes from a future-method call that returns no job ID:
LegacyAccountHealth.checkAccounts(accountIds);to a Queueable submission that returns an Apex job ID:
// Use the Check Set's exact Qualified API Name.String checkSetApiName = 'My_Account_Checks';
Id jobId = System.enqueueJob( new AccountHealthQueueable( checkSetApiName, new List<Id>(accountIds) ));AccountHealthQueueable is the complete custom class in the Queueable Apex
example. The returned jobId identifies
the replacement job in Setup → Apex Jobs. It does not contain the health results.
Before you change the code
Section titled “Before you change the code”Document the existing behavior:
- Find every caller of the future method.
- Record which Check or Check Set it runs and how record IDs are collected.
- Confirm the maximum number of records passed by each caller.
- Identify the user context and required permission sets.
- Identify where
PASS,FAIL,UNABLE_TO_EVALUATE, andERRORresults go today. - Identify how an uncaught background-job failure is reported.
- Confirm whether any caller depends on undocumented behavior.
Do not pass credentials, record contents, or other sensitive values into the replacement job. Pass the Check or Check Set Qualified API Name, record IDs within the documented limit, and approved text used to connect the job with its results.
Quick start: Replace the caller
Section titled “Quick start: Replace the caller”- Implement the custom Queueable example, including its Finalizer.
- Set the execution origin to
rhc.RecordHealthCheckExecutionOrigin.QUEUEABLE. - Keep each job within 200 records and within the 95 Salesforce formula evaluations one transaction allows. Each Formula Check uses one evaluation per record, and an Applies To formula uses another, so a Check Set with one Formula Check fits at most 95 records.
- Update one caller to enqueue the Queueable class.
- Save or send the returned
AsyncApexJobID when staff must find the job later. - Verify both returned health outcomes and the Finalizer’s uncaught-failure path.
- Migrate the remaining callers.
- Remove the future method only after a code search confirms that nothing references it.
What to test in a sandbox
Section titled “What to test in a sandbox”Run the replacement as the user who starts the real job, or with equivalent access. Test:
- a
PASSresult; - a business
FAILresult; - an
UNABLE_TO_EVALUATEresult; - an invalid request that fails before or during execution;
- an uncaught Queueable exception observed by the Finalizer;
- duplicate submission behavior, if callers can retry.
Open Setup → Apex Jobs and confirm that the Queueable job appears. If the design retains health
results, confirm that staff can use the saved Record Health Check runId to find the matching Apex
job ID.
Queueable Apex does not grant extra access. Assign the actual running user the packaged Record Health Check User Permission Set, or Record Health Check Admin if that user also configures Checks or views diagnostics. Then confirm the user’s access to the business objects, records, and fields used by the selected Checks.
If migration needs more than one release
Section titled “If migration needs more than one release”Keep the future method only as temporary code that starts the Queueable implementation. Do not add evaluation logic, queries, or result-saving code to it. Prevent new callers from using it and track each remaining caller until the method can be removed.
While a future method still calls rhc.RecordHealthCheck.evaluate directly, set
withExecutionOrigin(rhc.RecordHealthCheckExecutionOrigin.FUTURE) on its request, so the Source
of any events it publishes is FUTURE and the remaining callers are easy to find.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Check first |
|---|---|
| No job ID is returned | Submission validation, authorization, and whether the caller caught an exception |
| The job appears in Apex Jobs but no result is retained | The Queueable result destination and event-publication mode |
| The job fails only for the real user | That user’s Custom Permission, Apex class, object, record, field, and metadata access |
| Duplicate jobs are submitted | The caller’s retry handling. System. accepts a duplicate unless the caller passes AsyncOptions with a DuplicateSignature |
| The old method cannot be removed | Search Apex, Flow, integrations, and tests for remaining references |