Skip to content
Suggest a correction

Save Check Set run summaries

Guide9 min read

Keep a history of how many Checks passed and failed for each record by saving the Record Health Check Set Run Platform Event in a custom object. Record Health Check publishes one Set Run event for each record a Check Set run evaluates; a Platform Event-triggered Flow or an Apex trigger receives it and creates the history record.

For example, a nightly Batch job checks 5,000 Accounts. A Platform Event-triggered Flow saves one history record per Account with its passed, failed, skipped, unable, and system-error counts, and a report shows which Accounts got worse since the previous night.

Use the Record Health Check Result event instead when the receiving automation must know which Check failed. Use neither when the Flow or Apex code that runs the Checks can save the returned result itself.

Setup valueValue
Platform Event labelRecord Health Check Set Run
API name in your orgrhc__Record_Health_Check_Set_Run__e
Publish behaviorPublish After Commit

The fields used on this page are listed below. Every field name carries the rhc__ prefix in your org. See the Set Run field reference for every field.

FieldAPI name in your orgValue
Event IDrhc__EventId__cA different value for every event. Use it to detect a repeated event.
Run IDrhc__RunId__cThe same value for every event from one run or job.
Phaserhc__Phase__cCOMPLETED for a record. COMPLETED or FAILED for the final event of an async job.
Check Set Qualified API Namerhc__CheckSetQualifiedApiName__cThe Check Set that ran, such as Account_Data_Quality.
Record IDrhc__RecordId__cThe record that was checked. Blank on the final event of an async job.
Sourcerhc__Source__cWhat started the run, such as USER_INITIATED, FLOW, or BATCH.
Occurred Atrhc__OccurredAt__cWhen the event was created.
Eligible Check Countrhc__EligibleCheckCount__cChecks the run included.
Evaluated Check Countrhc__EvaluatedCheckCount__cResults returned for the record.
Passed Countrhc__PassedCount__cResults with status PASS.
Failed Countrhc__FailedCount__cResults with status FAIL.
Skipped Countrhc__SkippedCount__cResults with status SKIPPED.
Unable Countrhc__UnableCount__cResults with status UNABLE_TO_EVALUATE.
System Error Countrhc__SystemErrorCount__cResults with status ERROR.
Contract Versionrhc__ContractVersion__c1.0, the version of the event’s shape.

The event has no overall status, no messages, and no field values from the record.

The run starts fromSet Run events publish when
A person selecting Run or Rerun on the cardPublish User Run Event is selected on the Check Set.
A Flow actionEvent Publication is ACTIONABLE or ALL.
Apex code, or a Queueable, Batch, or Scheduled jobThe request’s Event Publication is ACTIONABLE or ALL. The Apex default is NONE.

With ACTIONABLE, a record publishes its Set Run event even when every Check passes, so a missing history record means that publication or receiving failed.

A Queueable, Batch, or Scheduled job also publishes one final Set Run event when the job ends. That event has a blank Record ID and no result counts; it reports Phase, Submitted Record Count, and Processed Record Count instead. The history Flow and Apex below skip it.

Page loads, browser refreshes, and the automatic rerun after a record save never publish. See Decide when to use Platform Events for every rule.

Create a custom object owned by your team, such as Health Check Run History (Health_Check_Run_History__c). Record Health Check does not create it, so its API names have no rhc__ prefix.

Add the fields your reports need:

History fieldAPI name used belowSuggested typeEvent field
Event IDEvent_Id__cText(80), Uniquerhc__EventId__c
Run IDRun_Id__cText(120)rhc__RunId__c
Check Set Qualified API NameCheck_Set_Api_Name__cText(80)rhc__CheckSetQualifiedApiName__c
Salesforce Record IDSalesforce_Record_Id__cText(18)rhc__RecordId__c
Occurred AtOccurred_At__cDate/Timerhc__OccurredAt__c
SourceSource__cText(30)rhc__Source__c
Overall StatusOverall_Status__cText(30) or a restricted picklistDerived from the counts
Eligible Check CountEligible_Check_Count__cNumber(5, 0)rhc__EligibleCheckCount__c
Evaluated Check CountEvaluated_Check_Count__cNumber(5, 0)rhc__EvaluatedCheckCount__c
Passed CountPassed_Count__cNumber(5, 0)rhc__PassedCount__c
Failed CountFailed_Count__cNumber(5, 0)rhc__FailedCount__c
Skipped CountSkipped_Count__cNumber(5, 0)rhc__SkippedCount__c
Unable CountUnable_Count__cNumber(5, 0)rhc__UnableCount__c
System Error CountSystem_Error_Count__cNumber(5, 0)rhc__SystemErrorCount__c
Contract VersionContract_Version__cText(10)rhc__ContractVersion__c

