Process Events with Salesforce Connector 10.12

You can use Anypoint Connector for Salesforce (Salesforce Connector) as an inbound connector to stream data from Salesforce into your application. To use the connector this way, use one of these sources:

Subscribe topic listener
Subscribe channel listener
Replay topic listener
Replay channel listener

When deploying apps in a distributed environment such as a runtime cluster, the source must run on the primary node. Running the source on multiple nodes causes duplicate event consumption.

Each event that travels through your flow contains information about the Salesforce data that changed, including how the data changed and when the change occurred.

Salesforce stores events for 24 hours (or 72 hours for high-volume events). A subscriber to a topic or channel can retrieve events related to that topic or channel during this retention window, after which the subscriber can retrieve only newer events that have not yet expired.

Salesforce assigns each broadcast event a numeric ID that is unique to the organization and channel. IDs are incremented, but not necessarily consecutively; for example, the event following event 999 might be event 1025. Salesforce does not reuse the IDs of deleted events.

Before You Begin

To process events with Salesforce Connector, ensure that you have:

Access to the Salesforce target resource
The required Salesforce Streaming API permissions enabled in your organization

To receive events for Salesforce changes associated with a topic, either create a new topic or use an existing one.

Object Store Usage in Events

Both Salesforce Connector and Mule runtime engine (Mule) use an object store to persist data for features such as automatic message replay and message redelivery:

The object store included in Mule for on-premises deployments of Mule apps has no transaction limits.
The free version of Object Store for CloudHub deployments of Mule apps has a limit of 10 transactions per second.

For more information about Object Store versions, see Object Store Notes.

Replay Topic Listener and Replay Channel Listener Operations

The Replay topic and Replay channel listener operations can continue from the last replay ID they received before restarting the application.

When a Mule app starts for the first time, the connector creates an object store that saves data:

If there are no failed events, the source starts from the event associated with the last successfully processed event ID.
If there are one or more failed events, the source starts with the event associated with the lowest replay ID that failed.

Saving this change data capture in an object store ensures that no message is processed twice and that when the application restarts, it can reprocess any failed messages. The IDs are stored in the object store for 72 hours, after which they are automatically removed.

For each message that comes through a topic or streaming channel to which the connector is subscribed, the connector uses up to four transactions to update the object store information.

If you have multiple workers deployed in CloudHub, the Replay topic listener source processes each message on all Mule instances. To avoid this situation, you can do one of the following:

Modify your app to filter out duplicate messages.
Designate a single worker as a receiver and then use a shared queue to pass the messages to a different worker to process the message.

Resume from the Last Replay ID

To enable the resume from the last replay ID functionality for the Replay topic listener and Replay channel listener sources, the connector must store information about the events that were successfully processed by the flow in which the source is used. The connector uses an object store to store that information.

The way that the object store stores the necessary data for the resume from the last replay ID functionality varies depending on the environment:

When a Mule app runs locally, the connector creates a persistent store in the file system.

If the application stops and restarts, or if a connection issue triggers a reconnection, the data saved in the object store enables the connector to continue processing messages at the point where it stopped.
When a Mule app runs in a cluster with the nodes either on the same machine or on different machines, Mule uses a distributed in-memory object store:
- If the primary node (the one consuming the messages) shuts down, the node that takes over for the primary node does not reprocess the same messages. Instead, the node continues from where the previous node stopped processing the messages.
- If the cluster stops, the data from the object store is lost. When the cluster restarts, the configuration at the source level determines whether the connector reprocesses the messages.
To persist data so that the app continues processing events when restarted, create a persistent object store, as described in Create and Manage a Cluster Manually.
If you use multiple workers when running the app in CloudHub, all of the workers receive and process the events.

Multiple Flows That Use the Same Source

If you have two or more flows that use a source that listens to events on the same channel or topic, the events are consumed two or more times from your user quota. To avoid this, consider implementing that logic in a single flow instead.

Having multiple sources listening to the same events and having the Resume from the Last Replay Id option enabled can lead to data corruption and the potential loss of events.

Work with Topic Events

Work with topic events by creating a topic, subscribing to a topic, and replaying topic messages.

Create a Topic to Receive Data from Salesforce

When you create a topic, the connector creates a PushTopic, which is a special object in Salesforce that binds a name (in this case, the topic’s name) and a Salesforce Object Query Language (SOQL) query together. After you create a topic, you can subscribe to it by its name.

