How to Build a Salesforce SOAP API Client OSGi Bundle

A few months ago, I had the need to integrate an application built using the OSGi framework with the Salesforce CRM system. The integration with the CRM system is realized through the SOAP API that exposes Salesforce.

The Force.com SOAP API (formerly known as the Force.com Web Services API) lets you integrate Force.com applications that can create, retrieve, update, or delete records managed by Salesforce, Force.com, and Database.com, records such as accounts, leads, and custom objects. With more than 20 different calls, SOAP API also lets you maintain passwords, perform searches, and much more. You can use the SOAP API with any programming language that supports Web services.

1. OSGi Bundle

To achieve this type of integration and since the application runs in OSGi context, I decided to create an OSGi bundle so that it can then be used by other OSGi applications. The OSGi bundle is created through the Force.com Web Service Connector (WSC) version 40.1.1 and export this package:

1. com.sforce.soap.partner.*
2. com.sforce.soap.enterprise.*
3. com.sforce.async.*
4. come.sforce.bulk.*
5. com.sforce.ws.*

The project Salesforce SOAP API Client OSGi Bundle is available on GitHub and the OSGi bundle (can be installed in every OSGi R6 compliant container) JAR is released on the Maven Central Repository (the last release is 1.0.2).

For the project I used Apache Maven to manage the project lifecycle with these main plugins:

1. Exec Maven Plugin: This plugin is used to run the WSC tool to generate Partner and Enterprise SOAP API stubs;
2. BND Tools: This plugin is used to properly create the OSGi bundle through the bnd.bnd configuration file.

Below is shown the Exec Maven Plugin configuration for the execution of the WSC tool. There are two executions: one to create the Partner stub (from WSDL partner file) and the other to create the Enterprise stub (from WSDL enterprise file).You can see the complete contents of the pom.xml. 

            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>1.6.0</version>
                <executions>
                    <execution>
                        <id>wsc-partner</id>
                        <phase>process-sources</phase>
                        <goals>
                            <goal>exec</goal>
                        </goals>
                        <configuration>
                            <executable>java</executable>
                            <arguments>
                                <argument>-DcompileTarget=${java.source}</argument>
                                <argument>-jar</argument>
                                <argument>${basedir}/libs/force-wsc-40.1.1-uber.jar</argument>
                                <argument>${salesforce.wsdl.partner.path}</argument>
                                <argument>${basedir}/libs/partner-${project.version}.jar</argument>
                            </arguments>
                        </configuration>
                    </execution>
                    <execution>
                        <id>wsc-enterprise</id>
                        <phase>process-sources</phase>
                        <goals>
                            <goal>exec</goal>
                        </goals>
                        <configuration>
                            <executable>java</executable>
                            <arguments>
                                <argument>-DcompileTarget=${java.source}</argument>
                                <argument>-jar</argument>
                                <argument>${basedir}/libs/force-wsc-40.1.1-uber.jar</argument>
                                <argument>${salesforce.wsdl.enterprise.path}</argument>
                                <argument>${basedir}/libs/enterprise-${project.version}.jar</argument>
                            </arguments>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

Below is shown the BND Tools Plugin configuration for the execution the process that generates the OSGi bundle based on the directives of the bnd.bnd file.  

            <plugin>
                <groupId>biz.aQute.bnd</groupId>
                <artifactId>bnd-maven-plugin</artifactId>
                <version>3.3.0</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>bnd-process</goal>
                        </goals>
                    </execution>
                </executions>
                <dependencies>
                    <dependency>
                        <groupId>biz.aQute.bnd</groupId>
                        <artifactId>biz.aQute.bndlib</artifactId>
                        <version>3.2.0</version>
                    </dependency>
                </dependencies>
            </plugin>

The following is the bnd.bnd file that is being processed by the BND Tools plugin and contains all the necessary directives to properly generate the OSGi bundle. Note the Export-Package and Include-Resource directives. You can see the complete contents of the bnd.bnd.

Bundle-Name: Salesforce SOAP API Client OSGi Bundle
Bundle-SymbolicName: it.dontesta.labs.liferay.salesforce.client.soap
Bundle-Description: Salesforce SOAP API Client OSGi bundle build with Force.com Web Service Connector (WSC)
Bundle-Version: 1.0.0-SNAPSHOT
Bundle-Category: Salesforce
Bundle-ContactAddress: https://www.dontesta.it/contatti/
Bundle-Developers: $$anonymous$$
Bundle-DocURL: https://www.dontesta.it/salesforce-client-soap
Bundle-Copyright: Antonio Musarra's Blog (c) 2017
Bundle-License: MIT License
Bundle-Icon: Console
Bundle-Vendor: Antonio Musarra's Blog
Bundle-RequiredExecutionEnvironment: JavaSE-1.8

Import-Package: \
!com.google.appengine.api.urlfetch,\
!org.codehaus.jackson.*,\
!org.stringtemplate.v4.*,\
!org.antlr.runtime.*,\
!org.antlr.stringtemplate.*,\
!org.apache.commons.*,\
*

Export-Package: \
com.sforce.soap.partner.*;version="1.0.0",\
com.sforce.soap.enterprise.*;version="1.0.0",\
com.sforce.async.*;version="1.0.0",\
com.sforce.bulk.*;version="1.0.0",\
com.sforce.ws.*;version="1.0.0"

-includeresource: \
@libs/partner-${project.version}.jar,\
@libs/enterprise-${project.version}.jar

The build process launched with the  mvn clean package  command will create the OSGi bundle JAR inside the target directory (for example: salesforce-client-soap-1.0.3-SNAPSHOT.jar). The figure shows the content of the OSGi bundle of the Salesforce API SOAP client.

2. How to Use It

If you need to access Salesforce via the SOAP API for your project development, then you could add to your project the dependency of the salesforce-client-soap bundle.

The last (release) version of the bundle is 1.0.2, available on the Maven Central Repository. Below are the two dependencies, Gradle or Maven, to add to your project:

Maven dependency:

<dependency>
<groupId>it.dontesta.labs.liferay.salesforce.client.soap</groupId>
<artifactId>salesforce-client-soap</artifactId>
<version>1.0.2</version>
</dependency>

Gradle dependency:

compile group:'it.dontesta.labs.liferay.salesforce.client.soap', name:'salesforce-client-soap', version:'1.0.2'

I implemented a series of Gogo Shell commands to interact with Salesforce using this OSGi bundle (salesforce-client-soap). The commands are:

1. salesforce:login: Login to your Salesforce instance.
2. salesforce:createAccount: Create account into your Salesforce instance.
3. salesforce:getNewestAccount: Query for the newest accounts.
4. salesforce:loginEnterprise: Login to your Salesforce instance using the Enterprise Connection.
5. salesforce:getNewestAccountEnterprise: Query for the newest accounts using the Enterprise Connection.

The video is a demo of Gogo Shell commands that let you perform operations on Salesforce. In this video not show the commands that use the Enterprise Connection.

3. Resources

If you follow these resources, you'll see how to use the Salesforce SOAP API.

• Introducing SOAP API
• Force.com Web Service Connector (WSC)
• Salesforce Liferay Gogo Shell Command Client