Liferay 7 Salesforce.com Gogo Shell Command Client

This project is born as demo for using the Salesforce SOAP API Client OSGi Bundle inside of the Liferay 7. This sample project implements a set of Gogo Shell commands that allow us to interact with the Salesforce CRM system. All project sources code are available on GitHub (salesforce-client-gogoshell-command).

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 to maintain passwords, perform searches, and much more. You can use the SOAP API with any programming language that supports Web services.

Figure 1 – Manage data using the Force.com SOAP API

 

The commands that are implemented in Liferay 7:

  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

The diagram in Figure 2 shows a possible integration scenario between Liferay and the CRM system that in this case is Salesforce.com. The CRM Application (Figure 2) in this case is implemented by this project.

Integration scenario Liferay 7 and CRM (in this case Salesforce.com) via SOAP

Figure 2 – Integration scenario Liferay 7 and CRM (in this case Salesforce.com) via SOAP

The version of this project was tested on Liferay 7 CE GA4. You can download the tomcat bundle of the Liferay 7 CE GA4 from sourceforge.

1. Getting started

To build the project you need:

  1. Sun/Oracle JDK 1.8
  2. Maven 3.2 or Gradle 3.x (this project include the gradle wrapper)
  3. Git tools

You also need to install the OSGi Salesforce SOAP API client bundle. You can follow these instructions How to install in Liferay 7 CE/DXP. If you want can download the bundle JAR salesforce-client-soap (v1.0.1) from Maven repository and deploy to Liferay (via auto deploy directory or directly in $LIFERAY_HOME/osgi/modules);

To start testing the plugin you need:

  1. clone this repository
  2. build project (with Maven or Gradle)
  3. deploy OSGi module (salesforce-client-gogoshell-command-$version.jar) to Liferay instance

From your terminal execute the commands:

$ git clone https://github.com/amusarra/salesforce-client-gogoshell-command.git
$ cd salesforce-client-gogoshell-command

if use Maven then run this command:

$ mvn clean verify

if use gradle wrapper (gradlew) then run this command:

$ ./gradlew clean deploy

The last commands create a OSGi bundle and deploy directly on your Liferay instance. The deployment directory is set by the property liferay.home for Maven (defined inside the pom.xml), while for Gradle is set by the property auto.deploy.dir(inside the gradle.properties).

The default value for the two properties:

  1. liferay.home /opt/liferay-ce-portal-7.0-ga4
  2. auto.deploy.dir /opt/liferay-ce-portal-7.0-ga4/deploy

If you want could customize the deployment directory in this two way (Maven or Gradle):

$ mvn clean verify -Dliferay.home=$YOUR_LIFERAY_HOME
$ ./gradlew clean deploy -Pauto.deploy.dir=$YOUR_LIFERAY_AUTO_DEPLOY

Check if the bundles are installed correctly via Gogo Shell.

$ telnet localhost 11311
g! lb | grep Salesforce
527|Active     |   10|Salesforce Client Gogo Shell Command (1.0.0.SNAPSHOT)
528|Active     |    1|Salesforce SOAP Client (1.0.1)
true

Both bundles are installed correctly.

2. Gogo Shell Command in action on Liferay 7

Bundles are installed correctly, so we can begin to see how to use commands. The commands that are implemented:

  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

To verify the commands that are available it is possible to execute the command (via Gogo Shell) help | grep salesforceand obtain the following result.

salesforce:login
salesforce:getNewestAccount
salesforce:createAccount

You can display online help for each command typing (on Gogo Shell) help $scope:$command and obtain the following result (for salesforce:login):

login - Login to your Salesforce instance
   scope: salesforce
   parameters:
      String   The your username
      String   The your password + append your API Key

Console 1 – Output of the command help:salesforce:login

Now let’s see the commands in action (in the order shown above).

g! salesforce:login antonio.musarra@gmail.com uuyteTey0PPntoZ9reywPmW1kmoClPDKa

