Tuesday, August 10, 2010

Integrating GWT applications into the Google Apps Marketplace

This article examines how easy it is to integrate a GWT application into the Google Apps Marketplace. Application stores are becoming the de-facto method to distribute software. It is a clean, secure and hassle free method of introducing users to a large software base. In the near future Google will be releasing an application store for chrome to distribute software, and it currently offers a business software alternative for its Google Apps users. This article takes a look at how easy it is to change an existing GWT application for integration into the Google Apps Marketplace.

Google Apps is the term used for a suite of applications that run under your own domain name. You get the Mail, Calendar, Documents, Sites and overall Google experience but it is configured to run on your own domain. A recent extension to this is the Google Apps Marketplace which allows anyone with a useful application, to integrate into the Google authentication and authorization system. Thus allowing the user a seamless experience through their current Google applications and any third-party applications configured to run on this system. The power of this feature cannot be underestimated.

Opening up the Google Apps world to all application developers provides developers with a easy to integrate revenue stream and customer marketplace. Whilst providing the end users with an easy to use configure application store for Google Apps. This is a win, win situation. No whilst it is easy to see how this will be a benefit for web application developers it might be interesting to see how easy it is in practice to integrate your application into this system.

Background Reading

You didn't think I was going to do everything did you? I would seriously recommend reading this article first to get an overview of what we are trying to do here. This gives an overview from a development perspective of what we are trying to achieve.

Writing your First Marketplace App using Java: http://code.google.com/googleapps/marketplace/tutorial_java.html

In addition this page gives a rough overview of the whole process including development, but also submission to the Google Apps Marketplace:

On your marks...

The application I am discussing is, my often touted, Simple CRM application, Soho CRM (http://sohocrm.appspot.com). It is a small business focussed CRM system aimed at the small business market. The application is developed in GWT, using Java, and is deployed to Google App Engine.

As you can see from the picture the application looks like a Google application with the familiar toolbar users come to expect. What follows is the process involved in converting this to fit into this architecture.

Step 1 : Create Vendor Profile
In order to get anywhere in this system you first need to become a vendor. The overview page here, http://developer.googleapps.com/marketplace/getting-started, explains how to do that in the section "Becoming a Vendor".

Step 2 : Download Code

Google provides us with an example application which you can deploy to Google App Engine and integrate into your own vendor profile in the Google Apps Marketplace. This code is located here:

Step 3 : Integrate code
If you understand theory then the developer resource above would have been good enough for you. I prefer real code so I can create my own internal models of what is happening during this process. To get started I copied all the code in the directory:


to a marketplace pacakge in my own GWT code


I also flattened the package all files required existed in this package and it wasn't distributed amongst several packages like it is in the example.

I also renamed the OpenIdServlet class to GoogleAppsOpenIdServlet because regular open id users can already log into the application and I didn't want the classes to become confusing.

GuiceModule.java: This file is in the downloaded code but not in the integration above, because this application already had GUICE configured. I simply took the code from the HW example and integrated it with my own.

ConsumerFactory.java: This file was excluded because again it wasn't required.

A final step in this process is integrating all the required libraries. The downloaded code comes with a library folder to make this easier.

Step 4 : Map Servlets
Examination of the web.xml file reveals the servlets you need to map. These can either be setup here, or if you have a code alternative set them up there. You will need to record what URL is used as the OpenID authenticator as this is sent to the Google Apps Marketplace when you install your application.

Step 5 : Create the manifest file
By this stage your application will be ready for installing. You just now need to configure Google Apps Marketplace to accept your application. The first step in this process is creating the manifest.xml file. This file is a configuration file which tells Google Apps the name and description of your application; how to authenticate; and what Google Services the application should be given access to. The manifest is quite an extensive piece of kit so the full explanation on the file is listed here:

Creating the manifest: http://code.google.com/googleapps/marketplace/manifest.html

Step 6 : Getting Excited - We are almost there!!!
The next stage is to add the application to the Google Apps Marketplace. The vendor profile was created earlier, so after navigating to that URL : https://www.google.com/enterprise/marketplace/viewVendorProfile
You should now be able to see a button which says "Create new listing". Click that button and fill in your application details.

Make sure you check the button "My product may be directly installed into the Google Apps domain". This then reveals the Manifest box in which you will place the manifest.xml code to set the application up.

After completing all the sections click "Save and Preview". On the screen that follows do not publish your application as you will first need to test it.

Step 7 : Grab oAuth Key and Secret
Back on the application listing page of your vendor profile your application should now be listed. If the stages above were completed correctly then a new link "View OAuth Consumer Key" will show under the application. Click this and record this information as you will need it to authenticate your application.

Step 8 : Add oAuthKey and Secret into web.xml.
If you are following the Hello World example then you will need to place the OAuth Key and Secret into the web.xml file. This correctly identifies your application to Google which will then authorise you to view the users OpenId details.

Step 9 : Integrate the user logon process into your application.
In the doPost method of the OpenIdServlet you can see what the application does after authenticating a user. In this section you need to introduce whatever code you need to setup the logged in user. In my code this involved setting the session.user variable to the current user. Then simply redirect the user to the application home page.

Step 9 : Test
If all has gone well then you should be ready to perform two important tests:
1) Installing this application on your domain.
2) Testing the application as an end user.

Installing: Is easy enough. Go to the marketplace home page for your application and click the button "Add It Now". This simply takes you to the domain administrator page for this application and gives you the option of installing the application or not.

Testing: Once installed simply log into your domains mail application and on the right hand side where the more dropdown shows your application should now be visible.

This is where most of my time was spent developing this application. I haven't worked on many OpenID projects so understanding the concepts was a large part of this, but the Hello World example given was very helpful in solving the problems involved. This article, although long, is a cursory look at the steps involved. Any readers wanting help, or more explanation on any of the steps, please let me know and I would be glad to help.


  1. Great article, thanks a lot! This is exactly what I'm searching for ;)

  2. Hey there
    I'm very new to the whole google app, marketplace ecosystem. Wanted to confirm my understanding.

    1. I have a sample app deployed to Google App Engine (GAE) lets call this app 'MyHelloWorld'. This app can be accessed on the appspot.com url without needing any login
    2. I want to be able to add this app i.e. 'MyHelloWorld' to the Google app Marketplace (GAM) so that all the users on my domain can access the 'MyHelloWorld' app from the top nav.

    Stuff which I'm not sure about
    1. The sample code for single-sign on given on the GAM needs to be integrated with the 'MyHelloWorld' App - right?
    2. The manifest entry in the listing created on GAM is used to identify the appropriate app.
    3. Once the setup has been done the users in my domain will be able to access the 'MyHelloWorld' app from the top nav

  3. 1. Correct.
    2. Correct.
    3. Correct.

  4. Hey Gene
    Thanks for the quick response.
    Have another question
    1. Why is the single sign on required even when the hello world app does not need it? Is it just a mandatory requirement which google has assuming more real world app will have a sign in functionality

    Thanks a lot man. Solved a lot of confusion for me

  5. I think in most instances the Single Sign on functionality will be required, and it is up to you to implement it on your site, so if you don't require it, don't implement the sign on code at your end.

    For example. Google redirects you to a specific login URL which you specify in the manifest. [S} You then authenticate that user in the back end with Google's servers, then you might create a session object setting the application up as being logged in for that particular user. If you don't require any login functionality. Simply skip the part after [S}.

  6. Gene
    Did you encounter any errors with guice provisioning while running the sample app?
    I'm getting errors on the app engine - mentioned the details here

  7. How would integrate with a GWT app as opposed to GAE or servlet-GET