Mark Event ID as Unique. Run ID is not unique: one run can check many records.

Give administrators Read access to the object through a permission set your organization owns. The history names Salesforce records, so protect it as you protect those records.

The event contains counts, not an overall status. To store one, test the counts in this order and use the first that applies:

  1. ERROR when System Error Count is greater than 0.
  2. UNABLE_TO_EVALUATE when Unable Count is greater than 0.
  3. FAIL when Failed Count is greater than 0.
  4. PASS when Passed Count is greater than 0.
  5. SKIPPED otherwise.

This is the same order the Flow action uses for its Status output, so one passing Check never hides a failure or an error.

  1. In Setup, open Flows, select New Flow, and choose Platform Event—Triggered Flow.
  2. Select Record Health Check Set Run as the Platform Event.
  3. Add a Decision element. When {!$Record.rhc__RecordId__c} is null, the event is the final event of an async job; end the Flow, or route it to separate job monitoring.
  4. Add a Decision element. When {!$Record.rhc__ContractVersion__c} does not equal 1.0, the event has a shape this Flow was not built for; send it to review, such as an error notification, and end the Flow.
  5. Add a Get Records element for Health Check Run History where Event ID equals {!$Record.rhc__EventId__c}. Store only the first record.
  6. Add a Decision element. When the record from step 5 exists, end the Flow. The event was already saved.
  7. Add a Decision element named Overall status with outcomes in the order from Derive an overall status. Assign the matching value to a text variable in each outcome.
  8. Add a Create Records element that creates the history record with the fields from Create a history object and the overall status variable.
  9. Connect the Create Records fault path to your organization’s Flow error handling, such as an error notification or a monitored queue.
  10. Save the Flow, test it in a sandbox, and then activate it.

By default, Salesforce runs a Platform Event-triggered Flow as the Automated Process user. The Flow runs separately from the Checks; when it fails, the result already returned to the person, Flow, or Apex code does not change.

Use an Apex trigger when your team needs bulk processing or complex routing. Replace the history object and field names with the ones your team creates.

trigger HealthCheckRunHistoryTrigger on rhc__Record_Health_Check_Set_Run__e(
after insert
) {
HealthCheckRunHistoryHandler.saveSummaries(Trigger.new);
}
public with sharing class HealthCheckRunHistoryHandler {
public static void saveSummaries(
List<rhc__Record_Health_Check_Set_Run__e> events
) {
Set<String> eventIds = new Set<String>();
for (rhc__Record_Health_Check_Set_Run__e eventRecord : events) {
eventIds.add(eventRecord.rhc__EventId__c);
}
// Event IDs already saved by an earlier delivery.
Set<String> savedEventIds = new Set<String>();
for (Health_Check_Run_History__c saved : [
SELECT Event_Id__c
FROM Health_Check_Run_History__c
WHERE Event_Id__c IN :eventIds
]) {
savedEventIds.add(saved.Event_Id__c);
}
List<Health_Check_Run_History__c> history = new List<Health_Check_Run_History__c>();
for (rhc__Record_Health_Check_Set_Run__e eventRecord : events) {
// Skip repeated events and the final event of an async job.
if (
savedEventIds.contains(eventRecord.rhc__EventId__c) ||
String.isBlank(eventRecord.rhc__RecordId__c)
) {
continue;
}
// An unexpected event shape goes to review instead of history.
if (eventRecord.rhc__ContractVersion__c != '1.0') {
// Send eventRecord.rhc__EventId__c to your monitoring.
continue;
}
savedEventIds.add(eventRecord.rhc__EventId__c);
history.add(
new Health_Check_Run_History__c(
Event_Id__c = eventRecord.rhc__EventId__c,
Run_Id__c = eventRecord.rhc__RunId__c,
Check_Set_Api_Name__c = eventRecord.rhc__CheckSetQualifiedApiName__c,
Salesforce_Record_Id__c = eventRecord.rhc__RecordId__c,
Occurred_At__c = eventRecord.rhc__OccurredAt__c,
Source__c = eventRecord.rhc__Source__c,
Overall_Status__c = overallStatus(eventRecord),
Eligible_Check_Count__c = eventRecord.rhc__EligibleCheckCount__c,
Evaluated_Check_Count__c = eventRecord.rhc__EvaluatedCheckCount__c,
Passed_Count__c = eventRecord.rhc__PassedCount__c,
Failed_Count__c = eventRecord.rhc__FailedCount__c,
Skipped_Count__c = eventRecord.rhc__SkippedCount__c,
Unable_Count__c = eventRecord.rhc__UnableCount__c,
System_Error_Count__c = eventRecord.rhc__SystemErrorCount__c,
Contract_Version__c = eventRecord.rhc__ContractVersion__c
)
);
}
if (history.isEmpty()) {
return;
}
List<Database.SaveResult> results = Database.insert(history, false);
for (Integer i = 0; i < results.size(); i++) {
if (!results[i].isSuccess()) {
// Send history[i].Event_Id__c and results[i].getErrors() to your monitoring.
}
}
}
private static String overallStatus(
rhc__Record_Health_Check_Set_Run__e eventRecord
) {
if (isPositive(eventRecord.rhc__SystemErrorCount__c)) {
return 'ERROR';
}
if (isPositive(eventRecord.rhc__UnableCount__c)) {
return 'UNABLE_TO_EVALUATE';
}
if (isPositive(eventRecord.rhc__FailedCount__c)) {
return 'FAIL';
}
if (isPositive(eventRecord.rhc__PassedCount__c)) {
return 'PASS';
}
return 'SKIPPED';
}
private static Boolean isPositive(Decimal value) {
return value != null && value > 0;
}
}