Console 2 – Try login to Salesforce.com (password is fake)

Login successful to Salesforce with username antonio.musarra@gmail.com
Welcome Antonio Musarra
Your sessionId is: 00D20000000m69v!ARAAQO2nNNOWOl9COMVk23Y9U99uZliR0vysheoRbrMd3SRVNtaDP6r5UOE8njs21pODplqA7vXYAsSnj6mYzzloHuSpFZ9z

Console 3 – Result of the login operation

g! salesforce:getNewestAccount 5

Console 4 – Get the last newest five accounts

┌──────────────────────────┬──────────────────────────┬──────────────────────────┬─────────────────────────┬─────────────────────────┬─────────────────────────┐
│Id                        │Account Name              │Web Site                  │Phone                    │Type                     │CreatedDate              │
├──────────────────────────┼──────────────────────────┼──────────────────────────┼─────────────────────────┼─────────────────────────┼─────────────────────────┤
│00120000018683xAAA        │GenePoint                 │www.genepoint.com         │(650) 867-3450           │Customer - Channel       │2014-05-06T11:37:25.000Z │
├──────────────────────────┼──────────────────────────┼──────────────────────────┼─────────────────────────┼─────────────────────────┼─────────────────────────┤
│00120000018683yAAA        │United Oil & Gas, UK      │http://www.uos.com        │+44 191 4956203          │Customer - Direct        │2014-05-06T11:37:25.000Z │
├──────────────────────────┼──────────────────────────┼──────────────────────────┼─────────────────────────┼─────────────────────────┼─────────────────────────┤
│00120000018683zAAA        │United    Oil    &    Gas,│http://www.uos.com        │(650) 450-8810           │Customer - Direct        │2014-05-06T11:37:25.000Z │
│                          │Singapore                 │                          │                         │                         │                         │
├──────────────────────────┼──────────────────────────┼──────────────────────────┼─────────────────────────┼─────────────────────────┼─────────────────────────┤
│001200000186840AAA        │Edge Communications       │http://edgecomm.com       │(512) 757-6000           │Customer - Direct        │2014-05-06T11:37:25.000Z │
├──────────────────────────┼──────────────────────────┼──────────────────────────┼─────────────────────────┼─────────────────────────┼─────────────────────────┤
│001200000186841AAA        │Burlington  Textiles  Corp│www.burlington.com        │(336) 222-7000           │Customer - Direct        │2014-05-06T11:37:25.000Z │
│                          │of America                │                          │                         │                         │                         │
└──────────────────────────┴──────────────────────────┴──────────────────────────┴─────────────────────────┴─────────────────────────┴─────────────────────────┘

Console 5 – Result of the salesforce:getNewestAccount operation

g! salesforce:createAccount

Console 6 – Start the interactive account creation process

Account Name:  Antonio Musarra's Blog
Web Site:  https://www.dontesta.it
Phone:  +39334756787
Do you confirm that I can start creating this account? (y):  y
0. Successfully created record - Id: 0010O00001o0BlVQAU

Console 7 – Result of the salesforce:createAccount operation

g! salesforce:getNewestAccount 1

Console 8 – Get the last one newest accounts

┌──────────────────────────┬──────────────────────────┬──────────────────────────┬─────────────────────────┬─────────────────────────┬─────────────────────────┐
│Id                        │Account Name              │Web Site                  │Phone                    │Type                     │CreatedDate              │
├──────────────────────────┼──────────────────────────┼──────────────────────────┼─────────────────────────┼─────────────────────────┼─────────────────────────┤
│0010O00001o0BlVQAU        │Antonio Musarra's Blog    │https://www.dontesta.it   │+39334756787             │                         │2017-07-26T20:44:55.000Z │
└──────────────────────────┴──────────────────────────┴──────────────────────────┴─────────────────────────┴─────────────────────────┴─────────────────────────┘

Console 9 – Result of the salesforce:getNewestAccount

