Resource Center

Prerequisites

• eXo Platform 3.0.x with Administrator access
  • The URL of the installation used for this document is http://127.0.0.1:8080
• Convertigo Proxy for eXo Platform available here

Introduction

The interoperability effort between eXo and Convertigo brings the Convertigo InteractionHub to eXo Platform, so third party applications can be integrated into an eXo dashboard in a non-intrusive way. This tutorial will explain how to install Gadgets that are hosted on a Convertigo Server running in the cloud.

Convertigo is particularly interesting for eXo and the GateIn community because the Convertigo Studio and Convertigo Enterprise Mashup Server (EMS) provide a complete solution to develop and deploy gadgets and web services using existing applications. With Convertigo and its connectors, a developer could revamp a Web Application and expose it as an OpenSocial gadget, or take a mainframe application and, in few clicks, expose the data and the user interaction as REST Web Services to allow new applications to consume them.

In the following example, we will build a new application exposed in an eXo Platform portal dashboard. The dashboard page is comprised of three different gadgets, or business sources:

• A list of leads from Salesforce.com
• Address information from US Directory website
• Maps from Google Maps

All these applications will be wired together on the client side using the Convertigo InteractionHub, allowing the user to show the address of a salesforce.com contact in Google Maps when he clicks on the US Directory Gadget.

The final page will look like this:

This tutorial will not cover how to develop these gadgets, because the Convertigo team has already developed and deployed them on a server hosted on the cloud. In this tutorial you will learn how to consume existing gadgets and add them to your eXo Platform instance. If you want to learn how to build Gadgets using Convertigo you can do it from the Convertigo Web site.

How to Use Convertigo Gadgets in eXo Platform

Installation of the Convertigo Proxy in your eXo Platform installation

Since Convertigo gadgets are hosted on a remote server in the cloud, it is necessary to install a Convertigo Web Application in your existing eXo Platform instance. This application is used as a proxy between your local instance and the Convertigo EMS. To do this just download the convertigo.war available here and deploy it in your application server.

If you are running, eXo Platform 3.0.x with Tomcat, copy the convertigo.war in the following folder (this could be done in a running system): $EXO_INSTALL/eXoPlatform-[version]/bin/tomcat6-bundle/webapps

Once you have deployed the application you should be able to check that it is installed using the following URL:

• http://127.0.0.1:8080/convertigo/index.html

The "Convertigo EMS (Enterprise Mashup Server)" application should be visible, and look like this:

The Convertigo EMS contains all the projects that were developed and deployed for this demonstration. This is the main entry point to manage applications and gadgets; this is also where we will be registering the gadgets in eXo and where the business logic will be executed.

Let's take a look at the content of this application.

The "Convertigo EMS" contains all the Convertigo applications that we will be using in this how-to, and are managed using "projects". Each project contains a list of "transactions" that are entry points, accessible as gadgets. Depending on the application requirements, it is possible to use different transactions. In our case where are using the following projects and transactions:

• Project : SalesForce
  • Transaction: Login
  • Description: Web Integration Project that captures content from the SalesForce site and exposes it as a list within a gadget.
• Project usDirectory:
  • Initial Transaction: usDirectory
  • Description: Web Integration Project that captures content from usDirectory.com and exposes the information within a gadget.
• Project Lib_GoogleMaps:
  • Initial Transaction: ShowMap
  • Description: Use the Google Maps API to show maps and pin addresses sent as parameters.
• Project interactionHub:
  • Initial Transaction: GateIn
  • Description: This gadget is used as a listener for all the events in a page containing gadgets. The developer of the Gadget defined in the Convertigo studio all the possible interaction supported by the gadgets.

When you put all these gadgets on a page the InteractionHub will automatically wire the gadgets together to provide the following features:

• The Sales Force gadget will send the company name, city and state of the selected lead to the US Directory gadget.
• The US Directory gadget, will show the list of street address entries based on the parameter sent by Sales Force. The user can view the US Directory an address of the US Directory entry, but can also directly update the Sales Force lead with the selected address.

