Managed Event Subscriptions (Beta)

Use managed event subscriptions to track the events that a subscriber client consumed and to resume a subscription from where it left off after a client disconnects. When you resubscribe with the new ManagedSubscribe RPC method, the subscription resumes after the last Replay ID that the client successfully committed on the server.

This feature is a Beta Service. Customer may opt to try such Beta Service in its sole discretion. Any use of the Beta Service is subject to the applicable Beta Services Terms provided at Agreements and Terms.

With managed subscriptions, you don’t worry about storing the Replay ID and managing your subscriptions on the client. After you commit a Replay ID, the system stores it on the server. After the subscription disconnects and is restarted, it resumes seamlessly from the events stored in the event bus. For more information about event storage in the event bus, see Event Message Durability. You can subscribe to the supported event types, or to custom or standard channels for platform events or change data capture events. A managed subscription is unique per client and can’t be shared with other clients for the same Salesforce org.

When using a managed subscription, you configure the subscription behavior and state by using the ManagedEventSubscription in Metadata API and Tooling API. For more information, see Configuring the Managed Event Subscription.

For a step-by-step walkthrough for configuring a managed subscription and using it to subscribe to events, see Java Quick Start for Managed Event Subscriptions (Beta).

Managed subscriptions have the same allocations as subscriptions that use the Subscribe RPC method. In addition, there’s a limit on how many managed subscriptions you can create per Salesforce org. See Pub/Sub API and Event Allocations.

To start a managed subscription, call the ManagedSubscribe RPC Method to subscribe by using the developer name of the ManagedEventSubscription Metadata API or Tooling API record, or use the ID of the Tooling API record.

ManagedEventSubscription contains configuration options for the managed subscription that controls subscription behavior after an error occurs and the subscription state. For more information, see Configuring the Managed Event Subscription.

If the subscriber client disconnects, the client can resume event delivery after the committed Replay ID, avoiding delivery of duplicate events or missed events. Events are returned from the event bus as long as they’re within the retention window. To learn about committing Replay IDs and the keepalive behavior, see ManagedSubscribe RPC Method (Beta).

This diagram shows the sequence of managed fetch requests and responses that a client performs to subscribe to events, commit the Replay ID of the last processed event, and resubscribe.

A sequence of managed fetch requests and responses

Here’s a detailed description of the diagram.

  1. The client starts the subscription by calling the ManagedSubscribe RPC method. It specifies the number of events to request in ManagedFetchRequest. The first time the client sends a managed fetch request, it sets the subscription_id or developer_name fields in ManagedFetchRequest. The developer_name field is the developer name of the ManagedEventSubscription Metadata or Tooling record. The subscription_id field is the ID of the Tooling API ManagedEventSubscription record.
  2. The server returns a batch of events in ManagedFetchResponse.
  3. After processing the events, the client commits the Replay ID of the last processed event by setting the CommitReplayRequest field of ManagedFetchRequest. Also, the client requests new events by setting the num_requested field of ManagedFetchRequest.
  4. The server returns a CommitReplayResponse nested in a ManagedFetchResponse that contains the result of the Replay ID commit request, indicating success or failure.
  5. The client receives the response of the Replay ID commit. After a successful commit, the server holds the Replay ID that the client committed (event100.replay_id).
  6. The client doesn’t process any events and disconnects.
  7. The client resubscribes by making a new ManagedSubscribe RPC method call. It sends the same subscription ID and requests new events in ManagedFetchRequest as part of the ManagedSubscribe RPC method call.
  8. The server returns a batch of events in ManagedFetchResponse. The batch of events starts from the event that’s after the one last processed (event100), in addition to new events received since the client shutdown. Events are returned from the event bus as long as they’re within the retention window.

The previous diagram shows one use case. It doesn’t show an example of when an empty ManagedFetchResponse is returned with the latest Replay ID. For best practices on when to commit a Replay ID, see Committing a Replay ID.

Managed subscriptions use configuration options that you set in ManagedEventSubscription by using Tooling API or Metadata API. You can define the topic to subscribe to, the position in the stream where the subscription starts, and where it resumes after an error.

This example shows a managed event subscription configuration for Order Event. This JSON example is the body of a REST API POST request that creates a managed event subscription named My_Managed_Subscription. The corresponding REST endpoint is /services/data/v61.0/tooling/sobjects/ManagedEventSubscription.

Here’s a brief description of the ManagedEventSubscription fields. For more information about each field, see ManagedEventSubscription (Beta) in the Metadata API Developer Guide and ManagedEventSubscription (Beta) in the Tooling API Developer Guide.

  • The topicName specifies the event subscription path. In this example, the topic name references Order_Event__e.
  • The defaultReplay field specifies from where the subscription starts for the first time or after it was stopped, or when no replay ID is stored. In this example, it starts from the latest events received.
  • The state field specifies whether the subscription is running or stopped. In this example, it’s set to be running. The administrator can stop the subscription by changing the changing state field to STOP. For more information, see Stopping a Managed Event Subscription.
  • The errorRecoveryReplay field specifies the position in the stream where the subscription restarts if the committed Replay ID is invalid. The Replay ID can be invalid if it corresponds to an event outside the event retention window. In this example, the subscription restarts from the latest event received.

When you create, update, or delete a ManagedEventSuscription, there can be a delay before the new or changed configuration takes effect in Pub/Sub API. If you delete a ManagedEventSuscription, ensure that you don’t recreate one with the same developer name to reduce inconsistencies.

An administrator can stop a managed subscription through ManagedEventSubscription in Metadata API or Tooling API. When the administrator stops the subscription via the API, the stored Replay ID value that was committed previously is deleted. Unlike a subscription that ends due to an error or by shutting down the client, the subscription that is stopped via the API doesn’t resume where it left off the next time it’s restarted. It starts from the position specified in the defaultReplay field, which is either the latest or earliest position in the stream.

When the ManagedEventSubscription state field is changed from RUN to STOP, the system notifies the Pub/Sub API client of the new state value after a small delay and the subscription disconnects.

To stop a subscription with ManagedEventSubscription by using Tooling API, send a PATCH request to this REST endpoint after replacing the <ID> placeholder with the ID of ManagedEventSubscription record: /services/data/v61.0/tooling/sobjects/ManagedEventSubscription/<ID>. Include the FullName field and the state field in the Metadata object.

To get the ID of a ManagedEventSubscription record, perform this query in Tooling API after replacing the developer name placeholder with the developer name.

To start a managed subscription, update the state field to RUN and, after waiting for a short while to allow for the state change to take effect in the service, call the ManagedSubscribe RPC method. The subscription starts from the position specified in the defaultReplay field. If you call ManagedSubscribe RPC when the state field is set to STOP, the subscription doesn’t start.

See Also