Save Check Set run summaries
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.
What the event contains
Section titled “What the event contains”| Setup value | Value |
|---|---|
| Platform Event label | Record Health Check Set Run |
| API name in your org | rhc_ |
| Publish behavior | Publish 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.
| Field | API name in your org | Value |
|---|---|---|
| Event ID | rhc_ | A different value for every event. Use it to detect a repeated event. |
| Run ID | rhc_ | The same value for every event from one run or job. |
| Phase | rhc_ | COMPLETED for a record. COMPLETED or FAILED for the final event of an async job. |
| Check Set Qualified API Name | rhc_ | The Check Set that ran, such as Account_. |
| Record ID | rhc_ | The record that was checked. Blank on the final event of an async job. |
| Source | rhc_ | What started the run, such as USER_, FLOW, or BATCH. |
| Occurred At | rhc_ | When the event was created. |
| Eligible Check Count | rhc_ | Checks the run included. |
| Evaluated Check Count | rhc_ | Results returned for the record. |
| Passed Count | rhc_ | Results with status PASS. |
| Failed Count | rhc_ | Results with status FAIL. |
| Skipped Count | rhc_ | Results with status SKIPPED. |
| Unable Count | rhc_ | Results with status UNABLE_. |
| System Error Count | rhc_ | Results with status ERROR. |
| Contract Version | rhc_ | 1., the version of the event’s shape. |
The event has no overall status, no messages, and no field values from the record.
Turn on publication
Section titled “Turn on publication”| The run starts from | Set Run events publish when |
|---|---|
| A person selecting Run or Rerun on the card | Publish User Run Event is selected on the Check Set. |
| A Flow action | Event Publication is ACTIONABLE or ALL. |
| Apex code, or a Queueable, Batch, or Scheduled job | The 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 history object
Section titled “Create a history object”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 field | API name used below | Suggested type | Event field |
|---|---|---|---|
| Event ID | Event_ | Text(80), Unique | rhc_ |
| Run ID | Run_ | Text(120) | rhc_ |
| Check Set Qualified API Name | Check_ | Text(80) | rhc_ |
| Salesforce Record ID | Salesforce_ | Text(18) | rhc_ |
| Occurred At | Occurred_ | Date/Time | rhc_ |
| Source | Source_ | Text(30) | rhc_ |
| Overall Status | Overall_ | Text(30) or a restricted picklist | Derived from the counts |
| Eligible Check Count | Eligible_ | Number(5, 0) | rhc_ |
| Evaluated Check Count | Evaluated_ | Number(5, 0) | rhc_ |
| Passed Count | Passed_ | Number(5, 0) | rhc_ |
| Failed Count | Failed_ | Number(5, 0) | rhc_ |
| Skipped Count | Skipped_ | Number(5, 0) | rhc_ |
| Unable Count | Unable_ | Number(5, 0) | rhc_ |
| System Error Count | System_ | Number(5, 0) | rhc_ |
| Contract Version | Contract_ | Text(10) | rhc_ |
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.
Derive an overall status
Section titled “Derive an overall status”The event contains counts, not an overall status. To store one, test the counts in this order and use the first that applies:
ERRORwhen System Error Count is greater than 0.UNABLE_TO_EVALUATEwhen Unable Count is greater than 0.FAILwhen Failed Count is greater than 0.PASSwhen Passed Count is greater than 0.SKIPPEDotherwise.
This is the same order the Flow action uses for its Status output, so one passing Check never hides a failure or an error.
Save summaries with Flow
Section titled “Save summaries with Flow”- In Setup, open Flows, select New Flow, and choose Platform Event—Triggered Flow.
- Select Record Health Check Set Run as the Platform Event.
- 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. - Add a Decision element. When
{!$Record.rhc__ContractVersion__c}does not equal1.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. - Add a Get Records element for Health Check Run History where Event ID equals
{!$Record.rhc__EventId__c}. Store only the first record. - Add a Decision element. When the record from step 5 exists, end the Flow. The event was already saved.
- 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.
- Add a Create Records element that creates the history record with the fields from Create a history object and the overall status variable.
- Connect the Create Records fault path to your organization’s Flow error handling, such as an error notification or a monitored queue.
- 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.
Save summaries with Apex
Section titled “Save summaries with Apex”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:
@IsTestprivate 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); }}Access
Section titled “Access”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.
Card events are reported by the browser
Section titled “Card events are reported by the browser”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 before activation
Section titled “Test before activation”Test each of these cases in a sandbox:
- Each overall status,
ERROR,UNABLE_TO_EVALUATE,FAIL,PASS, andSKIPPED, is saved correctly. - The same Event ID received twice creates one history record.
- Two events with the same Run ID and different Event IDs are both saved.
- The final event of a Batch job, which has a blank Record ID, does not create a history record.
- An event with a Contract Version other than
1.0goes to review. - A failed save reaches your monitoring.
- Users without access to the history object cannot read it.