Save or route restricted errors
Keep a record of the technical errors Record Health Check encounters, so support staff can investigate them after Salesforce debug logs are gone, by receiving the Record Health Check Log Platform Event. When a Check Set allows it, Record Health Check publishes one Log event for each error it captures; a restricted Platform Event-triggered Flow or Apex trigger saves it.
Log events can contain record IDs, user IDs, error messages, and stack traces. Use them only for
technical support. Business automation that reacts to FAIL, UNABLE_TO_EVALUATE, or ERROR
results should use the Record Health Check Result event, which
contains no technical details.
What the event contains
Section titled “What the event contains”| Setup value | Value |
|---|---|
| Platform Event label | Record Health Check Log |
| API name in your org | rhc_ |
| Publish behavior | Publish Immediately |
Every field name carries the rhc__ prefix in your org. See the
Log 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 run in which the error happened. |
| Level | rhc_ | ERROR. |
| Code | rhc_ | A short classification of the error, such as BATCH_. |
| Check Set Developer Name | rhc_ | The Check Set that was running, when known. |
| Check Developer Name | rhc_ | The Check that was running, when known. |
| Record ID | rhc_ | The record being checked, when known. |
| User ID | rhc_ | The user who ran the Checks. |
| Exception Type | rhc_ | The Apex exception type, when an exception caused the error. |
| Message | rhc_ | The exception message and error details, up to 4,000 characters. |
| Structured Diagnostic Details | rhc_ | The same details as JSON, up to 4,000 characters. |
| Stack Trace | rhc_ | The Apex stack trace, up to 32,000 characters. |
| Occurred At | rhc_ | When the error was captured. |
| Contract Version | rhc_ | 1., the version of the event’s shape. |
Codes lists every Code in this release and what each one means. Codes can change between releases. Use them to group errors, and send any Code the automation does not recognize to review rather than failing.
Turn on publication
Section titled “Turn on publication”Log publication is off by default. Two settings are needed, and both are independent of the card publication checkboxes and of Event Publication:
- In Setup, open Custom Metadata Types → Record Health Check Set → Manage Records, edit the Check Set, and select Publish Error Log Event.
- Assign the Record Health Check Error Log Publisher permission set to each user who runs that
Check Set, including the users who start Flows and the users who run async jobs. When
Salesforce rejects a Log event, the debug log shows
LOG_EVENT_PUBLISH_FAILEDorLOG_EVENT_FLUSH_FAILED, and the Check result does not change.
The permission set grants Create and Read access to the Log event. Salesforce requires Read with Create, so every assignee can read restricted error details; assign it only to users trusted with them.
When the setting is selected, every error Record Health Check captures while running that Check Set publishes a Log event, whether the card, a Flow, Apex code, or an async job started the run. Clearing the setting does not affect Salesforce debug logs, which still record the same errors while debug logging is on.
Every Unable to Check and System Error result counts as an error and can publish a Log event
with Code DIAGNOSTIC_INCIDENT. Estimate the volume before you select the setting on a Check
Set that runs for many records.
Decide what to keep
Section titled “Decide what to keep”Before you build receiving automation, agree on:
- who can read the event, the saved errors, and the reports on them;
- which fields to save; for counts and trends, Code and the developer names are enough;
- how long saved errors are kept; and
- which destinations must never receive messages or stack traces, such as broad email lists or chat channels.
Create a protected object
Section titled “Create a protected object”Create a custom object owned by your team, such as Record Health Check Error
(Record_Health_Check_Error__c). Record Health Check does not create it. Make it Private, and
give access only to support staff through a permission set your organization owns.
| Error field | API name used below | Suggested type | Event field |
|---|---|---|---|
| Event ID | Event_ | Text(80), Unique | rhc_ |
| Run ID | Run_ | Text(120) | rhc_ |
| Occurred At | Occurred_ | Date/Time | rhc_ |
| Code | Code_ | Text(120) | rhc_ |
| Check Set Developer Name | Check_ | Text(120) | rhc_ |
| Check Developer Name | Check_ | Text(120) | rhc_ |
| Salesforce Record ID | Salesforce_ | Text(18) | rhc_ |
| User ID | User_ | Text(18) | rhc_ |
| Exception Type | Exception_ | Text(120) | rhc_ |
| Message | Message_ | Long Text Area(32768) | rhc_ |
| Stack Trace | Stack_ | Long Text Area(32768) | rhc_ |
| Contract Version | Contract_ | Text(10) | rhc_ |
Message and Stack Trace are optional. When you save them, restrict their field-level security and every report, export, and backup that includes them.
Save errors with Flow
Section titled “Save errors with Flow”- In Setup, open Flows, select New Flow, and choose Platform Event—Triggered Flow.
- Select Record Health Check Log as the Platform Event.
- Add a Decision element. When
{!$Record.rhc__ContractVersion__c}does not equal1.0, send the event to review and end the Flow. - Add a Get Records element for Record Health Check Error 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.
- Add a Create Records element that saves the error with the approved fields.
- Optionally, notify a restricted support queue. Include the Code and the Run ID, not the message or stack trace.
- Connect each fault path to monitoring that does not run Record Health Check.
- Test with a sandbox error, and then activate the Flow.
The Flow must never run Record Health Check. An error in that run could publish another Log event and start the Flow again.
Save errors with Apex
Section titled “Save errors with Apex”This example saves the identifying fields and the Code. Add Message or Stack Trace only after your access and retention review.
trigger HealthCheckErrorTrigger on rhc__Record_Health_Check_Log__e( after insert) { HealthCheckErrorHandler.saveErrors(Trigger.new);}public with sharing class HealthCheckErrorHandler { public static void saveErrors(List<rhc__Record_Health_Check_Log__e> events) { Set<String> eventIds = new Set<String>(); for (rhc__Record_Health_Check_Log__e eventRecord : events) { eventIds.add(eventRecord.rhc__EventId__c); }
// Event IDs already saved by an earlier delivery. Set<String> savedEventIds = new Set<String>(); for (Record_Health_Check_Error__c saved : [ SELECT Event_Id__c FROM Record_Health_Check_Error__c WHERE Event_Id__c IN :eventIds ]) { savedEventIds.add(saved.Event_Id__c); }
List<Record_Health_Check_Error__c> errors = new List<Record_Health_Check_Error__c>(); for (rhc__Record_Health_Check_Log__e eventRecord : events) { if (savedEventIds.contains(eventRecord.rhc__EventId__c)) { continue; } // An unexpected event shape goes to review instead of the error object. if (eventRecord.rhc__ContractVersion__c != '1.0') { // Send eventRecord.rhc__EventId__c to restricted monitoring. continue; } savedEventIds.add(eventRecord.rhc__EventId__c); errors.add( new Record_Health_Check_Error__c( Event_Id__c = eventRecord.rhc__EventId__c, Run_Id__c = eventRecord.rhc__RunId__c, Occurred_At__c = eventRecord.rhc__OccurredAt__c, Code__c = eventRecord.rhc__Code__c, Check_Set_Developer_Name__c = eventRecord.rhc__CheckSetDeveloperName__c, Check_Developer_Name__c = eventRecord.rhc__CheckDeveloperName__c, Salesforce_Record_Id__c = eventRecord.rhc__RecordId__c, User_Id__c = eventRecord.rhc__UserId__c, Exception_Type__c = eventRecord.rhc__ExceptionType__c, Contract_Version__c = eventRecord.rhc__ContractVersion__c ) ); }
if (errors.isEmpty()) { return; } List<Database.SaveResult> results = Database.insert(errors, false); for (Integer i = 0; i < results.size(); i++) { if (!results[i].isSuccess()) { // Send errors[i].Event_Id__c and results[i].getErrors() to restricted monitoring. } } }}The handler must never call Record Health Check, for the same reason as the Flow. To test it,
publish an rhc__Record_Health_Check_Log__e event with Event ID, Run ID, Level, Occurred At, and
Contract Version set, call Test.getEventBus().deliver(), and then query the error object.
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, and give that user Read access to the Log event.
How Publish Immediately affects delivery
Section titled “How Publish Immediately affects delivery”The Log event uses Publish Immediately: Salesforce delivers it even when the transaction that captured the error rolls back. That is what makes errors visible when a failing Check stops a Flow or an Apex transaction.
Record Health Check collects the errors during a request and publishes them, in groups of up to 100, when the request ends. A transaction that stops at an uncatchable Salesforce limit can end before that point, so some errors never produce an event. Keep Salesforce debug logs and your normal Apex exception monitoring for those cases.
Test before activation
Section titled “Test before activation”Test each of these cases in a sandbox:
- An error creates one protected error record.
- The same Event ID received twice creates one record and one notification.
- An event with a blank Record ID, Check, or Exception Type is saved without a fault.
- A Contract Version other than
1.0goes to review, and an unfamiliar Code is still saved. - The receiving automation never runs Record Health Check.
- Users without access cannot read the event, the object, its restricted fields, or its reports.