dbMundada / liferay-crm-sample-integration

A few weeks ago I saw the post Liferay Salesforce.com integration on the Liferay forum of the year 2010. Certainly the post is a little old-fashioned and personally at that time I didn't even know about Liferay's existence. The request of Nicolas Raoul (author of the post) was this: Hello all, Is there any way to integrate Salesforce.com into a Liferay portal without writing code? If not, a solution would be to create a new portlet that calls Salesforce.com's Web Services, but I am wondering if anything already exists that I could just reuse. I am not asking for perfect integration of everything, but if you know of a portlet that shows some data or allows any Salesforce.com action that would be great already :-) Thank you! Nicolas Raoul I took the challenge in hand and throughout this article we will look at the modern approach (Liferay 7/7.1/7.2 & OSGi) of the solution I developed to integrate OSGi, Liferay 7/7.1/7.2 and Salesforce.com as bundles. [Tweet "Not sure how to integrate #Liferay 7/7.1/7.2 and #Salesforce? I'll explain how to implement integration in an OSGi context."] 1. What you need to know first All the developed software referred to is available on my GitHub account which specifically covers two repositories Salesforce SOAP API Client OSGi Bundle and Salesforce Gogo Shell Command Client. For your integration tests, remember that you must have at least one Salesforce.com Developer account (free of charge). The resources to follow are in-depth points that I recommend reading after reading this article. Introducing SOAP API Cheat Sheets Force.com SOAP API Cheatsheet Force.com Web Service Connector (WSC) The two OSGi bundles are compatible with Liferay 7/7.1/7.2 and Apache Karaf 4.x and in general can be installed in any container that complies with OSGi R6 specifications. The latest version of the Salesforce SOAP API Client OSGi bundle is publicly available on the Maven Central Repository. 2. What you need to build We are fortunate enough, we do not need a lot of effort in terms of code development. The only fundamental component to prepare is the one that will allow us to talk to Salesforce.com. The tasks to be done are: create the OSGi bundle responsible for communicating with Salesforce.com; create the OSGi bundle that will use the component above to perform actions on Salesforce.com. We have identified the "pieces of software" that we need to realize and at the end of the construction we should find ourselves in a situation analogous to that shown in Figure 1. Figura 1. Integrazione Salesforce.com in contesto OSGi The diagram in Figure 1 shows the two Salesforce SOAP API Client and My Salesforce Bundle App bundles. The first bundle is the one that will communicate with Salesforce.com through the SOAP APIs (exposed by the latter), the second bundle uses APIs instead Java exported from the first bundle in order to perform actions on Salesforce.com (such as login, account creation, etc.). 3. The Salesforce SOAP API Client bundle Salesforce.com exposes a set of APIs via SOAP and REST that allow external systems to interact with it. In this solution I chose to use the SOAP API. Salesforce.com provides the Force.com Web Service Connector (WSC) tool that creates the Java stubs needed to communicate via SOAP and this greatly facilitates the process of creating our OSGi bundle. Our OSGi bundle will show the following set of Java APIs that can then be used by any other bundle that will need to interact with Salesforce.com. com.sforce.soap.partner.* com.sforce.soap.enterprise.* com.sforce.async.* come.sforce.bulk.* com.sforce.ws.* In the article How to Build a Salesforce SOAP API Client OSGi Bundle you can read all the details related to the construction of the OSGi bundle responsible for communication via SOAP with Salesforce.com and for exporting the Java APIs that will then be publicly available within the OSGi container. 4. The Salesforce App bundle Once we have the Salesforce.com Java API available in our OSGi container (thanks to the salesforce-client-soap v1.2.0 bundle we created earlier), we are able to implement all the integrations we want with Salesforce.com. As an example application, and for reasons of simplicity, we could make a series of OSGi commands that perform the following actions on Salesforce.com: salesforce:login: Login on Salesforce.com salesforce:createAccount: Create an account salesforce:getNewestAccount: Return the list of the new account Article Liferay 7 Salesforce.com Gogo Shell Command Client explains in detail the implementation and use of this specific example integration bundle with Salesforce.com. The two videos published on Antonio Musarra's Blog YouTube Channel show the integration solution in the Liferay 7 and Apache Karaf context in action. 5. The next step Thanks to the OSGi approach we have been facilitated in implementing the solution to the integration problem between Liferay and Salesforce.com. The solution of creating an OSGi Salesforce SOAP API Client bundle responsible for communication via SOAP with Salesforce.com and exporting the Java API in the context of the OSGi container, makes this component very "reusable" (in fact we installed on Liferay and Apache Karaf) . The next scenario of integration could be similar to what I had a few years ago illustrated in the article Introduction to the Hook - First episode, where, however, the CRM system was SugarCRM, in this new scenario it will be Salesforce.com instead. I would like to receive your comments regarding the solution adopted.

