Salesforce Transport for Mule 2.x User Guide

[ Key Features ] [ Setting Up the Salesforce Transport ] [ Configuring the Connection ] [ Writing to Salesforce ] [ Configuring Queries ] [ Customer Extensions and Customizations ] [ Note on Salesforce Partner WSDL ]

The Salesforce transport enables a powerful, seamless integration between Salesforce and other enterprise systems. Through the Salesforce transport, Mule takes Salesforce integration beyond just SOAP/Web Services, enabling connections over any of Mule's supported transports (like JMS, EJB, File, Email, and many others). In other words, the Salesforce transport increases interoperability between Salesforce and other systems in your enterprise, helping you to maximize your organization's ROI on these assets.

Key Features

Following are some of the key features of the Salesforce transport:

Enables Salesforce endpoints, which connect to a Mule endpoint
Uses the native Salesforce Partner Web Services API Version 14.0 (customizable to your own version)
Open source and freely available from the MuleForge
Adapts to Salesforce customizations unique to your environment
Supports secure login to Salesforce with auto-reconnect
Supports SOQL statements for retrieving Salesforce data. Allows parameterization of statements in your Mule configuration.
Supports update and upsert of Salesforce data
Support passing the session ID in the request header, enabling users to build RIA with tools like GWT or Flex
Automatically converts from Map payload to SObject, eliminating the need to write any Java code or use the Salesforce API.
Certified with Mule 2.2

Setting Up the Salesforce Transport

Follow the instructions in the Installation Guide for installing and configuring the Salesforce transport. Next, run the example to see some capabilities of the Salesforce transport.

Configuring the Connection

You can use the Salesforce transport to connect to Salesforce.

Salesforce Connection Properties

Property	Description	Default	Required
userName	The user name to be used in the login operation.		Yes
password	The password to be used in the login operation. You must append the security token to the password. You can reset the token here.		Yes
pollingFrequency	The delay in milliseconds between two polls to the database.	3000	No
batchSize	The batch size for Salesforce queries.	1000	No
loginTimeout	The idle timeout for the Salesforce connection.	86060*1000	No
sfdcURL	The URL for the Salesforce WSDL. This is required only if you want to override the default URL in the WSDL, such as using HTTP instead of HTTPS or connecting to a staging/test instance of Salesforce.	`https://www.salesforce.com/services/Soap/u/14.0`	No
dataSource-ref	Reference to the JDBC DataSource object. This object is typically created using Spring. You must provide this if you are using `pollingFieldName` in the SOQL inbound endpoint and want to persist the last poll time. You must ensure that the table in the database exists--use the `createPollingTable.sql` script to create the table.		No

Following is the minimum configuration:

    <sfdc:connector name="sfdcConn" userName="marc@acme.com"
        password="passwordplussecuritytoken"/>

Writing to Salesforce

There are two actions that are currently supported for writing to Salesforce:

Update: Updates one or more existing objects in your organization's data. The update call is analogous to the UPDATE statement in SQL.
```
<sfdc:outbound-endpoint path="/update/?sobject=Contact"/>
```
The expected payload by the endpoint is Map. The Map payload must contain keys that are the same as the column names of the Sobject (in this case "Contact") and must contain a key called "Id" that corresponds to the ID of the object that has to be updated. In the above example, the Map payload could contain:
```
Map 
{
Id, 0037000000dohg2

FirstName, Marc
LastName, Benioff
Phone, 415-901-7001 
Email, chairman@salesforce.com
}
```
Upsert: Creates new objects and updates existing objects. It matches on a custom field to determine the presence of existing objects. The upsert call is available for objects that can be updated by the update call and have an external ID field.
```
<sfdc:outbound-endpoint path="/upsert/?sobject=Contact&amp;externalIdFieldName=External_Id__c"/>
```
In the example above, the outbound payload is assumed to be a List of Maps (same as update above). The only difference is that instead of Id, External_Id__c is used to determine unique records in Salesforce. The field External_Id__c must be present in the Map payload.

Action	Endpoint Address	Expected Payload
update	`<endpoint address="sfdc://update"/>`	List of Map containing key/value pairs. The keys must be the same as the sObject field names.
upsert	`<endpoint address="sfdc://upsert"/>`	List of Map containing key/value pairs. The keys must be the same as the sObject field names.

Configuring Queries

Salesforce has defined its own query language [Salesforce Object Query Language (SOQL)||http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_calls_soql.htm]. SOQL is used to construct simple but powerful query strings similar to the SELECT command in SQL. SOQL allows you to specify the source object (such as Account), a list of fields to retrieve, and conditions for selecting rows in the source object.

The SOQL statement can be set directly on the endpoint itself:

<sfdc:inbound-endpoint path="/query/?soql=Select c.Id, c.FirstName, c.LastName, c.Title, c.Department,
c.Email, c.Phone from Contact c where  c.FirstName = '#[payload:]'" name="QueryContact" synchronous="true"/>

You can also define the pollingFieldName and pollingFieldInitialValue. The transport will maintain the state of the last poll time based on the value in the last retrieved pollingFieldName. For example:

<sfdc:inbound-endpoint path="/query/?soql=Select c.Id, c.FirstName, c.LastName, c.Title, c.Department,
c.Email, c.Phone from Contact c where  c.FirstName = '#[payload:]'" pollingFrequency="300000"
pollingFieldName="LastModifiedDate" pollingFieldInitialValue="2009-01-29T01:14:08.000Z"
name="QueryContact" synchronous="true"/>

Note: If you specify pollingFieldInitialValue and pollingFieldName, you must specify dataSource-ref in the Salesforce transport configuration. For an example, see salesforce-sugar-config.xml, which is provided with the Salesforce example in the distribution.

Customer Extensions and Customizations

The Partner API handles everything in terms of SObjects, so any client customization/extension would be dealt with in just the same way as any other default object would be. Custom objects can be updated, deleted, updated, queried, and searched like any standard object. The Salesforce documentation indicates that custom objects cannot be created through the Salesforce API itself. For this reason, extensions and custom objects must be created through the Salesforce web site.

Note on Salesforce Partner WSDL

The Salesforce transport was created using Salesforce's Partner WSDL. Following is what the Salesforce web site says about this type of WSDL.

Partner Web Services WSDL:

Used for client applications that are metadata driven and dynamic in nature. It is particularly but not exclusively useful to salesforce.com partners who are building client applications for multiple organizations. As a loosely typed representation of the Salesforce data model, it can be used to access data within any organization. This WSDL is most appropriate for developers of clients that can issue a query call to get information about an object before the client acts on the object.

In general, the enterprise WSDL is more straightforward to use, while the partner WSDL is more flexible and dynamically adaptable to different organizations, allowing you to write a single application that can be used for multiple users and multiple organizations.

The Partner WSDL was chosen over the Enterprise WSDL because it is more malleable. Hence the objects to be created need to be of SObject type as defined in the partner WSDL and not as defined in the Enterprise WSDL.

The Enterprise SObject is not the same as the Partner SObject and consequently one does not map well onto the other. It might be possible to create transformers to transform objects from Enterprise into Partner SObject. The API libraries available for download are compatible with JDK 5.0.