Subscribe to Events Using Managed Subscriptions (Beta)

Learning Objectives

After completing this unit, you’ll be able to:

Describe what managed subscriptions are.
Describe the benefits of managed subscriptions.
Explain how and when a commit request is sent.
Explain the metadata used to configure a managed subscription.

Managed Subscriptions (Beta)

Use managed subscriptions to track the events that a subscriber client consumed and to resume a subscription from where it left off after a client disconnects. Using the ManagedSubscribe RPC method, you can commit the Replay ID of the last processed event on the server. After the subscription disconnects and is restarted, it resumes seamlessly from the unprocessed events stored in the event bus.

Managed Subscriptions is a pilot or beta service that is subject to the Beta Services Terms at Agreements - Salesforce.com or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.

For more information about the Replay ID and event storage in the event bus, see Event Message Durability in the Pub/Sub API guide and Use Pub/Sub API unit in the Platform API Basics module.

Without the managed subscriptions, you can resume a subscription after a specific Replay ID with the Subscribe RPC method. But this requires you to manage the storage of the event Replay ID on the client. By using managed subscriptions, you don’t worry about storing the Replay ID on the client.

Like with the Subscribe RPC method, the ManagedSubscribe RPC method uses bidirectional streaming and is pull-based. WithManagedSubscribe, the client requests the number of events it is ready to receive from the server with a ManagedFetchRequest. The client then receives a ManagedFetchResponse with a batch of events. After receiving a batch of events and processing the events, the client commits the Replay ID of the last processed event.

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.

A managed subscription is unique per client and can’t be shared with other clients for the same Salesforce org.

Configuring a Managed Subscription

You configure the managed subscription behavior and state by using the ManagedEventSubscription in Metadata API and Tooling API.

This example is for a managed subscription Tooling API request body that you use later to set up a managed subscription for the opportunity change events.

{
  "FullName": "Managed_Sub_OpportunityChangeEvent",
  "Metadata":
  {
      "label" : "Managed Sub Order Event",
      "topicName" : "/data/OpportunityChangeEvent",
      "defaultReplay": "LATEST",
      "state" : "RUN",
      "errorRecoveryReplay" : "LATEST"
  }
}

Here's an overview of some field values that are specific to a managed subscription. For a detailed description of the field values, see ManagedEventSubscription (Beta) in the Metadata API Developer Guide and ManagedEventSubscription (Beta) in the Tooling API Developer Guide.

The topicName field specifies the event subscription path for a platform event, change event, or Real-Time Event Monitoring event. In this example, the topic name references the opportunity change event. Also, the topicName field can specify a channel that groups multiple platform events or change events. For more information about platform event channels, see Group Platform Events into One Stream with a Custom Channel in the Platform Events Developer Guide. For more information about change event channels, see Subscription Channels and Compose Streams of Change Data Capture Notifications with Custom Channels in the Change Data Capture Developer Guide.
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 state field to STOP. For more information, see Stopping a Managed Event Subscription in the Pub/Sub API Guide.
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.

The steps for creating the configuration are outlined later in this module.

Committing a Replay ID with Managed Subscriptions

After receiving and processing a batch of events, commit the Replay ID (event replay_id field in the protocol specification) of the event that was last processed. To commit a Replay ID, set it in CommitReplayRequest and send it in ManagedFetchRequest. For more information about the fields in ManagedFetchRequest and CommitReplayRequest, see the Pub/Sub API proto file.

Also, you should commit the Replay ID after receiving an empty batch of events. The ManagedFetchResponse contains the latest Replay ID in the latest_replay_id field. That Replay ID points to an advanced position in the stream beyond the last consumed event. An advanced position in the stream is possible even if you didn’t receive events because the event bus combines streams from multiple orgs. No org-specific information or personally identifiable information is shared with other orgs. Storing a recent Replay ID ensures that the server doesn’t take too much time to seek the event in the event bus when the subscription resumes.

For more information about the commit request, see ManagedSubscribe RPC method in the Pub/Sub API guide.

Keeping the Subscription Alive

The ManagedSubscribe call stream stays open if there are still pending events to be delivered from the server based on the number of events the client requested. If there are pending events to be delivered but no new events are available in the event bus, the server sends keepalive messages. Otherwise, the client is supposed to send fetch requests and commit requests to keep the stream alive. For more details, see ManagedSubscribe Keepalive Behavior in the Pub/Sub API guide.

Now that you learned about what managed subscriptions are, you can try them out in action in the next unit.

Besoin d'aide ?

En savoir plus

Subscribe to Events Using Managed Subscriptions (Beta)

Learning Objectives

Managed Subscriptions (Beta)

Configuring a Managed Subscription

Committing a Replay ID with Managed Subscriptions

Keeping the Subscription Alive

Resources