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.
Use this template if you would like to sync Customers from SAP to Salesforce Accounts in manner real-time synchronization using Polling. The inbound SAP endpoint retrieves all Accounts in SAP using the custom BAPI ZMULE_CUSTOMER_GETLIST and transforms them to Salesforce Accounts. In the other direction, the synchronization is completed by polling Salesforce for Accounts and sending them to SAP using the standard IDoc DEBMAS01.
To make this Anypoint Template run, there are certain preconditions that must be considered. All of them deal with the preparations in both SAP and SFDC systems, that must be made in order for all to run smoothly. Failling to do so could lead to unexpected behavior of the template.
Before continue with the use of this Anypoint Template, you may want to check out this Documentation Page, that will teach you how to work with SAP and Anypoint Studio-
This Anypoint template uses a few private Maven dependencies in oder to work. If you intend to run this template with Maven support, please continue reading.
You will find that there are three dependencies in the pom.xml file that begin with the following group id: com.sap.conn.jco These dependencies are private for Mulesoft and will cause you application not to build from a Maven command line. You need to replace them with "provided" scope and copy the libraries into the build path.
There may be a few things that you need to know regarding SAP, in order for this template to work.
SAP backend system is used as source of data. SAP Connector is used to send and receive the data from the SAP backend. The connector can either use RFC calls of BAPI functions and/or IDoc messages for data exchange and needs to be properly customized as per chapter: Properties to be configured
In order for this Anypoint Template to work, there are a few things that need to be done in SAP first.
-
RFC destination of type "T = TCP/IP Connection" pointing to Program ID on gateway host needs to be created. The destination uses Unicode communication type with target system.
-
Program ID registration RFC SDK is used to register Program ID on gateway host. Same Program ID name is used here as in the RFC destination.
-
Partner Profile needs to be customized; type of Logical System as partner type. Message type DEBMAS is defined as Outbound and Inbound parameter. For Outbound parameter: As receiver port an RFC destination created earlier is used. IDoc Type DEBMAS01 is defined. For Inbound parameter: Process Code DEBM is used. IDoc Type DEBMAS01 is defined.
-
Partner Port needs to be defined for type of IDoc record type of SAP release 4.x as its version. As RFC destination same RFC destination created earlier is used.
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'
]
]
This template makes use of the External ID field offered by Salesforce. Here is a short description on how SFDC define external ID's
The templates uses the External ID in order to do xRef between the entities in both systems. The idea is, once an entity is created in SFDC it's decorated with an ID from the source system which will be used afteward for the template to reference it.
You will need to create a new custom field in your Product entity in SFDC with the following name:
sap_external_id
For instructions on how to create a custom field in SFDC plase check this link:
Simple steps to get SAP and Salesforce Customer/Account Bi-Directional Sync running.
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"In order to make this Anypoint Template run on Mule Studio there are a few extra steps that needs to be made. Please check this Documentation Page:
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.
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.
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:
-
polling.frequency
20000 -
polling.start.delay
1000 -
watermark.default.expression
2014-08-01T10:46:00.000Z -
watermark.default.expression.sap
2014-08-01T12:29:44Z -
page.size
100 -
sapOffset
+00:00:00 -
salesforceOffset
+00:00:00
SAP Connector configuration
-
sap.jco.ashost
your.sap.address.com -
sap.jco.user
SAP_USER -
sap.jco.passwd
SAP_PASS -
sap.jco.sysnr
14 -
sap.jco.client
800 -
sap.jco.lang
EN -
sap.default.accountGroup
ZAG2
SAP Endpoint configuration
- sap.jco.connectioncount
2 - sap.jco.gwhost
your.sap.addres.com - sap.jco.gwservice
sapgw14 - sap.jco.idoc.programid
PROGRAM_ID
SalesForce Connector configuration
- sfdc.username
bob.dylan@sfdc - sfdc.password
DylanPassword123 - sfdc.securityToken
avsfwCUl7apQs56Xq2AKi3X - sfdc.url
https://test.salesforce.com/services/Soap/u/32.0 - sfdc.integration.user.id
00520000003LtvG
SalesForce imposes limits on the number of API Calls that can be made. Therefore calculating this amount may be an important factor to consider. Customer migration template calls to the API can be calculated using the formula:
X / 200
Being X the number of Accounts to be synchronized on each run.
The division by 200 is because, by default, Accounts are gathered in groups of 200 for each Upsert API Call in the commit step. Also consider that this calls are executed repeatedly every polling cycle.
For instance if 10 records are fetched from origin instance, then 1 api calls to SFDC will be made ( 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.
The functional aspect of the Anypoint Template is implemented on this XML, directed by two batch jobs that will be responsible for creations/updates of Customers and Accounts in both ways. The several message processors constitute four high level actions that fully implement the logic of this Anypoint Template:
- Job executions are invoked from the trigger flows (endpoints.xml) everytime there is a new query executed asking for created/updated Contacts or Accounts.
- From SAP to SFDC: during the Process stage, each SAP Customer will be mapped into an SFDC Account and matched by name with the existent ones in the SFDC instance. After that, the Account will be upserted to the SFDC instance.
- From SFDC to SAP: during the Process stage, all the information needed to upsert the Customer will be retrieved from the SAP instance, and then the original Account will be mapped into a SAP Customer to proceed with the upsert.
- Finally during the On Complete stage, the Anypoint Template will unlock the processing for allowing the other direction to be executed.
This is file is conformed by a Flow containing the endpoints for triggering the template and retrieving the objects 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.