Summary: Configuration | Message Processors | Message Sources
org.mule.modules

mule-module-sfdc

4.0
Namespacehttp://www.mulesoft.org/schema/mule/sfdc
Schema Locationhttp://www.mulesoft.org/schema/mule/sfdc/4.0/mule-sfdc.xsd
Version4.0
Minimum Mule Version3.2

Module Overview

The Salesforce Connector will allow to connect to the Salesforce application. Almost every operation that can be done via the Salesforce's API can be done thru this connector. This connector will also work if your Salesforce objects are customized with additional fields or even you are working with custom objects.

Integrating with Salesforce consists of web service calls utilizing XML request/response setup over an HTTPS connection. The technical details of this connection such as request headers, error handling, HTTPS connection, etc. are all abstracted from the user to make implementation quick and easy.

Summary

Configuration
<sfdc:config>
Configure an instance of this module
Message Processors
<sfdc:convert-lead>
Converts a Lead into an Account, Contact, or (optionally) an Opportunity.
<sfdc:create>
Adds one or more new records to your organization's data.
<sfdc:create-bulk>
Adds one or more new records to your organization's data.
<sfdc:create-single>
Adds one new records to your organization's data.
<sfdc:delete>
Deletes one or more records from your organization's data.
<sfdc:describe-global>
Retrieves a list of available objects for your organization's data.
<sfdc:describe-sobject>
Describes metadata (field list and object properties) for the specified object.
<sfdc:empty-recycle-bin>
The recycle bin lets you view and restore recently deleted records for 30 days before they are permanently deleted.
<sfdc:get-deleted>
Retrieves the list of individual records that have been deleted between the range of now to the duration before now.
<sfdc:get-deleted-range>
Retrieves the list of individual records that have been deleted within the given timespan for the specified object.
<sfdc:publish-topic>
Creates a topic which represents a query that is the basis for notifying listeners of changes to records in an organization.
<sfdc:query>
Executes a query against the specified object and returns data that matches the specified criteria.
<sfdc:query-single>
Executes a query against the specified object and returns the first record that matches the specified criteria.
<sfdc:update>
Updates one or more existing records in your organization's data.
<sfdc:update-bulk>
Updates one or more existing records in your organization's data.
<sfdc:upsert>
Upserts an homogeneous list of objects: creates new records and updates existing records, using a custom field to determine the presence of existing records.
<sfdc:upsert-bulk>
Upserts an homogeneous list of objects: creates new records and updates existing records, using a custom field to determine the presence of existing records.
Message Sources
<sfdc:subscribe-topic>
Subscribe to a topic.

Configuration

To use the this module within a flow the namespace to the module must be included. The resulting flow will look similar to the following:

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:sfdc="http://www.mulesoft.org/schema/mule/sfdc"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/sfdc
               http://www.mulesoft.org/schema/mule/sfdc/4.0/mule-sfdc.xsd">

      <!-- here goes your flows and configuration elements -->

</mule>

This module is configured using the config element. This element must be placed outside of your flows and at the root of your Mule application. You can create as many configurations as you deem necesary as long as each carries its own name.

Each message processor, message source or transformer carries a config-ref attribute that allows the invoker to specify which configuration to use.

Attributes
TypeNameDefault ValueDescription
xs:string name Optional. Give a name to this configuration so it can be later referenced.
xs:string proxyHost Optional. Proxy host
xs:string proxyPassword Optional. Proxy password
xs:int proxyPort 80 Optional. Proxy port
xs:string proxyUsername Optional. V Proxy username
xs:anyUri url https://login.salesforce.com/services/Soap/u/23.0 Optional. SalesForce SOAP endpoint

Connection Pool

This connector offers automatic connection management via the use of a connection pool. The pool will act a storage mechanism for all the connections that are in-use by the user of this connector.

Prior to execution of a processor, the connector will attempt to lookup an already established connection and if one doesn't exists it will create one. That lookup mechanism is done in the connection pool via the use of connection variables declared as keys.

The user of the connector can configure the pool by adding a connection-pooling-profile to the connector configuration like this:

    <sfdc:connection-pooling-profile maxActive="10" maxIdle="10"
                             exhaustedAction="WHEN_EXHAUSTED_GROW" maxWait="120"/>

The following is a list of connection attributes, each connection attribute can be configured at the config element level or they can also be added to each processor. If they are used at the processor level they get the benefit of full expression resolution.

Connection Attributes
NameDescription
username Username used to initialize the session
password Password used to authenticate the user
securityToken User's security token