Liferay 7.1 The CRM Integration Quick Start

1. Overview

This simple project was born with the aim of providing the basis for a "gym" with the aim of creating a system of integration with the most common Customer Relationship Management (CRM) systems.

CRM systems are:

• Salesforce.com (SF or SFDC) - https://www.salesforce.com
• SuiteCRM - https://suitecrm.com/
• OpenCRX - http://www.opencrx.org/

The implemented use case is very simple, to then kick off your fantasy. The case implemented in this project allows, when a new user is registered, to send it to the CRM system, where it will be created as Lead. The figure below shows the integration case implemented in this project.

Figure 1 - Integration scenario Liferay 7.1 and CRM System via API

For integration with Salesforce, this project uses as dependency the salesforce-client-soap bundle (last version is 1.1.0) whose implementation is available here https://github.com/amusarra/salesforce-client-soap

The salesforce-client-soap bundle installation on the Liferay instance is an important requirement in order to make integration with Salesforce work.

In this project the following topics of the Liferay 7/7.1 platform were addressed, which are:

• OSGi and modularity - https://dev.liferay.com/develop/tutorials/-/knowledge_base/7-1/osgi-and-modularity
• OSGi services and dependency injection with declarative services - https://dev.liferay.com/develop/tutorials/-/knowledge_base/7-1/osgi-services-and-dependency-injection-with-declarative-services
• OSGi Configuration - https://dev.liferay.com/develop/tutorials/-/knowledge_base/7-1/making-applications-configurable
• Portal Instance Lifecycle
• Categorizing the configuration - https://dev.liferay.com/develop/tutorials/-/knowledge_base/7-1/categorizing-the-configuration
• Model Listener - https://dev.liferay.com/develop/reference/-/knowledge_base/7-1/model-listener
• Custom Fields - https://dev.liferay.com/discover/portal/-/knowledge_base/7-0/custom-fields
• Message Bus - https://dev.liferay.com/develop/tutorials/-/knowledge_base/7-1/message-bus

At this time the project includes only complete integration with Salesforce. For the rest of the CRM systems (SuiteCRM and OpenCRX), it is only necessary to implement the API layer that communicates with the target system.

This current version of the project has been tested with the Liferay 7.1 Community Edition GA1.

2. Architecture

A scheme is better than a hundred words! The figure shows the macro architecture adopted to achieve the integration between Liferay and the most common CRM systems.

The components offered by the Liferay platform used are:

• Model Listener (User listener)
• Message Bus
• OSGi DS Components
• OSGi Configuration

Figure 2 - Liferay CRM Sample Integration - Architecture

In short. For each new user who registers (Login Form => Create Account) on Liferay, the user model listener is triggered which in turn sends a message to a specific destination via the message bus, the listener receives the message that once processed sent to the specific CRM system through the APIs.

The figure below shows the diagram of the modules and the relationships between them.

Figure 3 - Liferay CRM Sample Integration - Component diagram

The table below describes the responsibility of each module.

Name of the module	Description
crm-sample-integration-api	This module defines a subset of APIs representing the operations that can be performed on the CRM system.
crm-user-model-listener	This module contains the OSGi component that implements the Model Listener of the Liferay user entity. This module communicates exclusively with the Message Bus and not directly with the CRM systems. This module also includes the OSGi configuration that specifies which CRM systems to enable for integration.
crm-user-message-bus	This module contains the definition of the message destination (one for each CRM system) and the implementation of the related message listener. Receives and processes messages sent by the crm-user-model-listener module. In particular, this module is related to the CRM API module.
crm-user-custom-fields	This module contains a component of the Portal Instance Lifecycle Listener which is responsible for creating some custom fields on the user entity.
salesforce-sample-integration-service	This module contains the API implementation defined in the crm-sample-integration-api module for the specific Salesforce CRM system.
suitecrm-sample-integration-service	This module contains the API implementation defined in the crm-sample-integration-api module for the specific Suite CRM system.
opencrx-sample-integration-service	This module contains the API implementation defined in the crm-sample-integration-api module for the specific OpenCRX CRM system.

