Brief Introduction
Salesforce.com is a hosting-based CRM solution for small businesses to large enterprises. It caught my interest last year when one of my clients wanted me to create a solution to sync up their Salesforce.com contacts with their MS Exchange server for all their sales team members in a centralized way, without installing Outlook plugin. I created the solution for the client using Salesforce Enterprise WSDL and MS Exchange WSDL. It was a really fun project for me since I learned a great deal about Salesforce.com Web Service API and the solution saved my client a lot of manual process time, about 80%. That’s a win-win. Before I created the solution for my client using Salesforce Enterprise API, I took a look at the Partner API realizing it is better than Enterprise API because my client will not need to rebuild the solution when they change their fields or metadata in their Salesforce. On the other hand, there is a time constraint so Enterprise API is used to save time.
Goals for this Adventure
Now that I have sometime to revisit the solution I have created, I want to understand a few things related to Salesforce.com Partner API.
- Time and effort to setup my development environment (Netbeans 6.9.1) for using Salesforce Partner API
- Integration effort to make use of class library generated by the Partner WSDL
- Determine and compare the implementation differences between Salesforce.com Enterprise and Partner API
- Share what I have learned so others can avoid some of the frustrations I went through
- Look for feedback from others who may want to share some of their experiences and insights
Salesforce.com provides extensive documentation and small set of examples on coding with Partner API. However, they are gears toward using Axis. I personally prefer JAX-WS to Axis since it seems more active in term of development by the open source community. I haven’t tried the Axis2 yet, so this is just my personal preference. There are also many postings regarding Partner API tutorials, and I think these tutorials are pretty good as well. You may want to check them out.
Setting Up Netbeans project using Partner API
There are many ways to create application project (desktop or web-based) in Netbeans, for this tutorial I am going to use desktop application. To create a desktop application, I go to File > New Project > Java > Java Desktop Application, click “Next”, and then click “Next” again. I named my application as SFPartnerWSDLApp with application class sfpartnerwsdlapp.SFPartnerWSDLApp. I choose Basic Application as the application shell and then click “Finish”. Netbeans takes care of the rest and create all the needed directory structures for the project.
Since I have already signed up for developer account in Salesforce.com and logged in, I go to Setup > Develop > API and download the Partner API WSDL. To download the Partner WSDL, I right mouse click on the link “Generate Partner WSDL” and save it to a folder, named wsdl, under the desktop application project directory I have just created. It should be in XML format. I named it partner.wsdl. If you have not already sign up as developer on Salesforce.com, you can go here and sign up before proceeding to the next step.
Next I create a new web service client in my desktop application project. To create a web service client, I right mouse click on my project, SFPartnerWSDLApp, in Netbeans, select New > “Web Services” > “Web Services Client” and click “Next”. Select “Local File” under “Specify the WSDL file for the Web Service” and then click “Browse…”. Select the partner.wsdl we have just downloaded. I provided a package name, com.salesforce.ws.partner, for the web services I am going to setup. Select JAX-WS for “Client Style” and checked the option for “Generate Dispatch Code”. Then click “Finish”.
At this point, I am getting an error due to name conflict from the generated stub code for the WSDL. To resolve conflict in generated stub code, I need to customize the JAXB binding by creating JAXB binding file with the following content. I named this file, sf-jaxb-binding.xml, and saved it under the wsdl folder I created earlier.
<?xml version="1.0" encoding="UTF-8"?>
<bindings
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://java.sun.com/xml/ns/jaxws">
<bindings
node="//xsd:schema[@targetNamespace='urn:partner.soap.sforce.com']">
<jaxb:globalBindings
underscoreBinding="asCharInWord" />
<jaxb:schemaBindings>
<jaxb:nameXmlTransform>
<jaxb:typeName
suffix="Type" />
</jaxb:nameXmlTransform>
</jaxb:schemaBindings>
</bindings>
<enableWrapperStyle>false</enableWrapperStyle>
<enableAsyncMapping>false</enableAsyncMapping>
</bindings>
To specify the external JAXB binding file in the web service client I have defined earlier, I went to my Netbeans project, expanded “Web Service References”, selected “partner” and right mouse clicked to select “Edit Web Service Attributes”. In the popup dialog, I selected “WSDL Customization” tab, scrolled all the way down to the bottom of the list, expanded “External Binding Files” and clicked “Add”. In the file dialog box, I navigated to and selected the JAXB binding file I have just created. Then I clicked “OK”.
At this point, Netbeans refreshes the generated stub source code using the external JAXB binding file. Everything is build without error. This concludes our part 1 of this tutorial. Nice, clean and easy. No need to tinker with Ant script and wsimport script. In my next tutorial, I am going to share with you on how to make use of this Salesforce.com Partner API library. Stay tune.