Also this connector offers automatic retry for certain operations. There are a couple of situations in which a retry may solve the problem at hand, like for example if the system is currently busy or if the session has expired. Those kind of situations are solvable by reacquiring a connection and retrying the operation.

By default, the connector will automatically attempt to retry the operation only once. You can at your choosing specify a greater ammount of retries by using the retryMax attribute on each operation.

    ... retryMax="3"/>

Message Processors

<sfdc:convert-lead>

Converts a Lead into an Account, Contact, or (optionally) an Opportunity.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
leadId ID of the Lead to convert. Required. For information on IDs, see ID Field Type.
contactId ID of the Contact into which the lead will be merged (this contact must be associated with the specified accountId, and an accountId must be specified). Required only when updating an existing contact.IMPORTANT if you are converting a lead into a person account, do not specify the contactId or an error will result. Specify only the accountId of the person account. If no contactID is specified, then the API creates a new contact that is implicitly associated with the Account. To create a new contact, the client application must be logged in with sufficient access rights. To merge a lead into an existing contact, the client application must be logged in with read/write access to the specified contact. The contact name and other existing data are not overwritten (unless overwriteLeadSource is set to true, in which case only the LeadSource field is overwritten). For information on IDs, see ID Field Type.
accountId Optional. ID of the Account into which the lead will be merged. Required only when updating an existing account, including person accounts. If no accountID is specified, then the API creates a new account. To create a new account, the client application must be logged in with sufficient access rights. To merge a lead into an existing account, the client application must be logged in with read/write access to the specified account. The account name and other existing data are not overwritten. For information on IDs, see ID Field Type.
overWriteLeadSource Optional. Specifies whether to overwrite the LeadSource field on the target Contact object with the contents of the LeadSource field in the source Lead object (true), or not (false, the default). To set this field to true, the client application must specify a contactId for the target contact.
doNotCreateOpportunity Optional. Specifies whether to create an Opportunity during lead conversion (false, the default) or not (true). Set this flag to true only if you do not want to create an opportunity from the lead. An opportunity is created by default.
opportunityName Optional. Name of the opportunity to create. If no name is specified, then this value defaults to the company name of the lead. The maximum length of this field is 80 characters. If doNotCreateOpportunity argument is true, then no Opportunity is created and this field must be left blank; otherwise, an error is returned.
convertedStatus Valid LeadStatus value for a converted lead. Required. To obtain the list of possible values, the client application queries the LeadStatus object, as in: Select Id, MasterLabel from LeadStatus where IsConverted=true
sendEmailToOwner Optional. Specifies whether to send a notification email to the owner specified in the ownerId (true) or not (false, the default).
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
Exception Payload
Exception
Exception

<sfdc:create>

Adds one or more new records to your organization's data.

IMPORTANT: When you map your objects to the input of this message processor keep in mind that they need to match the expected type of the object at Salesforce.

Take the CloseDate of an Opportunity as an example, if you set that field to a string of value "2011-12-13" it will be sent to Salesforce as a string and operation will be rejected on the basis that CloseDate is not of the expected type.

The proper way to actually map it is to generate a Java Date object, you can do so using Groovy expression evaluator as #[groovy:Date.parse("yyyy-MM-dd", "2011-12-13")].


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
type Type of object to create
objects An array of one or more sObjects objects.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
Exception Payload
Exception
Exception

<sfdc:create-bulk>

Adds one or more new records to your organization's data.

This call uses the Bulk API. The creation will be done in asynchronous fashion.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
type Type of object to create
objects An array of one or more sObjects objects.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
  • A
    BatchInfo that identifies the batch job.
    http://www.salesforce.com/us/developer/docs/api_asynch/Content/asynch_api_reference_batchinfo.htm
Exception Payload
Exception
Exception

<sfdc:create-single>

Adds one new records to your organization's data.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
type Type of object to create
object SObject to create
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
Exception Payload
Exception
Exception

<sfdc:delete>

Deletes one or more records from your organization's data.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
ids Array of one or more IDs associated with the objects to delete.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
Exception Payload
Exception
Exception

<sfdc:describe-global>

Retrieves a list of available objects for your organization's data.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
Exception Payload
Exception
Exception

<sfdc:describe-sobject>

Describes metadata (field list and object properties) for the specified object.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
type Object. The specified value must be a valid object for your organization. For a complete list of objects, see Standard Objects
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
Exception Payload
Exception
Exception

<sfdc:empty-recycle-bin>