Each specific implementation of the CRM API also contains the OSGi configuration necessary to set up, for example, the service end point, username and password of the CRM system.

Only the salesforce-sample-integration-service module contains the implementation of the CRM API that lets you communicate with Salesforce. For the rest of the modules I leave the specific implementation to you.

3. Configuration

There are two configurations with scope at the instance (or company) level and which are:

• CRMGroupServiceConfiguration: This configuration allows you to set with which CRM system to enable integration.
• CRMClientGroupConfiguration: For each implementation of the CRM API there is a specific configuration that in this are three.
  • SalesforceClientGroupConfiguration
  • OpenCRXClientGroupConfiguration
  • SuiteCRMClientGroupConfiguration

The following figures show each of the configurations indicated above.

Figure 4 - Liferay CRM Integration Sample - Enable CRM Service Configuration

Figure 5 - Liferay CRM Integration Sample - OpenCRX RESTful Client Configuration

Figure 7 - Liferay CRM Integration Sample - Salesforce SOAP Client Configuration

Figure 7 - Liferay CRM Integration Sample - SuiteCRM Rest Client Configuration

4. Integration in action

At this time the available integration is the one with Salesforce. Once you have enabled the integration with Salesforce and set the connection parameters to your Salesforce instance, you should get the expected result, that is, once you have added a new account on Liferay you should have the relative Lead on the Salesforce and on Liferay you should see the custom field updated.

Figure 8 - Liferay CRM Integration Sample - View User Account

Figure 9 - Liferay CRM Integration Sample - View Lead on Salesforce

Following is an example of logs that highlight the operations of integration with the CRM system.

2018-10-23 10:06:46.084 DEBUG [salesforce/send_lead-1][SalesforceUserRequestMessageListerner:42] Action: add
2018-10-23 10:06:46.085 DEBUG [salesforce/send_lead-1][SalesforceUserRequestMessageListerner:43] Receive this payload
[WSC][Thread.run:748]Log file already exists, appending to /tmp/traceSalesforceEnterprise.log
2018-10-23 10:06:46.317 DEBUG [http-nio-8080-exec-3][CRMUserModelListener:60] Get Configuration interface it.dontesta.labs.liferay.crm.listener.user.configuration.CRMGroupServiceConfiguration for companyId: 20099
2018-10-23 10:06:46.318 DEBUG [http-nio-8080-exec-3][CRMUserModelListener:73] CRM Salesforce enabled: true
2018-10-23 10:06:46.319 DEBUG [http-nio-8080-exec-3][CRMUserModelListener:75] CRM SuiteCRM enabled: false
2018-10-23 10:06:46.320 DEBUG [http-nio-8080-exec-3][CRMUserModelListener:77] CRM OpenCRX enabled: false
2018-10-23 10:06:48.606 INFO  [salesforce/send_lead-1][SalesforceBaseService:95] Successfully created lead with id of: 00Q0O000016m5g3UAA.
2018-10-23 10:06:49.222 INFO  [salesforce/send_lead-1][SalesforceUserRequestMessageListerner:95] User custom fields updated for user: [e-mail]
2018-10-23 10:06:49.223 INFO  [salesforce/send_lead-1][SalesforceUserRequestMessageListerner:75] Lead created on CRM target system with id: 00Q0O000016m5g3UAA

Console 1 - Log of CRM Integration components in action

Resources

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

1. Salesforce - Introducing SOAP API
2. Salesforce - Cheat Sheets
3. Force.com SOAP API Cheatsheet
4. Force.com Web Service Connector (WSC)
5. openCRX 4.1 Documentation
6. SuiteCRM - API Version 8

Video 1 - Liferay 7: Demo Salesforce Gogo Shell Command

Project License

The MIT License (MIT)

Copyright © 2018 Antonio Musarra's Blog - https://www.dontesta.it , [e-mail]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.