Skip to content
Suggest a correction

Decide when to use Platform Events

Guide9 min read

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.

Platform EventAPI name in your orgPublish behaviorContains
Record Health Check Set Runrhc__Record_Health_Check_Set_Run__ePublish After CommitResult counts for one record, or the outcome of one async job
Record Health Check Resultrhc__Record_Health_Check_Result__ePublish After CommitStatus, severity, and Reason Code of one Check for one record
Record Health Check Logrhc__Record_Health_Check_Log__ePublish ImmediatelyOne 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.

Card publication happens only when a person selects Run or Rerun. Two checkboxes control it:

SettingWhereWhen selected, a Run or Rerun publishes
Publish User Run Event (PublishUserRunEvent__c)On the Check SetOne Record Health Check Set Run event with the result counts for the record
Publish User Result Event (PublishUserResultEvent__c)On each CheckOne Record Health Check Result event for that Check, whatever its status: PASS, FAIL, SKIPPED, UNABLE_TO_EVALUATE, 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:

  1. In Setup, open Custom Metadata Types → Record Health Check Set → Manage Records, edit the Check Set, and select Publish User Run Event.
  2. 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.
  3. 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_UNREACHABLE or USER_RESULT_PUBLICATION_UNREACHABLE.
  4. 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.

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.

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 PublicationRecord Health Check Result eventsRecord Health Check Set Run events
NONENoneNone
ACTIONABLEOne for each FAIL, UNABLE_TO_EVALUATE, or ERROR resultOne for every record checked
ALLOne for every result, including PASS and SKIPPEDOne 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.

When a Queueable, Batch, or Scheduled job runs with ACTIONABLE or ALL, it publishes one more Set Run event when the job ends:

FieldValue
PhaseCOMPLETED when every submitted record was processed; otherwise FAILED
Run IDbatch- or queue- followed by the job ID, the same as the job’s other events
Submitted Record CountRecords submitted to the job
Processed Record CountRecords the job processed
Record ID and countsBlank

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 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.

The Set Run and Result events use Publish After Commit:

  1. The Checks run and return their result to the caller.
  2. Record Health Check asks Salesforce to publish the requested events.
  3. When the transaction that ran the Checks completes successfully, Salesforce delivers the events.
  4. When that transaction rolls back, Salesforce discards them.
  5. 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.

Every Set Run and Result event records what started the run in Source (rhc__Source__c):

SourceThe run was started by
USER_INITIATEDA person selecting Run or Rerun on the card
FLOWA Record Health Check Flow action
APEX_APIApex code calling the RecordHealthCheck class
QUEUEABLEThe packaged Queueable job
BATCHThe packaged Batch job
SCHEDULEDThe 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.

Receiving automation that runs Checks again must use Event Publication NONE. If it publishes, each run starts the receiving automation again.

FieldValue in 2.0.11Meaning
Contract Version (rhc__ContractVersion__c)1.0The shape of the event. It changes only when a field changes incompatibly.
Framework Version (rhc__FrameworkVersion__c)2.0.11The 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.

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.

What you seeLikely causeWhat to do
No event after opening or refreshing the pageAutomatic runs never publish.Select Run or Rerun, or run the Checks from Flow or Apex.
No event after saving the recordThe automatic rerun after a save never publishes.Select Rerun.
No event after selecting Run or RerunThe 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 buttonRun 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 runEvent 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 CheckACTIONABLE publishes only FAIL, UNABLE_TO_EVALUATE, and ERROR.Use ALL when the receiving automation needs every result.
No Log eventPublish 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 twiceSalesforce 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 secondsTwo separate runs, such as two browser tabs.Keep both. Each has its own Event ID.
A Set Run event has a blank Record IDIt is the final event of an async job.Read Phase and the record counts instead.
The receiving automation failedIts own access, limits, or logic failed after delivery.Fix and recover it separately. The result is already final.