Note that using this template is subject to the conditions of this License Agreement. Please review the terms of the license before downloading and using this template. In short, you are allowed to use the template for free with Mule ESB Enterprise Edition, CloudHub, or as a trial in Anypoint Studio.
As a Salesforce admin I want to synchronize Users between two Salesfoce orgs.
This Template should serve as a foundation for setting an online sync of Users from one SalesForce instance to another. Everytime there is a new User or a change in an already existing one, the integration will poll for changes in SalesForce source instance and it will be responsible for updating the User on the target org.
What about Passwords? When the User is updated in the target instance, the password is not changed and therefore there is nothing to concern about in this case. Password set in case of User creation is not being covered by this template considering that many different approaches can be selected.
Requirements have been set not only to be used as examples, but also to establish a starting point to adapt your integration to your requirements.
As implemented, this Template leverage the Batch Module. The batch job is divided in Input, Process and On Complete stages. The integration is triggered by a poll defined in the flow that is going to trigger the application, querying newest SalesForce updates/creations matching a filter criteria and executing the batch job. During the Process stage, each SFDC User will be filtered depending on, if it has an existing matching user in the SFDC Org B. The last step of the Process stage will group the users and create/update them in SFDC Org B. Finally during the On Complete stage the Template will log output statistics data into the console.
To make this Anypoint Template run, there are certain preconditions that must be considered. All of them deal with the preparations in both source and destination systems, that must be made in order for all to run smoothly. Failling to do so could lead to unexpected behavior of the template.
- Users cannot be deleted in SalesForce: For now, the only thing to do regarding users removal is disabling/deactivating them, but this won't make the username available for a new user.
- Each user needs to be associated to a Profile: SalesForce's profiles are what define the permissions the user will have for manipulating data and other users. Each SalesForce account has its own profiles. In this kick you will find a processor labeled assignProfileId and Username to the User where to map your Profile Ids from the source account to the ones in the target account. Note that for the integration test to run properly, you should change the constant DEFAULT_PROFILE_ID in BusinessLogicTestIT to one that's valid in your source test organization.
- Working with sandboxes for the same account: Although each sandbox should be a completely different environment, Usernames cannot be repeated in different sandboxes, i.e. if you have a user with username bob.dylan in sandbox A, you will not be able to create another user with username bob.dylan in sandbox B. If you are indeed working with Sandboxes for the same SalesForce account you will need to map the source username to a different one in the target sandbox, for this purpose, please refer to the processor labeled assign ProfileId and Username to the User.
There may be a few things that you need to know regarding Salesforce, in order for this template to work.
In order to have this template working as expected, you should be aware of your own Salesforce field configuration.
###FAQ
-
Where can I check that the field configuration for my Salesforce instance is the right one?
Salesforce: Checking Field Accessibility for a Particular Field
-
Can I modify the Field Access Settings? How?
If the user configured in the template for the source system does not have at least read only permissions for the fields that are fetched, then a InvalidFieldFault API fault will show up.
java.lang.RuntimeException: [InvalidFieldFault [ApiQueryFault [ApiFault exceptionCode='INVALID_FIELD'
exceptionMessage='
Account.Phone, Account.Rating, Account.RecordTypeId, Account.ShippingCity
^
ERROR at Row:1:Column:486
No such column 'RecordTypeId' on entity 'Account'. If you are attempting to use a custom field, be sure to append the '__c' after the custom field name. Please reference your WSDL or the describe call for the appropriate names.'
]
row='1'
column='486'
]
]
There are no particular considerations for this Anypoint Template regarding Salesforce as data destination.
Simple steps to get Salesforce to Salesforce User Broadcast running. See below.
In this section we detail the way you should run your Anypoint Template on your computer.
First thing to know if you are a newcomer to Mule is where to get the tools.
Mule Studio offers several ways to import a project into the workspace, for instance:
- Anypoint Studio generated Deployable Archive (.zip)
- Anypoint Studio Project from External Location
- Maven-based Mule Project from pom.xml
- Mule ESB Configuration XML from External Location
You can find a detailed description on how to do so in this Documentation Page.
Once you have imported you Anypoint Template into Anypoint Studio you need to follow these steps to run it:
- Locate the properties file
mule.dev.properties, in src/main/resources - Complete all the properties required as per the examples in the section Properties to be configured
- Once that is done, right click on you Anypoint Template project folder
- Hover you mouse over
"Run as" - Click on
"Mule Application"
Complete all properties in one of the property files, for example in [mule.prod.properties] (../master/src/main/resources/mule.prod.properties) and run your app with the corresponding environment variable to use it. To follow the example, this will be mule.env=prod.
Once your app is all set and started, there is no need to do anything else. The application will poll SalesForce to know if there are any newly created or updated objects and synchronice them.
While creating your application on CloudHub (Or you can do it later as a next step), you need to go to Deployment > Advanced to set all environment variables detailed in Properties to be configured as well as the mule.env.
Once your app is all set and started, you will need to define Salesforce outbound messaging and a simple workflow rule. This article will show you how to accomplish this
The most important setting here is the Endpoint URL which needs to point to your application running on Cloudbhub, eg. http://yourapp.cloudhub.io:80. Additionaly, try to add just few fields to the Fields to Send to keep it simple for begin.
Once this all is done every time when you will make a change on Account in source Salesforce org. This account will be sent as a SOAP message to the Http endpoint of running application in Cloudhub.
Mule Studio provides you with really easy way to deploy your Template directly to CloudHub, for the specific steps to do so please check this link
In order to use this Mule Anypoint Template you need to configure properties (Credentials, configurations, etc.) either in properties file or in CloudHub as Environment Variables. Detail list with examples:
- http.port
9090 - poll.frequencyMillis
60000 - poll.startDelayMillis
0 - watermark.defaultExpression
YESTERDAY
- sfdc.a.username
bob.dylan@orga - sfdc.a.password
DylanPassword123 - sfdc.a.securityToken
avsfwCUl7apQs56Xq2AKi3X - sfdc.a.url
https://login.salesforce.com/services/Soap/u/28.0
- sfdc.b.username
joan.baez@orgb - sfdc.b.password
JoanBaez456 - sfdc.b.securityToken
ces56arl7apQs56XTddf34X - sfdc.b.url
https://login.salesforce.com/services/Soap/u/28.0
SalesForce imposes limits on the number of API Calls that can be made. Therefore calculating this amount may be an important factor to consider. User Broadcast Template calls to the API can be calculated using the formula:
1 + UsersToSync + UsersToSync / CommitSize
Being UsersToSync the number of Users to be synchronized on each run.
The division by CommitSize is because by default, for each Upsert API Call, Users are gathered in groups of a number defined by the Commit Size property. Also consider that this calls are executed repeatedly every polling cycle.
For instance if 10 records are fetched from origin instance, then 12 api calls will be made (1 + 10 + 1).
This brief guide intends to give a high level idea of how this Anypoint Template is built and how you can change it according to your needs. As mule applications are based on XML files, this page will be organized by describing all the XML that conform the Anypoint Template. Of course more files will be found such as Test Classes and Mule Application Files, but to keep it simple we will focus on the XMLs.
Here is a list of the main XML files you'll find in this application:
Configuration for Connectors and Properties Place Holders are set in this file. Even you can change the configuration here, all parameters that can be modified here are in properties file, and this is the recommended place to do it so. Of course if you want to do core changes to the logic you will probably need to modify this file.
In the visual editor they can be found on the Global Element tab.
Functional aspect of the Template is implemented on this XML, directed by one flow that will poll for SalesForce creations/updates. The severeal message processors constitute four high level actions that fully implement the logic of this Template:
- During the Input stage the Template will go to the SalesForce Org A and query all the existing users that match the filter criteria.
- During the Process stage, each SFDC User will be filtered depending on, if it has an existing matching user in the SFDC Org B.
- The last step of the Process stage will group the users and create/update them in SFDC Org B. Finally during the On Complete stage the Template will logoutput statistics data into the console.
This is file is conformed by a Flow containing the Poll that will periodically query Salesforce for updated/created Users that meet the defined criteria in the query. And then executing the batch job process with the query results.
This is the right place to handle how your integration will react depending on the different exceptions. This file holds a Choice Exception Strategy that is referenced by the main flow in the business logic.