Skip to content

Latest commit

 

History

History
192 lines (145 loc) · 7.11 KB

USAGE.md

File metadata and controls

192 lines (145 loc) · 7.11 KB

Data types

Date format

To store Date fields just use a String with the following format: yyyy-mm-dd. Example: 2012-03-26.

Streaming

Using the Streaming API allows you to receive events for changes to Salesforce data that match a SOQL query you define, in a secure and scalable way.

This events will be converted to Mule events and dispatched to your flows.

Publishing a topic

Before you can start receiving events for changes in Salesforce, you must first create a PushTopic. A PushTopic is a special object in Salesforce that binds a name (the topic's name) and SOQL together. Once a PushTopic is created you can then subscribe to it by using only its name.

There are several ways in which you can create a PushTopic, we will cover using Salesforce itself and using this connector. You could potentially also use Workbench.

Using Salesforce

First, select Your Name | System Log.

Then, on the Logs tab, click Execute.

Finally, in the Enter Apex Code window, paste in the following Apex code, and click Execute.

PushTopic pushTopic = new PushTopic();
pushTopic.Name = 'AccountUpdates';
pushtopic.Query = 'SELECT Id FROM Account';
pushTopic.ApiVersion = 26.0;
insert pushTopic;

Using our connector

You can either use the create operation but also you can use our exclusive publish-topic operation as follows:

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

Subscribing to a topic

Once your topic has been created, you can start receiving events by subscribing to it. Our subscribe-topic acts like an inbound endpoint and it can be used as such.

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

A Mule flow is divided in two. The first portion of it is usually an inbound endpoint or a message source. It is an entity that will receive/generate events that will later be processed by the rest of the flow. The other portion is a collection of message processors which will processes the messages (aka events) received/generated by the inbound endpoint.

Every time our subscription to AccountUpdates receives an event it will execute the rest of the flow. In the case of this example it will print a message to the log at INFO level.

Examining the Events

The event that gets pushed down the flows contains information about the Salesforce data that has changed, how it changes, and when. Usually the raw JSON that the subscription receives looks something like this:

{
  "channel": "/topic/AccountUpdates",
  "data": {
    "event": {
      "type": "created",
      "createdDate": "2011-11-35T19:14:31.000+0000"
    },
    "sobject": {
      "Id": "a05D0000002jKF1IAM"
    }
  }
}

Our connector will parse this information and send you something that a flow can actually work with.

Inbound Properties

Some information will get passed along as inbound properties:

Property Name Scope Maps to
channel INBOUND channel JSON property
type INBOUND type JSON property in data
createdDate INBOUND createdDate JSON property in data

!!! Actually besides channel, every property inside event will be available as an INBOUND property.

Payload

The payload of the event is actually a Map. That map contains everything inside the sobject object in the received JSON data. It offered as a map for the convenience of being able to use map-payload expression evaluator to extract the information of the SObject.

See how in the Subscribing to a topic example we used #[map-payload:Id] to print the Id of the SObject.

Bulk

The Salesforce Bulk API is based is optimized for loading or deleting large sets of data. It allows you to query, insert, update, upsert, or delete a large number of records asynchronously by submitting a number of batches which are processed in the background by Salesforce.

Our connector simplifies the model heavily making it very transparent and really easy. While the connectors works with concepts like Jobs and Batches, you will rarely see them except maybe in responses.

Creating/Updating/Upserting Objects in Bulk

Creating objects in bulk is as easy as creating objects without the bulk portion of it. Let's do a quick recap as to how the regular create works:

<sfdc:create type="Account">
    <sfdc:objects>
        <sfdc:object>
            <Name>MuleSoft</Name>
            <BillingStreet>30 Maiden Lane</BillingStreet>
            <BillingCity>San Francisco</BillingCity>
            <BillingState>CA</BillingState>
            <BillingPostalCode>94108</BillingPostalCode>
            <BillingCountry>US</BillingCountry>
        </sfdc:object>
    </sfdc:objects>
</sfdc:create>

That Mule config extract will create an SObject of type Account with the properties that you see. You can have as many objects as you want inside the objects collection. The output of this message processor will be a list of SaveResult. A SaveResult is compound object between a status and an Id. Meaning that it will tell you whenever or not the object got created successfully and what the Id of that object is.

The Bulk version of the create operation is named create-bulk and shares the exact same signature.

<sfdc:create-bulk type="Account">
    <sfdc:objects>
        <sfdc:object>
            <Name>MuleSoft</Name>
            <BillingStreet>30 Maiden Lane</BillingStreet>
            <BillingCity>San Francisco</BillingCity>
            <BillingState>CA</BillingState>
            <BillingPostalCode>94108</BillingPostalCode>
            <BillingCountry>US</BillingCountry>
        </sfdc:object>
    </sfdc:objects>
</sfdc:create-bulk>

There are no practical differences. Of course, since it is a Bulk operation (meaning that the actual creation process will be handled by Salesforce in the background) we don't reply with a collection of SaveResults, because we do not have them yet. Instead we reply with a BatchInfo object with contains the id of the batch and the id of the job we just created to upload those objects.

This change in behavior remains true for all operations that support bulk.

Monitoring a Batch

You can monitor a Bulk API batch in Salesforce.

To track the status of bulk data load jobs and their associated batches, click Your Name | Setup | Monitoring | Bulk Data Load Jobs. Click on the Job ID to view the job detail page.

The job detail page includes a related list of all the batches for the job. The related list provides View Request and View Response links for each batch. If the batch is a CSV file, the links return the request or response in CSV format. If the batch is an XML file, the links return the request or response in XML format. These links are available for batches created in API version 19.0 and later.