You can use either the Create (create) operation or Publish topic (publish-topic) operation to create a topic. The following example uses the publish-topic operation to create a topic:

<sfdc:publish-topic name="AccountUpdates" query="SELECT Id, Name FROM Account"/>

Alternatively, you can create a topic in Salesforce by executing code from an Enter Apex Code window, which is accessible through the system logs, for example:

PushTopic pushTopic = new PushTopic();
pushTopic.ApiVersion = 23.0;
pushTopic.Name = 'AllAccounts';
pushTopic.Description = 'All records for the Account object';
pushTopic.Query = 'SELECT Id, Name FROM Account';
insert pushTopic;
System.debug('Created new PushTopic: '+ pushTopic.Id);

Subscribe to a Topic

To subscribe to a topic, add either the Subscribe topic listener (subscribe-topic-listener) or the Replay topic listener (replay-topic-listener) as a source for your flow. The source acts as an inbound endpoint. Every time the subscription receives an event, the source executes the rest of the flow in your Mule app.

In the following XML example, Mule prints a message to the log at the INFO level when the AccountUpdates topic receives an event:

<flow name="accountUpdatesSubscription">
    <!-- INBOUND ENDPOINT -->
    <sfdc:subscribe-topic-listener topic="AccountUpdates"/>
    <!-- REST OF YOUR FLOW -->
    <logger level="INFO" message="Received an event for Salesforce Object ID #[map-payload:Id]"/>
</flow>

You can subscribe to a topic that was not previously published in Salesforce. However, after the topic is published, you won’t receive notifications for that topic unless you resubscribe to it.

Replay Messages from a Topic

A subscriber can specify which events to receive. By default, a subscriber receives only the events that occur after subscribing. Events outside of the 24-hour retention period (or 72-hour retention period for high-volume events) are discarded.

The Replay topic listener source provides these options:

ALL

Subscriber receives all events, including past events that are within the 24-hour (or 72-hour) retention period and new events that are sent after the client subscribes.
ONLY_NEW

Subscriber receives new events that are sent after the client subscribes.
FROM_REPLAY_ID

Subscriber receives all events after the specified event replayId.

If you specify either the ALL replay option or ONLY_NEW replay option, the replayId value is ignored.

The Resume from the Last Replay Id checkbox enables you to specify an automatic replay of stored events based on the Replay ID of the last event processed by the connector. You can use this functionality when the connector stops listening, such as a during a server shutdown or dropped connection. If the stored Replay ID is outside the 24-hour retention period, the replay option determines which events to replay.

To support the resume from last replay ID functionality, the connector uses a persistent object store to keep different details regarding the processed messages. This feature reduces the possibility of message loss and avoids processing duplicate messages. For more information about how the object store is used, see Object Store Usage in Events.

In the following XML example, the Replay topic listener operation (replay-topic-listener) acts like an inbound endpoint for the Logger component message:

<flow name="accountUpdatesReplay">
    <!-- INBOUND ENDPOINT -->
    <sfdc:replay-topic-listener topic="AccountUpdates" replayId="1" replayOption="ALL" autoReplay="true"/>
    <!-- REST OF YOUR FLOW -->
    <logger level="INFO" message="Replayed events: #[payload]"/>
</flow>

Work with Streaming Channel Events

Work with streaming channel events by creating a streaming channel, subscribing to a streaming channel, replaying streaming channel events, and pushing events to a streaming channel.

Create a Streaming Channel

To create a streaming channel, you must have the proper Salesforce Streaming API permissions enabled in your organization.

Follow these steps to create a streaming channel:

Log in to your Salesforce Developer Edition organization.
Under All Tabs (+), select Streaming Channels.
On the Streaming Channels tab, select New.
Enter /u/notifications/ExampleUserChannel in the Streaming Channel Name field.
Enter an optional description.

You can also create a streaming channel by using either the connector Create operation or the connector Publish streaming channel (publish-streaming-channel) operation. The following example uses the publish-streaming-channel operation:

<sfdc:publish-streaming-channel
    name="/u/Notifications"
    description="General notifications"/>

Subscribe to a Streaming Channel

After you create a streaming channel, you can start receiving events by subscribing to the channel. The Subscribe channel listener (subscribe-channel-listener) source acts like an inbound endpoint. In this example, every time a subscription to /u/TestStreaming receives an event, it executes the rest of the flow and logs a message at the INFO level:

