Skip to content
Suggest a correction

Run Record Health Check from Scheduled Apex

Guide7 min read

Run Record Health Check automatically at a recurring time, such as every night at 2:00 AM, with Scheduled Apex. The scheduled class starts a Batch job, which checks the records in groups.

Record Health Check provides rhc.RecordHealthCheckScheduled.scheduleDaily, which schedules a fixed list of up to 2,000 record IDs every day. To check records that a query finds each time, write your own Schedulable class that starts your own Batch. Both are created from Apex code: the packaged class needs a Check Set and record IDs, so the Schedule Apex page in Setup cannot start it.

ExampleUseWhy
The same 400 Account IDs must run every dayPackaged daily schedulerThe IDs are known and intentionally stay the same.
Every night, check all Accounts modified in the last 30 daysCustom scheduler that starts a query-backed BatchThe matching Accounts change, so the Batch must query them each night.

The packaged schedule captures record IDs when the schedule is created. Records added later are not included, and removed IDs are not automatically replaced. This behavior is correct only when the list of records is intentionally fixed.

Also decide where results go:

Scheduled workResult choices
Packaged daily schedulerPublish ACTIONABLE or ALL Platform Events, or use NONE when only job completion matters.
Custom scheduler that starts a custom BatchSave response.results directly, publish Platform Events, or retain no individual results.
  1. Decide whether every run uses the same record IDs or queries the records again.
  2. Assign the scheduling user the packaged Record Health Check User Permission Set. Use Record Health Check Admin only when the user also configures Checks or views diagnostics. Both include Custom Permission label: Record Health Check Run, Custom Permission API name: rhc__Record_Health_Check_Run, and the required Apex class access.
  3. Confirm that the scheduling user has the object, record, field, and Custom Metadata access the selected Checks require.
  4. Find the Check Set’s exact Qualified API Name, as described in Names and API identities.
  5. Choose a result destination from the table above. Prepare the custom result object or Platform Event receiver before creating the schedule.
  6. Choose a stable, unique scheduled-job name.

The scheduling user’s time zone controls the start time. Verify that user’s Salesforce time zone before enabling a production schedule.

Example: Schedule the same record IDs every day

Section titled “Example: Schedule the same record IDs every day”

Schedule the same known IDs to run daily at 2:00 AM in the scheduling user’s time zone:

// Use the Check Set's exact Qualified API Name.
// A Check Set included with the installed package might be rhc__Example_Account_Check_Builder_Guide.
String checkSetApiName = 'My_Account_Checks';
String scheduledJobId = rhc.RecordHealthCheckScheduled.scheduleDaily(
'Nightly Account Health',
checkSetApiName,
accountIds,
// Use ACTIONABLE to publish only FAIL, UNABLE_TO_EVALUATE, and ERROR.
// Use ALL to publish every result, including PASS and SKIPPED.
// Use NONE only when scheduled-job and Batch-job completion are enough.
rhc.RecordHealthCheckEventPublication.ACTIONABLE
);

The packaged scheduling class accepts:

  • a job name containing 1–80 characters;
  • a Check Set Qualified API Name;
  • 1–2,000 distinct, non-null record IDs;
  • every remaining ID belongs to the selected Check Set object, or scheduling is rejected; and
  • an explicit event-publication mode.

Invalid input or missing permission is rejected before Salesforce creates a CronTrigger:

Exception messageCause and fix
A schedule name of 1–80 characters is required.Shorten or supply the job name.
Starts with Scheduled population must contain 1–2000 IDsSupply 1–2,000 IDs after nulls and repeats are removed.
Contains outside the selected Check Set objectRemove IDs of other objects.
Contains was not found, is inactive, or has no configured objectCorrect the Qualified API Name, activate the Check Set, or set its Object.
Contains cannot evaluate one record inside the FormulaEval budgetThe Check Set’s formulas need more than 95 formula evaluations for one record. Reduce the Formula Checks.
Starts with NOT_AUTHORIZED:The user lacks the Record Health Check Run Custom Permission.
Salesforce reports that a job with this name is already scheduledAnother schedule uses the name. Delete or reuse it, as described in Change or stop the schedule.

Authorization is checked again when the schedule fires. Each firing starts the packaged Batch class, which repeats the Check Set and formula checks before it starts. If the Check Set was deactivated after scheduling, or its formulas no longer fit, that firing fails and starts no Batch.