The SalesforceClientCommand OSGi component is linked to the SalesforceClientCommandConfiguration configuration (via configurationPid attribute).

...
@Component(
 configurationPid = "it.dontesta.labs.liferay.salesforce.client.command.configuration.SalesforceClientCommandConfiguration",
 property = {
 "osgi.command.function=login",
 "osgi.command.function=createAccount",
 "osgi.command.function=getNewestAccount",
 "osgi.command.scope=salesforce"
 },
 service = Object.class
)
@Descriptor("Gogo Shell Command Series for Salesforce "
 + "(Example: create leads, create customers, search, etc.).")
public class SalesforceClientCommand {
 ...
}

Java Code 1 – Definition of the OSGi component implementing the commands.

Figure 3 shows the configuration parameters used by the Gogo Shell commands. As you can see from the configuration, communication tracking between Liferay and Salesforce is enabled. Each SOAP request and response flow is traced to the configured file.

Salesforce Client Gogo Shell Command OSGi Configuration

Figure 3 – Salesforce Client Gogo Shell Command OSGi Configuration

 

<?xml version="1.0" encoding="UTF-8"?><env:Envelope
   xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <env:Header>
  <SessionHeader xmlns="urn:partner.soap.sforce.com">
   <sessionId>00D20000000m69v!ARAAQO2nNNOWOl9COMVk23Y9U99uZliR0vysheoRbrMd3SRVNtaDP6r5UOE8njs21pODplqA7vXYAsSnj6mYzzloHuSpFZ9z</sessionId>
  </SessionHeader>
 </env:Header>
 <env:Body>
  <m:query xmlns:m="urn:partner.soap.sforce.com" xmlns:sobj="urn:sobject.partner.soap.sforce.com">
   <m:queryString>SELECT Id, Name, Type, Website, CreatedDate, CreatedById, Phone FROM Account ORDER BY CreatedDate DESC LIMIT 1</m:queryString>
  </m:query>
 </env:Body>
</env:Envelope>

XML Code 1 – SOAP Request for the salesforce:getNewestAccount operation

<?xml version="1.0" encoding="UTF-8"?>
	<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:partner.soap.sforce.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:sf="urn:sobject.partner.soap.sforce.com">
		<soapenv:Header>
			<LimitInfoHeader>
				<limitInfo>
					<current>4</current>
					<limit>15000</limit>
					<type>API REQUESTS</type>
			</limitInfo>
		</LimitInfoHeader>
	</soapenv:Header>
		<soapenv:Body>
			<queryResponse>
				<result xsi:type="QueryResult">
					<done>true</done>
					<queryLocator xsi:nil="true"/>
						<records xsi:type="sf:sObject">
							<sf:type>Account</sf:type>
							<sf:Id>0010O00001o0BlVQAU</sf:Id>
							<sf:Id>0010O00001o0BlVQAU</sf:Id>
							<sf:Name>Antonio Musarra&apos;s Blog</sf:Name>
							<sf:Type xsi:nil="true"/>
								<sf:Website>https://www.dontesta.it</sf:Website>
								<sf:CreatedDate>2017-07-26T20:44:55.000Z</sf:CreatedDate>
								<sf:CreatedById>00520000003S6PBAA0</sf:CreatedById>
								<sf:Phone>+39334756787</sf:Phone>
						</records>
							<size>1</size>
					</result>
				</queryResponse>
			</soapenv:Body>
		</soapenv:Envelope>

XML Code 2 – SOAP Response for the salesforce:getNewestAccount operation

Resources on Salesforce

If you follow this resources you could see how to use Salesforce SOAP API.

  1. Introducing SOAP API
  2. Cheat Sheets
  3. Force.com SOAP API Cheatsheet
  4. Force.com Web Service Connector (WSC)

I leave you with the link to the demo video showing the Gogo Shell commands in action. Let me know your considerations that are very important to me.

Video 1 – Liferay 7: Demo Salesforce Gogo Shell Command