The handler queries and saves once for the whole group of events, so it stays within Salesforce limits when many events arrive together. The Unique Event ID field stops a duplicate when two deliveries of the same event are processed at the same time; that save fails and reaches your monitoring instead of creating a second record.

Test the handler by publishing an event and delivering it:

@IsTest
private class HealthCheckRunHistoryHandlerTest {
@IsTest
static void savesOneHistoryRecordPerEvent() {
Account account = new Account(Name = 'Test Account');
insert account;
rhc__Record_Health_Check_Set_Run__e eventRecord = new rhc__Record_Health_Check_Set_Run__e(
rhc__EventId__c = 'test-event-1',
rhc__RunId__c = 'test-run-1',
rhc__Phase__c = 'COMPLETED',
rhc__CheckSetQualifiedApiName__c = 'Account_Data_Quality',
rhc__RecordId__c = account.Id,
rhc__Source__c = 'FLOW',
rhc__OccurredAt__c = System.now(),
rhc__ContractVersion__c = '1.0',
rhc__FrameworkVersion__c = '2.0.11',
rhc__PassedCount__c = 3,
rhc__FailedCount__c = 1
);
Test.startTest();
EventBus.publish(eventRecord);
Test.getEventBus().deliver();
Test.stopTest();
Health_Check_Run_History__c saved = [
SELECT Overall_Status__c
FROM Health_Check_Run_History__c
WHERE Event_Id__c = 'test-event-1'
];
Assert.areEqual('FAIL', saved.Overall_Status__c);
}
}

The Record Health Check Card User, Record Health Check User, and Record Health Check Admin permission sets grant Create and Read access to the Set Run event, so the people and automation that run Checks can publish it.

By default, Salesforce runs Platform Event triggers and Platform Event-triggered Flows as the Automated Process user. To run an Apex trigger as a specific user, configure it with Salesforce’s PlatformEventSubscriberConfig. That user then needs Read access to the event and Create access to the history object and its fields.

A Set Run event with Source USER_INITIATED comes from the record-page card. The browser reports the results it evaluated, and Salesforce publishes them without evaluating the Checks again. Treat these events as notifications. Before a decision that affects security, compliance, or money, run the Check Set again from Apex or Flow.

Test each of these cases in a sandbox:

  1. Each overall status, ERROR, UNABLE_TO_EVALUATE, FAIL, PASS, and SKIPPED, is saved correctly.
  2. The same Event ID received twice creates one history record.
  3. Two events with the same Run ID and different Event IDs are both saved.
  4. The final event of a Batch job, which has a blank Record ID, does not create a history record.
  5. An event with a Contract Version other than 1.0 goes to review.
  6. A failed save reaches your monitoring.
  7. Users without access to the history object cannot read it.