The returned scheduledJobId identifies the recurring schedule, not the Batch job started each day. Monitor each Batch separately in Setup → Apex Jobs. Passing NONE creates no health-result destination, so use it only when job completion is sufficient.

With ACTIONABLE or ALL, each day’s events have Source SCHEDULED and the Run ID batch- followed by that day’s Batch job ID. Each Batch also publishes one final Set Run event, with Phase COMPLETED or FAILED, when it ends. See Check many records with Batch Apex.

The packaged daily schedule automatically checks 1–100 records in each Batch transaction, reducing the scope when required by the FormulaEval budget. The scheduled API does not accept an explicit Batch size. To choose one, create a custom scheduler that calls rhc.RecordHealthCheckBatch.run(..., scopeSize).

The record IDs, Check Set, and Event Publication value are saved with the schedule and cannot be edited. To change any of them:

  1. Open Setup → Scheduled Jobs.
  2. Find the job by its exact name, confirm its owner and next run, and select Del.
  3. Call scheduleDaily again with the same job name and the new values.

To stop the schedule from Apex, call System.abortJob(scheduledJobId) with the ID that scheduleDaily returned.

Example: Query the current records every time the schedule runs

Section titled “Example: Query the current records every time the schedule runs”

First create the complete AccountHealthBatch described in Batch Apex. That example uses NONE and saves response.results directly. Then create a small scheduler whose only job is to start that Batch:

public with sharing class NightlyAccountHealthSchedule implements Schedulable {
public void execute(SchedulableContext context) {
// Use the Check Set's exact Qualified API Name.
String checkSetApiName = 'My_Account_Checks';
// AccountHealthBatch queries current Accounts, publishes no result
// events, and saves its response.results directly.
Database.executeBatch(new AccountHealthBatch(checkSetApiName), 25);
}
}

Schedule the custom class from Setup:

  1. In Setup, enter Apex Classes in Quick Find and select Apex Classes.
  2. Select Schedule Apex.
  3. Enter a job name, such as Nightly Account Health.
  4. Select NightlyAccountHealthSchedule as the Apex class.
  5. Choose the frequency, start date, end date, and preferred start time.
  6. Select Save.
  7. Open Setup → Scheduled Jobs and confirm that the schedule appears.

The same schedule can be created from Apex:

String scheduledJobId = System.schedule(
'Nightly Account Health',
'0 0 2 * * ?',
new NightlyAccountHealthSchedule()
);

The value '0 0 2 * * ?' is Salesforce’s scheduling expression for every day at 2:00 AM in the scheduling user’s time zone.

A scheduled run has three different IDs:

IDWhat it tracks
CronTrigger IDThe recurring schedule
AsyncApexJob IDThe Batch or Queueable job started by one firing
Record Health Check runIdThe health-check results created by one run

Save these IDs together only when staff must follow one run from its schedule to its health results. Check these failures separately:

  • the schedule did not fire or could not start the Batch or Queueable job;
  • the Batch or Queueable job failed;
  • Record Health Check returned ERROR or UNABLE_TO_EVALUATE; or
  • the Flow, Apex trigger, or integration receiving Platform Events failed to process one.

Use one stable job name for one logical schedule. A random or timestamped name can create duplicate schedules and consume scheduled-job capacity. When a request changes, deliberately abort or replace the known schedule.

Schedule the class between Test.startTest() and Test.stopTest(). Assert that it starts the expected Batch or Queueable job or saves the expected result. Keep scheduler tests separate from detailed health-result and Batch-group tests.

Before production activation, verify the schedule in a sandbox as the real scheduling user or with equivalent access.

SymptomCheck first
No CronTrigger is createdCustom Permission, job-name length, Check Set Qualified API Name, and record-ID count
The schedule exists but no Batch startsThe scheduling user’s current access, whether the Check Set is still active, and the latest Scheduled Apex failure
Batch completes but no outcomes are retainedEvent-publication mode and the Flow, Apex trigger, integration, or storage that should receive them
The same records run every dayExpected for the packaged scheduling class; use a query-backed Batch to query the records again
The job runs at the wrong local timeThe scheduling user’s Salesforce time zone and CRON expression
Duplicate schedules consume slotsReuse one stable name and replace the known schedule deliberately