Configure the User and Batch Size for Your Platform Event Trigger with PlatformEventSubscriberConfig

You can override the default running user and batch size of a platform event Apex trigger. By default, the trigger runs as the Automated Process system user with a batch size of 2,000 event messages. Configuring the user and batch size enables you to bypass some limitations that sometimes arise from using the defaults. Use PlatformEventSubscriberConfig in Tooling API or Metadata API to configure the trigger.

Running the trigger as a specific user instead of the default Automated Process entity has these benefits.

  • Records are created, modified, and deleted as this user.
  • OwnerId fields of created records are populated to this user.
  • Records are shared with the user when sharing is enabled. For example, when the trigger calls into an Apex class declared with the with sharing keywords.
  • Debug logs for the trigger execution are created by this user.
  • You can send email messages from the trigger, which isn’t supported with the default Automated Process user.

You can specify any active user in the Salesforce org. The trigger runs in system context with privileges to access all records regardless of the user’s object and field-level permissions. Record sharing is enforced for the running user when the trigger calls into an Apex class declared with the with sharing keywords.

In addition to setting a user, you can specify a custom batch size from 1 through 2,000. The batch size is the maximum number of event messages that can be sent to a trigger in one execution. For platform event triggers, the default batch size is 2,000. Setting a smaller batch size can help avoid hitting Apex governor limits.

This image shows the Subscriptions related list in Setup for a platform event with a custom batch size and user.

The Subscriptions related list showing the trigger's custom batch size and user
  • We don’t recommend setting the batch size to a small number or to 1. Small batch sizes can slow down the processing of event messages. For batch size best practices, see "Adjust the Platform Event Trigger Batch Size" in the Platform Events Debugging Trailhead module.
  • If a trigger is running and subscribed to a platform event, new configuration settings take effect after you suspend and resume the trigger. You can suspend and resume a trigger from the platform event detail page by clicking Manage next to the Apex trigger in the Subscriptions related list. For more information, see View and Manage an Event’s Subscribers on the Platform Event’s Detail Page.

Note

To configure a platform event trigger with Tooling API, see PlatformEventSubscriberConfig in the Tooling API Developer Guide. To add a configuration, perform a POST with the PlatformEventSubscriberConfig REST resource, and perform a GET call to retrieve a configuration by ID. Also, you can query the configurations by using Tooling API.

To configure a platform event trigger with Metadata API, see PlatformEventSubscriberConfig in the Metadata API Developer Guide. You can use Visual Studio Code with the Salesforce Extension pack to deploy and retrieve Metadata API. For more information about installing Visual Studio Code and the extension pack, see Salesforce Extensions for Visual Studio Code. For more information about deploying and retrieving metadata by using the CLI, see source Commands and mdapi Commands in the Salesforce CLI Command Reference.

To learn about packaging PlatformEventSubscriberConfig components, see Platform Event Subscriber Configuration in the First-Generation Managed Packaging Developer Guide.