The recycle bin lets you view and restore recently deleted records for 30 days before they are permanently deleted. Your organization can have up to 5000 records per license in the Recycle Bin at any one time. For example, if your organization has five user licenses, 25,000 records can be stored in the Recycle Bin. If your organization reaches its Recycle Bin limit, Salesforce.com automatically removes the oldest records, as long as they have been in the recycle bin for at least two hours.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
ids Array of one or more IDs associated with the records to delete from the recycle bin. Maximum number of records is 200.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
Exception Payload
Exception

<sfdc:get-deleted>

Retrieves the list of individual records that have been deleted between the range of now to the duration before now.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
type Object type. The specified value must be a valid object for your organization.
duration The amount of time in minutes before now for which to return records from.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
Exception Payload
Exception
Exception

<sfdc:get-deleted-range>

Retrieves the list of individual records that have been deleted within the given timespan for the specified object.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
type Object type. The specified value must be a valid object for your organization.
startTime Starting date/time (Coordinated Universal Time (UTC)not local timezone) of the timespan for which to retrieve the data. The API ignores the seconds portion of the specified dateTime value ' (for example, 12:30:15 is interpreted as 12:30:00 UTC).
endTime Ending date/time (Coordinated Universal Time (UTC)not local timezone) of the timespan for which to retrieve the data. The API ignores the seconds portion of the specified dateTime value (for example, 12:35:15 is interpreted as 12:35:00 UTC).
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
Exception Payload
Exception
Exception

<sfdc:publish-topic>

Creates a topic which represents a query that is the basis for notifying listeners of changes to records in an organization.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
name Descriptive name of the push topic, such as MyNewCases or TeamUpdatedContacts. The maximum length is 25 characters. This value identifies the channel.
query The SOQL query statement that determines which records' changes trigger events to be sent to the channel. Maximum length: 1200 characters
description Optional. Description of what kinds of records are returned by the query. Limit: 400 characters
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Exception Payload
Exception
Exception

<sfdc:query>

Executes a query against the specified object and returns data that matches the specified criteria.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
query Query string that specifies the object to query, the fields to return, and any conditions for including a specific object in the query. For more information, see Salesforce Object Query Language (SOQL).
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
Exception Payload
Exception
Exception

<sfdc:query-single>

Executes a query against the specified object and returns the first record that matches the specified criteria.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
query Query string that specifies the object to query, the fields to return, and any conditions for including a specific object in the query. For more information, see Salesforce Object Query Language (SOQL).
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
Exception Payload
Exception
Exception

<sfdc:update>

Updates one or more existing records in your organization's data.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
type Type of object to update
objects An array of one or more sObjects objects.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
Exception Payload
Exception
Exception

<sfdc:update-bulk>

Updates one or more existing records in your organization's data.

This call uses the Bulk API. The creation will be done in asynchronous fashion.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
type Type of object to update
objects An array of one or more sObjects objects.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
  • A
    BatchInfo that identifies the batch job.
    http://www.salesforce.com/us/developer/docs/api_asynch/Content/asynch_api_reference_batchinfo.htm
Exception Payload
Exception
Exception

<sfdc:upsert>

Upserts an homogeneous list of objects: creates new records and updates existing records, using a custom field to determine the presence of existing records. In most cases, prefer
upsert(String, String, List) over
create(String, List), to avoid creating unwanted duplicate records.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
externalIdFieldName Contains the name of the field on this object with the external ID field attribute for custom objects or the idLookup field property for standard objects.
type The type of the given objects. The list of objects to upsert must be homogeneous
objects The objects to upsert
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
Exception Payload
Exception if a connection error occurs

<sfdc:upsert-bulk>

Upserts an homogeneous list of objects: creates new records and updates existing records, using a custom field to determine the presence of existing records. In most cases, prefer
upsert(String, String, List) over
create(String, List), to avoid creating unwanted duplicate records.

This call uses the Bulk API. The creation will be done in asynchronous fashion.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
type The type of the given objects. The list of objects to upsert must be homogeneous
externalIdFieldName Contains the name of the field on this object with the external ID field attribute for custom objects or the idLookup field property for standard objects.
objects The objects to upsert
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements
Return Payload
  • A
    BatchInfo that identifies the batch job.
    http://www.salesforce.com/us/developer/docs/api_asynch/Content/asynch_api_reference_batchinfo.htm
Exception Payload
Exception
Exception

Message Sources

<sfdc:subscribe-topic>

Subscribe to a topic.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
topic The name of the topic to subscribe to
callback The callback to be called when a message is received
retryMax 1 Optional. Specify how many times this operation can be retried automatically
username Optional. Username used to initialize the session
password Optional. Password used to authenticate the user
securityToken Optional. User's security token
Child Elements