In the current version of the Convertigo Interaction Hub for GateIn, the wiring is done during the development phase in the Convertigo Studio. But it is important to notice that Convertigo is currently working with the eXo and the Red Hat/JBoss community to embed the Interaction Hub in the GateIn portal, enabling GateIn to perform powerful late binding of applications.

Now that we have looked at the various projects that contain the gadgets used in our sample dashboard, let's register them in eXo Platform.

Register Gadgets into eXo Platform

Convertigo EMS provides 2 ways to integrate gadgets inside eXo, with either a simple remote URL or by providing the gadget code that could be registered inside the product. We will be use the second approach where we will copy the source of the Gadget inside the eXo Application Registry.

For this we will be using the eXo Acme Social Intranet instance located at http://127.0.0.1:8080/portal/private/intranet (connect with user root and password gtn).

Register the SalesForce Gadget

• Inside the Convertigo EMS Project page click on the "SalesForce" project
• Copy the Gadget source code using the folllowing steps
  • Select the Login transaction
  • Click on the gadget URL button
  • Copy the gadget source code
    
    
• Inside eXo Platform: go to the Application Registry by selecting in the portal menu: My Spaces > Portal Administration > Application Registry
• In the Application Registry click on the "Gadget" tab
  
  
• Click on the "Create a new gadget button"
• Enter a new gadget name : SalesForce_Leads (be sure to enter this exact name since this is what is stored inside the InteractionHub configuration)
• Copy the XML source of the gadget in the source text area. When working with Convertigo it's a best practice to set the gadget's title attribute in the XML, to the same value name, so putSalesForce_Leads as the title.
• Save the gadget
• Click on the "Click here to add into categories" link
• Select the "Gadget" category

The SalesForce gadget is now registered in your application registry and available to eXo Platform users. You can now add the other gadgets.

Register Other Convertigo Gadgets

Using the approach described above you can now create new gadgets using the following transactions:

• US Directory project, select gadget code for the usDirectory transaction. Register this gadget with the name: usDirectory
• lib_GoogleMaps project select gadget code for the ShowMap transaction of the GoogleMapsConnector connector. Register this gadget with the name: GoogleMaps
• Interaction Hub project, select the gadget code for the GateIn transaction. Register this gadget with the name: InteractionHub
• As a reminder you should already have registered the SalesForce application using a gadget named SalesForce_Leads

Use the Convertigo Gadgets to Build a Composite Application

You can now use these gadgets within your dashboard or inside a portal page. Since some of the applications (such as SalesForce) have a lot of data, it is better to build a new portal page and arrange the gadgets to build a composite application.

Create a Business Application page

• Go to the Intranet Social Home page http://127.0.0.1:8080/portal/private/intranet/
• Create a new Page by clicking in the eXo Portal Toolbar: Site Editor > Add New Page
• Enter the CRM as node name and CRM Application as display name
• Click Next
• Select the Template of the page
  • In the drop down list select "Mix Page Config"
  • Select "One Row Two Columns Layout"
• Click Next
• You are now ready to add the various gadgets on the page
• Add the InteractionHub gadget on the top section
• Add the SalesForce_Leads under the Interaction Hub gadget
• Add the usDirectory gadget on the left column at the bottom of the page
• Add the Google Map gadget on the right column at the bottom of the page.
• Your page should look like the following screen:
  
  
• Before saving the page, you can remove the portlet decoration to create a better user experience. To achieve this, click on the portlet's edit button (the pencil when you roll over the portlet) and uncheck the Show Info Bar option.
• Next, save the page by clicking on the save button in the "Page Editor" dialog.
  
  
• Your page should now look like
  
  

Using the Gadgets and Interactions

By clicking on the in the Sales Force application. the gadget will send an event to the US Directory application to load all the information related to the lead you have selected.

Then, click on the Google Map button in the US Directory application. This will send an event to the Google Map application to show the address of the selected lead.

Conclusion

In this how-to you have learned how to:

• Register gadgets developed and deployed by Convertigo inside eXo Platform
• Use these gadgets with the Convertigo InteractionHub to build composite application

You can now learn more about the Convertigo development experience on their Web site:

• http://www.convertigo.com/
• Convertigo Developer Network