ManagedSubscribe RPC Method (Beta)

The ManagedSubscribe method starts a managed subscription. With a managed subscription, you can store the Replay ID of the event last processed on the server and resume your subscription from where it left off by using the stored Replay ID. The ManagedSubscribe method uses bidirectional streaming and is pull-based, which means that it requests new events.

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.

A client calls ManagedSubscribe to subscribe to events by using the developer name of the ManagedEventSubscription Metadata API or Tooling API record, or the ID of the Tooling API record. ManagedEventSubscription contains configuration options that control subscription behavior after an error occurs and the subscription state. For more information, see Configuring the Managed Event Subscription. A managed subscription is unique per client and can’t be shared with other clients for the same Salesforce org.

For more information about the fields in ManagedFetchRequest and ManagedFetchResponse, see the Pub/Sub API proto file.

A client can request the number of events that it can process by setting the num_requested field in ManagedFetchRequest. The maximum value for num_requested is 100. The server returns the events in one or more ManagedFetchResponses. Each ManagedFetchResponse contains the number of events that are pending delivery in the pending_num_requested field. If a client requests more events before the server finishes the last requested amount, the server appends the new amount to the current batch of events that it still needs to fetch and deliver.

The client commits the Replay ID from each received ManagedFetchResponse whether the response contains events or is empty.

• If a ManagedFetchResponse contains one or more events, the client processes the events first and then commits the Replay ID of the last processed event in CommitReplayRequest as part of ManagedFetchRequest.
• If a ManagedFetchResponse contains an empty batch of events, the client commits the latest Replay ID that it gets from the latest_replay_id field in ManagedFetchResponse. The client sets the Replay ID in CommitReplayRequest as part of ManagedFetchRequest. 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.

The commit request response is returned in a ManagedFetchResponse in CommitReplayResponse, which indicates success or failure. This particular ManagedFetchResponse doesn’t include any events. There is no one-to-one correspondence between a CommitReplayRequest and a CommitReplayResponse. The server can return a CommitReplayResponse for one or more CommitReplayRequests. If the server receives several commit requests in a short amount of time, the server commits the latest Replay ID from all the requests and returns one CommitReplayResponse.

If the Replay ID commit request is successful, as indicated by the CommitReplayResponse success field, the Replay ID is stored on the server. It’s used the next time the client resubscribes by using the same subscription ID to resume the subscription from where it left off.

If the Replay ID commit request isn’t successful, make sure that you sent a valid Replay ID. If your commit request is valid, you can ignore the commit failure. You can rely on future commit requests that the client sends after processing the next batch of events to succeed in case the previous error was transient. The next time the client sends a CommitReplayRequest as part of a new ManagedFetchRequest, if it succeeds, the new Replay ID is stored on the server.

The ManagedSubscribe call stream stays open under certain conditions, including the number of pending events to be delivered, and the Replay ID commit requests the client sends. The number of pending events is based on the number of events the client requested in ManagedFetchRequests and the number of events delivered in ManagedFetchResponses.

This table summarizes how to keep a managed subscription stream open for each condition.

Condition	To keep a managed subscription stream alive
Pending events to be sent to the client and there are still events in the event bus to be delivered (pending_num_requested in ManagedFetchResponse is greater than zero)	The stream stays open. After the first ManagedFetchResponse is received, the client must commit a Replay ID within 30 minutes from when the last ManagedFetchResponse with a CommitReplayResponse was sent. To commit a Replay ID, a client sends a ManagedFetchRequest with the CommitReplayRequest set to the Replay ID value.
No more pending events to be sent to the client (pending_num_requested in ManagedFetchResponse is equal to zero)	The client must request new events within 60 seconds from when the last ManagedFetchResponse was sent. To request new events, a client sends a ManagedFetchRequest with a num_requested field greater than zero. After the first ManagedFetchResponse is received, the client must commit a Replay ID within 30 minutes from when the last ManagedFetchResponse with a CommitReplayResponse was sent. To commit a Replay ID, a client sends a ManagedFetchRequest with the CommitReplayRequest set to the Replay ID value.
Pending events to be sent to the client but no new events are available in the event bus to be delivered (pending_num_requested in ManagedFetchResponse is greater than zero)	The server keeps the stream open by sending keepalive messages within 270 seconds. A keepalive message indicates that the Pub/Sub API service is healthy and provides a new Replay ID that points to an advanced position in the stream.

If there are pending events to be sent to the client (pending_num_requested in ManagedFetchResponse is greater than zero) but no new events are available in the event bus, the server keeps the stream alive by sending keepalive messages within 270 seconds. The keepalive message is an empty batch ManagedFetchResponse with the latest replay_id. The returned replay_id can be the last event consumed in your client or 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.

For best performance results, we recommend that you commit the replay_id from each empty ManagedFetchResponse by sending a CommitReplayRequest with that replay_id as part of a ManagedFetchRequest. That way, when you restart the subscription, it starts from a replay_id that’s recent. An old replay_id refers to an earlier position in the stream than the replay_id that the keepalive message returns. Using the more recent replay_id ensures that the server doesn’t take too much time to seek the event in the event bus when the subscription restarts.

See Also

• Managed Event Subscriptions (Beta)
• Java Quick Start for Managed Event Subscriptions (Beta)
• Subscribe RPC Method