<flow name="notificationsChannelSubscription">
  <!-- INBOUND ENDPOINT -->
  <sfdc:subscribe-channel-listener streamingChannel="/u/TestStreaming"/>
  <!-- REST OF YOUR FLOW -->
  <logger level="INFO" message="Received an event: #[payload]"/>
</flow>

The Streaming channel field of the Subscribe channel listener operation does not display change events that are available in the Salesforce environment. However, your connector can subscribe to a streaming channel to obtain this information. For example, to subscribe to the All Change Events channel, use /data/ChangeEvents as the channel name to which to subscribe.

For more information, see Subscription Channels in the Salesforce Change Data Capture Developer Guide.

Replay Messages from a Streaming Channel

A streaming channel can replay notifications. The Replay channel listener (replay-channel-listener) source acts as an inbound endpoint, for example:

<flow name="flowStreamingChannelReplay">
    <!-- INBOUND ENDPOINT -->
    <sfdc:replay-channel-listener streamingChannel="/u/Notifications" replayId="1" replayOption="ALL"/>
    <!-- REST OF YOUR FLOW -->
    <logger level="INFO" message="Replayed events: #[payload]"/>
</flow>

If you specify either the ALL replay option or the ONLY_NEW replay option, the replayId value is ignored.

To support the resume from the last replay ID feature, the connector uses a persistent object store to keep details regarding the processed messages. This feature reduces the possibility of message loss and avoids processing duplicate messages. For more information about how the object store is used, see Object Store Usage in Events.

Push Events to a Streaming Channel with No Listener

Users can push events to a streaming channel, even if the channel does not have a listener for reading published events. After a listener is started for the channel, Salesforce Streaming API pushes as many messages as it can to the listener, based on the maximum daily limit.

For example, the maximum number of delivered event notifications within a 24-hour period for a free Salesforce organization is 10,000. Suppose you publish 15,000 events to that channel. When Salesforce Connector subscribes to that channel, Streaming API attempts to push 10,000 events, thus consuming the daily quota. The API then attempts to push the remaining 5,000 events the next day, before pushing any new events.

In this scenario, the connector streams the events one-by-one into the Mule app. If the app takes too long to process a message, Streaming API might instruct the connector to reconnect. If this happens, Streaming API drops all of the unprocessed messages. You can avoid this situation by implementing a reliability pattern, as described in Reliability Patterns.

Work with Custom Events

Work with custom events by obtaining custom event notifications and pushing custom events to a streaming channel.

Obtain Custom Event Notifications

Salesforce Connector enables you to obtain custom event notifications, which apply to general events that are not tied to Salesforce data changes.

To obtain custom event notifications:

Use the Publish streaming channel operation to create a streaming channel.

StreamingChannel is a special Salesforce object that represents a channel used to notify listeners of generic Streaming API events.

You can also create a streaming channel through Salesforce or Workbench.
Use the Subscribe channel listener operation to subscribe to the channel.

Salesforce Connector converts the custom events in your streaming channel to Mule events.

Push Custom Events to a Streaming Channel

Salesforce enables you to push custom events to a specific streaming channel through the REST API. To do this, use Workbench or this connector.

The following example uses the connector’s Push generic event (push-generic-event) operation to push custom events to the channel with the ID 0M6j0000000KyjBCAS:

<flow name="flowPushGenericEvent">
    <!-- INBOUND ENDPOINT -->
    <sfdc:push-generic-event channelId="0M6j0000000KyjBCAS">
      <sfdc:events>
            <sfdc:event payload="Notification message text"/>
        </sfdc:events>
  </sfdc:push-generic-event>
    <logger level="INFO" message="Replayed events: #[payload]"/>
</flow>

You can retrieve the channel ID from the response map of the Publish streaming channel operation. Alternatively, you can retrieve the channel ID from the Salesforce page:

Log in to your Salesforce Developer Edition organization.
Under All Tabs (+), select Streaming Channels.

If the channel ID field is not visible on the channel list, follow these steps:

Click Create New View.
Type a name for the view in the Name input field.
In the Available Fields list, select Streaming Channel ID and click Add.

You should see the channel ID for each streaming channel in the list.
Add any other fields.
Click Save.

The JSON received as a response from the push event operation looks something like this:

[
  {
  "userOnlineStatus": {
  },
  "fanoutCount": 0
  }
]