Decide when to use Platform Events
Find out exactly which Platform Events a Record Health Check run publishes, which setting controls each one, what the events contain, and why an expected event might not arrive. Record Health Check publishes events only when a setting or a caller asks for them; every publication setting is off by default.
Use Platform Events when a separate Flow, Apex trigger, or external integration must receive results after a run. When the Flow or Apex code that runs the Checks can use the returned result itself, publish nothing. See Save or send results after a run to choose.
The three events
Section titled “The three events”| Platform Event | API name in your org | Publish behavior | Contains |
|---|---|---|---|
| Record Health Check Set Run | rhc_ | Publish After Commit | Result counts for one record, or the outcome of one async job |
| Record Health Check Result | rhc_ | Publish After Commit | Status, severity, and Reason Code of one Check for one record |
| Record Health Check Log | rhc_ | Publish Immediately | One technical error, with its message, exception type, and stack trace |
All three are high-volume Platform Events, which Salesforce keeps for 72 hours. Their fields carry
the rhc__ prefix in your org, such as rhc__EventId__c.
Publish from the record-page card
Section titled “Publish from the record-page card”Card publication happens only when a person selects Run or Rerun. Two checkboxes control it:
| Setting | Where | When selected, a Run or Rerun publishes |
|---|---|---|
Publish User Run Event (PublishUserRunEvent_) | On the Check Set | One Record Health Check Set Run event with the result counts for the record |
Publish User Result Event (PublishUserResultEvent_) | On each Check | One Record Health Check Result event for that Check, whatever its status: PASS, FAIL, SKIPPED, UNABLE_, or ERROR |
The two settings are independent. A Check can publish Result events even when its Check Set does not publish a Set Run event.
To set them up:
- In Setup, open Custom Metadata Types → Record Health Check Set → Manage Records, edit the Check Set, and select Publish User Run Event.
- Open Custom Metadata Types → Record Health Check → Manage Records, and select Publish User Result Event only on the Checks whose individual results the receiving automation needs.
- Confirm that the card shows a Run or Rerun button. If Run Button Display or Card
Heading Display is Hide, the card has no button, and nothing can publish. Validation warns
about this with
USER_RUN_PUBLICATION_UNREACHABLEorUSER_RESULT_PUBLICATION_UNREACHABLE. - Build and test the receiving automation in a sandbox before you select the checkboxes in production.
These card runs never publish:
- the automatic run when When Checks Run is When the page opens;
- a browser refresh; and
- the automatic rerun after a person saves the record.
Selecting Rerun after an automatic run does publish, because a person started it.
Card events are reported by the browser
Section titled “Card events are reported by the browser”On the card, the browser evaluates each Check and then sends the results to Salesforce to publish. Salesforce keeps only results for the record on the page and for Checks in the Check Set, but it does not evaluate the Checks again. A person who can run Checks controls that browser request, so a card event is a notification, not proof.
Before a receiving process makes a change that affects security, compliance, or money, it should run the Check again from Apex or Flow. Events from Apex, Flow, and async jobs come from Salesforce’s own evaluation.
Publish from Flow, Apex, and async jobs
Section titled “Publish from Flow, Apex, and async jobs”Flows, Apex code, and the Queueable, Batch, and Scheduled jobs that install with the package use an Event Publication value instead of the card checkboxes:
| Event Publication | Record Health Check Result events | Record Health Check Set Run events |
|---|---|---|
NONE | None | None |
ACTIONABLE | One for each FAIL, UNABLE_, or ERROR result | One for every record checked |
ALL | One for every result, including PASS and SKIPPED | One for every record checked |
- The Flow actions require Event Publication. In Apex, the default is
NONE. - With
ACTIONABLE, a record whose Checks all pass still publishes its Set Run event. A missing Set Run event therefore means that publication or receiving failed, not that the record was clean. - A run of a single Check also publishes one Set Run event per record. The event names the Check’s Check Set and counts only that Check.
- Agentforce actions, the MCP service, and Preview always use
NONE.
Async job events
Section titled “Async job events”When a Queueable, Batch, or Scheduled job runs with ACTIONABLE or ALL, it publishes one more
Set Run event when the job ends:
| Field | Value |
|---|---|
| Phase | COMPLETED when every submitted record was processed; otherwise FAILED |
| Run ID | batch- or queue- followed by the job ID, the same as the job’s other events |
| Submitted Record Count | Records submitted to the job |
| Processed Record Count | Records the job processed |
| Record ID and counts | Blank |
A Batch job commits each group of records separately. When a later group fails, events from earlier groups are still delivered. Wait for the job’s final event before you treat the job’s results as complete. Receiving automation that saves per-record history must skip the final event, which has a blank Record ID.
Publish Log events
Section titled “Publish Log events”Publish Error Log Event (PublishErrorLogEvent__c) on the Check Set controls Log events. It is
cleared by default and is independent of the card checkboxes and of Event Publication.
When it is selected, every technical error that Record Health Check captures while running that
Check Set publishes one Record Health Check Log event, whatever started the run. Assign the
Record Health Check Error Log Publisher permission set, which grants Read and Create on the Log
event, to each user who runs the Check Set. When the Check Set cannot be identified, nothing
publishes. When Salesforce rejects a Log event, the debug log shows LOG_EVENT_PUBLISH_FAILED or
LOG_EVENT_FLUSH_FAILED, and the result does not change.
Log events can contain error messages and stack traces. See Save or route restricted errors before you turn them on.
When events are delivered
Section titled “When events are delivered”The Set Run and Result events use Publish After Commit:
- The Checks run and return their result to the caller.
- Record Health Check asks Salesforce to publish the requested events.
- When the transaction that ran the Checks completes successfully, Salesforce delivers the events.
- When that transaction rolls back, Salesforce discards them.
- The receiving automation runs separately. Its success or failure does not change the result.
So the caller cannot wait for the receiving automation. A Flow or Apex caller must decide what to do from the result returned to it.
The Log event uses Publish Immediately, so an error event is delivered even when the transaction later rolls back. Record Health Check collects error events during a request and publishes them when the request ends.
Record Health Check publishes events in groups of up to 100. When Salesforce rejects a publish
request, Record Health Check writes a warning to the debug log (SET_RUN_PUBLISH_FAILED or
CHECK_RESULT_PUBLISH_FAILED) and the result does not change.
Source values
Section titled “Source values”Every Set Run and Result event records what started the run in Source (rhc__Source__c):
| Source | The run was started by |
|---|---|
USER_ | A person selecting Run or Rerun on the card |
FLOW | A Record Health Check Flow action |
APEX_ | Apex code calling the RecordHealthCheck class |
QUEUEABLE | The packaged Queueable job |
BATCH | The packaged Batch job |
SCHEDULED | The packaged scheduled job, which runs the Batch job |
The package also defines RUN_ON_LOAD, FUTURE, and AGENT. Automatic card runs (RUN_ON_LOAD)
and Agentforce actions (AGENT) never publish these events. FUTURE appears only when Apex code in
an @future method sets withExecutionOrigin(rhc.RecordHealthCheckExecutionOrigin.FUTURE) on its
request; those events publish like any other Apex run.
Prevent publishing loops
Section titled “Prevent publishing loops”Receiving automation that runs Checks again must use Event Publication NONE. If it publishes,
each run starts the receiving automation again.
Versions on events
Section titled “Versions on events”| Field | Value in 2.0.11 | Meaning |
|---|---|---|
Contract Version (rhc_) | 1. | The shape of the event. It changes only when a field changes incompatibly. |
Framework Version (rhc_) | 2. | The Record Health Check release that published the event. |
Receiving automation should check Contract Version, not Framework Version, and send an
unexpected version to review. The event Contract Version is separate from the 2.0 Contract
Version that the Flow actions and Apex API return.
What the events contain
Section titled “What the events contain”The Set Run and Result events contain the Record ID, Run ID, Event ID, Check Set and Check API names, statuses, severities, Reason Codes, counts, and the time of the event. They never contain:
- the running user’s ID;
- card messages, Found values, or Expected values;
- formulas or queries; or
- field values from the record.
When the receiving automation needs more information, it reads it from Salesforce with its own access, using the Record ID and API names in the event.
Log events are different: they contain the running user’s ID, the error message, the exception type, and the stack trace. See the Log event fields.
Troubleshoot a missing or repeated event
Section titled “Troubleshoot a missing or repeated event”| What you see | Likely cause | What to do |
|---|---|---|
| No event after opening or refreshing the page | Automatic runs never publish. | Select Run or Rerun, or run the Checks from Flow or Apex. |
| No event after saving the record | The automatic rerun after a save never publishes. | Select Rerun. |
| No event after selecting Run or Rerun | The checkbox for that event is cleared, or Salesforce rejected the publish request. | Check Publish User Run Event or Publish User Result Event, and look for a publish warning in the debug log. |
| The card has no Run or Rerun button | Run Button Display or Card Heading Display is Hide. | Show the button, or run the Checks from Flow or Apex. |
| No event after a Flow or Apex run | Event Publication is NONE, the transaction rolled back, or Salesforce rejected the publish. | Check the caller’s Event Publication value and whether the transaction completed. |
| No Result event for a passing Check | ACTIONABLE publishes only FAIL, UNABLE_, and ERROR. | Use ALL when the receiving automation needs every result. |
| No Log event | Publish Error Log Event is cleared, or the running user lacks the Error Log Publisher permission set. | Select the checkbox and assign the permission set. |
| The same event was processed twice | Salesforce delivered it again after a retry or replay. | Save the Event ID in a Unique field and skip events already saved. |
| Two events for one record within seconds | Two separate runs, such as two browser tabs. | Keep both. Each has its own Event ID. |
| A Set Run event has a blank Record ID | It is the final event of an async job. | Read Phase and the record counts instead. |
| The receiving automation failed | Its own access, limits, or logic failed after delivery. | Fix and recover it separately. The result is already final. |
Related
Section titled “Related”- Save or send results after a run
- Save Check Set run summaries
- Save or route individual Check results
- Save or route restricted errors
- Record Health Check Set Run fields
- Record Health Check Result fields
- Record Health Check Log fields
- Flow action inputs and outputs
- Run from Apex
- Receive events with Pub/Sub API