Save or route individual Check results
Save the result of each Check, or start follow-up work when a specific Check fails, by receiving the Record Health Check Result Platform Event. Record Health Check publishes one Result event for each Check result it is asked to publish; a Platform Event-triggered Flow or an Apex trigger receives it and saves or routes it.
For example, when the Billing_City_Is_Populated Check returns FAIL for an Account, a Flow
creates a Task for the Account owner to add the billing city.
Result events can be numerous: with ALL, a run publishes one event per Check per record. When
the receiving automation needs only counts, use the
Record Health Check Set Run event instead.
What the event contains
Section titled “What the event contains”| Setup value | Value |
|---|---|
| Platform Event label | Record Health Check Result |
| API name in your org | rhc_ |
| Publish behavior | Publish After Commit |
Every field name carries the rhc__ prefix in your org. See the
Result 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. |
| Check Set Qualified API Name | rhc_ | The Check Set the Check belongs to. |
| Check Qualified API Name | rhc_ | The Check, such as Billing_ or rhc_. |
| Record ID | rhc_ | The record that was checked. |
| Status | rhc_ | PASS, FAIL, SKIPPED, UNABLE_, or ERROR. |
| Severity | rhc_ | The Check’s Failure Severity, CRITICAL, WARNING, or INFO, when Status is FAIL. |
| Reason Code | rhc_ | A stable code that explains the result. See Reason codes. |
| Source | rhc_ | What started the run, such as USER_, FLOW, or BATCH. |
| Occurred At | rhc_ | When the event was created. |
| Contract Version | rhc_ | 1., the version of the event’s shape. |
| Contains Restricted Detail | rhc_ | Always false in contract version 1.. |
The event contains no messages, Found or Expected values, formulas, queries, or field values. Route on Status, Reason Code, Severity, and Check Qualified API Name, never on the text the card shows, which an administrator can change.
Turn on publication
Section titled “Turn on publication”| The run starts from | Result events publish |
|---|---|
| A person selecting Run or Rerun on the card | For each Check with Publish User Result Event selected, one event for its result, whatever the status. |
| A Flow action, Apex code, or an async job | With ACTIONABLE, one event for each FAIL, UNABLE_, or ERROR result. With ALL, one event for every result. With NONE, nothing. |
Page loads, browser refreshes, and the automatic rerun after a record save never publish. See Decide when to use Platform Events for every rule.
On the card, select Publish User Result Event only on the Checks the receiving automation needs. Each selected Check publishes an event every time a person selects Run or Rerun.
Create a history object
Section titled “Create a history object”Create a custom object owned by your team, such as Health Check Result History
(Health_Check_Result_History__c). Record Health Check does not create it, so its API names have
no rhc__ prefix.
| History field | API name used below | Suggested type | Event field |
|---|---|---|---|
| Event ID | Event_ | Text(80), Unique | rhc_ |
| Run ID | Run_ | Text(120) | rhc_ |
| Salesforce Record ID | Salesforce_ | Text(18) | rhc_ |
| Check Set Qualified API Name | Check_ | Text(80) | rhc_ |
| Check Qualified API Name | Check_ | Text(80) | rhc_ |
| Status | Status_ | Text(30) or a restricted picklist | rhc_ |
| Severity | Severity_ | Text(20) | rhc_ |
| Reason Code | Reason_ | Text(80) | rhc_ |
| Source | Source_ | Text(30) | rhc_ |
| Occurred At | Occurred_ | Date/Time | rhc_ |
| Contract Version | Contract_ | Text(10) | rhc_ |
Mark Event ID as Unique. Run ID is not unique: one run publishes many events.
Save or route results with Flow
Section titled “Save or route results with Flow”- In Setup, open Flows, select New Flow, and choose Platform Event—Triggered Flow.
- Select Record Health Check Result as the Platform Event.
- 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 Result History where Event ID equals
{!$Record.rhc__EventId__c}. Store only the first record. - Add a Decision element. When the record from step 4 exists, end the Flow. The event was already handled.
- Add a Create Records element that saves the history record with the fields from Create a history object.
- Add a Decision element with an outcome for each case the Flow handles. For the example on
this page, add an outcome where
{!$Record.rhc__CheckQualifiedApiName__c}equalsBilling_City_Is_Populatedand{!$Record.rhc__Status__c}equalsFAIL. Events that match no outcome follow the default outcome, which ends the Flow after the history record is saved. - On that outcome, add a Get Records element for the Account whose Account ID equals
{!$Record.rhc__RecordId__c}, and then a Create Records element that creates a Task with Assigned To ID set to the Account’s Owner ID, Related To ID set to{!$Record.rhc__RecordId__c}, and Subject set toAdd the billing city. - Connect each Create Records fault path to your organization’s Flow error handling.
- Save the Flow, test it in a sandbox, and then activate it.
Saving the history record before creating the Task means that a repeated event finds the saved Event ID in step 5 and does not create a second Task.
Handle FAIL, UNABLE_TO_EVALUATE, and ERROR separately. A FAIL asks a business user to fix
the record; UNABLE_TO_EVALUATE usually needs an administrator to fix access or configuration; and
ERROR needs technical investigation.
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 does not change.
Save results with Apex
Section titled “Save results with Apex”Use an Apex trigger when your team needs bulk processing or complex routing. This example saves
only FAIL, UNABLE_TO_EVALUATE, and ERROR results. Replace the history object and field names
with the ones your team creates.
trigger HealthCheckResultHistoryTrigger on rhc__Record_Health_Check_Result__e( after insert) { HealthCheckResultHistoryHandler.saveActionableResults(Trigger.new);}public with sharing class HealthCheckResultHistoryHandler { private static final Set<String> ACTIONABLE = new Set<String>{ 'FAIL', 'UNABLE_TO_EVALUATE', 'ERROR' };
public static void saveActionableResults( List<rhc__Record_Health_Check_Result__e> events ) { Set<String> eventIds = new Set<String>(); for (rhc__Record_Health_Check_Result__e eventRecord : events) { if (ACTIONABLE.contains(eventRecord.rhc__Status__c)) { eventIds.add(eventRecord.rhc__EventId__c); } } if (eventIds.isEmpty()) { return; }
// Event IDs already saved by an earlier delivery. Set<String> savedEventIds = new Set<String>(); for (Health_Check_Result_History__c saved : [ SELECT Event_Id__c FROM Health_Check_Result_History__c WHERE Event_Id__c IN :eventIds ]) { savedEventIds.add(saved.Event_Id__c); }
List<Health_Check_Result_History__c> history = new List<Health_Check_Result_History__c>(); for (rhc__Record_Health_Check_Result__e eventRecord : events) { if ( !eventIds.contains(eventRecord.rhc__EventId__c) || savedEventIds.contains(eventRecord.rhc__EventId__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_Result_History__c( Event_Id__c = eventRecord.rhc__EventId__c, Run_Id__c = eventRecord.rhc__RunId__c, Salesforce_Record_Id__c = eventRecord.rhc__RecordId__c, Check_Set_Api_Name__c = eventRecord.rhc__CheckSetQualifiedApiName__c, Check_Api_Name__c = eventRecord.rhc__CheckQualifiedApiName__c, Status__c = eventRecord.rhc__Status__c, Severity__c = eventRecord.rhc__Severity__c, Reason_Code__c = eventRecord.rhc__ReasonCode__c, Source__c = eventRecord.rhc__Source__c, Occurred_At__c = eventRecord.rhc__OccurredAt__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. } } }}The handler queries and saves once for the whole group of events. The Unique Event ID field stops a duplicate when two deliveries of the same event are processed at the same time.
To test it, publish an rhc__Record_Health_Check_Result__e event with every required field set,
call Test.getEventBus().deliver(), and then query the history object. The required fields are
Event ID, Run ID, Check Set Qualified API Name, Check Qualified API Name, Status, Source, Occurred
At, Contract Version, and Framework Version.
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 Result 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, Create access to
the history object, and access to any records the automation reads or creates.
The history names Salesforce records, so protect it as you protect those records.
Card events are reported by the browser
Section titled “Card events are reported by the browser”A Result event with Source USER_INITIATED comes from the record-page card. The browser
reports the status it evaluated, and Salesforce publishes it without evaluating the Check again.
Treat these events as notifications. Before a change that affects security, compliance, or money,
run the Check again from Apex or Flow.
Test before activation
Section titled “Test before activation”Test each of these cases in a sandbox:
- Each status the automation handles follows the expected path.
- With
ACTIONABLE, no event arrives forPASSorSKIPPED; withALL, one does. - The same Event ID received twice creates one history record and one Task.
- A Contract Version other than
1.0goes to review, and a Reason Code that no outcome names follows the default outcome. - A failed save reaches your monitoring.
- Users without access to the history object cannot read it.