Using the TwoConnect Salesforce.com Adapter

Update: You should also watch the MSDN Webcast ‘Integrating Sales Data with LOB apps using the Salesforce.com adapter for BizTalk Server 2006‘.

In the month since I last posted, I’ve been working on an evaluation of Salesforce.com and its integration into an ERP system, with BizTalk 2006 acting as middleware using the TwoConnect Salesforce.com adapter.

The TwoConnect Salesforce.com adapter is a great ‘off-the-shelf’ adapter that will get you up and running in no time at all. If you’re thinking about using Salesforce.com and BizTalk, TwoConnect provide a trial adapter which is a good place to start – you can download a copy of both the BizTalk 2004 and 2006 adapters from TwoConnects AdapterWorx website (although free registration is required). The AdapterWorx site also has several helpful resources including an adapter datasheet, user guide and forums (although I wish some of their support team would respond to some of the queries!).

In this post I’ll run through the installation of the adapter and present a simple demonstration of ‘subscribing’ to updated Salesforce.com contacts.

Installation

Installation of the 2006 adapter was through the usual MSI route with the necessary Visual Studio adapter wizard extensions installing automatically.

Initially, the adapter didn’t appear in the BizTalk Explorer or Admin Console, until I realised that the adapter had to be manually added by clicking on ‘Platform Settings -> Adapters -> New -> Adapter’ in the Admin Console:

With configuration of the adapter completed, it became immediately available as a transport option in both the Explorer and Admin Console.

Salesforce.com Adapter Prerequisites

Before we get into the example solution you will need to register on Salesforce.com and generate a WSDL file specific to your organisation/account.Salesforce.com provide a developer portal at http://www.salesforce.com/developer/ – register as a developer and you will be provided with a free enterprise account. Follow these instructions to generate the necessary WSDL file and save it locally on your machine.I also suggest at this point that you create a simple contact on the Salesforce.com website so it can be changed and the adapter functionality demonstrated once the solution is complete.

Salesforce.com Adapter First Steps

The adapter is very similar to the SQL Server adapter that ships as standard with BizTalk 2004/06; developers start by adding adapter metadata through the included wizard and selecting the Salesforce.com adapter:

Next, provide the necessary connection details to connect to the Salesforce.com service. Use the WSDL file created earlier when prompted: Provide a meaningful target namespace and select whether you are generating a schema for a receive port or a send port. In a manner similar to the SQL Adapter Wizard, you will be promoted to populate both request and response document root element names: Because we want to ‘subscribe’ to objects that get updated on Salesforce.com (contacts in this example), we’re using the ‘GetUpdated’ operation; ‘Select’ allows us to perform a custom SOQL queries while ‘GetDeleted’ allows us to subscribe to deleted objects: Finally, we need to select the objects we want to subscribe to; because we want to get updated contacts in this example we’ll just select ‘Contact’ but we could select any other object or multiple objects here: Clicking ‘Finish’ on the final wizard page will cause Visual Studio to produce the relevant schema and a blank orchestration; delete the orchestration but keep the schema.

Build, Deploy and Configure

Follow the usual build and deploy process to deploy the new project to BizTalk; In either the Admin Console or BizTalk Explorer create a new receive port and location and select the Salesforce.com adapter as the Transport Type (note: your adapter will be listed under the name you provided when adding the adapter under Installation above).

Configure the adapter so that it will poll Salesforce.com every minute and retrieve back changes to contacts (I have assumed you are using the same naming as above – if not you will need to substitute the relevant values):

• Polling Interval: 1
• Polling Interval Unit: Minute
• SfBatchSize: 200
• Uri: [do not change]
• Password: [your sf.com (developer) password]
• Response Root Node: Response__GetUpdatedContacts
• SalesForceOperation: GETUPDATED Contact
• SfUrl: [do not change]
• Target NS: http://modhul.com/salesforce.com/get-updated-objects/contacts
• Username: [your sf.com (developer) username]

You will also need a send port bound to the receive location name (filter on BTS.ReceivePortName) that will output the Xml message returned by Sf.com to a file location.Once the relevant receive and send ports are enabled/enlisted & started, we are ready to test the solution.

Testing the Solution – Changing a Salesforce.com Contact

The solution described above will poll Salesforce.com once every 1 minute for any updated contacts. When a contact is changed on the website, the receive port will return a message describing the changed contact (using the schema generated above) and will drop the message into the Message Box; the subscribing send port will route then message to the designated file location. An example message is available in the download-able solution below.

Go ahead and change the contact on the Saleforce.com website you created earlier, wait for a minute and a message should appear in the directory detailed on the Send Port.

The returned message provides an Id of the changed object on Salesforce.com. With this Object Id, you can poll Salesforce.com using a SOQL statement to return either partial or full contact details.

Returning only the Object Id reduces the overhead incurred when using the polling adapter and provides more flexibility to the developer/system architect when developing solutions based on this adapter.

Finally…

I appreciate that this is a simple example, but it should provide you with the tools necessary to start working with the adapter.

I plan on further developing this simple example to demonstrate a full end-to-end solution utilising the power of orchestrations to retrieve updated objects and update end user systems, such as Exchange.

An example project is available for download in the Downloads Section of this blog.

Happy BizTalk-ing!