Getting Started With the SPML Gateway for Salesforce.com (using a servlet) Solution

This solution shows how you can use the SPML Gateway to provision users in Salesforce.com. You need to have an account set up with Salesforce.com. If you don't have one already you can create a developer account.

Setting up a Salesforce.com developer account.

If you already have an account you can skip this part. If not go here Salesforce Developer Account. And fill out the form. This will set up an account for you.

Now you need 4 values to configure the connectivity information for the Gateway.

You need the URL for the location of the enterprise web service for Salesforce.com You need the Username and Password for the Administrator account (if you set up the developer account your initial account will also have the administrative permissions). And finally you need a special Key that is emailed to you.

To get the URL for the location of the enterprise web service you need to need to download the Enterprise WSDL. First go to the setup and open up the App Setup folder. In it you will find the API label. Select it and you will get a screen that shows a bunch of download links. Select the Download Enterprise WSDL link. This will give you a WSDL file. At the bottom of the WSDL file you will find the service definition. For me it is "http://www.salesforce.com/services/Soap/c/13.0". (Note: the gateway currently does not support https so you will need to only use http).

Now you have the URL.

The username and password are the same ones that you use to log into Salesforce.com.

For the key you will need to go to the setup and open up the My Personal Information folder and then select the "Reset My Security Token". This will email you a new key.

Now that you have the 4 values you are ready to configure the connections.

This solution is implemented as a Servlet. It has been tested in Glassfish but it should work in any servlet container.

The following SPML operations are supported:

Architecture of the Servlet Solution

This gateway is implemented in a servlet. The messages will arrive via http to the url of 'http://localhost:8080/spmlv2/Provisioner'. The request will be parsed using XPath and DOM to pull out the relevant information and then translated into the corresponding HTTP request to salesforce.com. The listTargets will query the metadata definition of User so that all fields that have been configured for a User in Salesforce will automatically be part of the schema definition. The same is true for the add, modify, lookup, and search operations. The servlet also has a simple configuration page located at "http://localhost:8080/spmlv2 that can be used to setup the connectivity information as described above.

Installing the Salesforce.com Solution

Watch this video for an overview on how to install and run a quick test of the SPMLv2 Gateway for Salesforce.com

This procedure assumes that you know how to deploy a war file into an application server.

To Install the Salesforce.com Solution

1. Download the war file that contains the solution.
2. Deploy the war file into glassfish (or any servlet container)

The source code is also available as a Netbeans project. You can get that here.

Setting up the connectivity information

Now that you have the war file deployed you can own up your browser to http://localhost:8080/spmlv2/

You will see the following screen:

Fill in the values and Save it.

Testing the Salesforce.com Solution

You can find here (this netBeans project is located here) a simple swing based tester. Nothing special. Just something that can help test out your SPMLv2 service. It creates an XML template for you to fill out. Invokes the service. And then shows you the raw response. Again nothing special, but something that can show you whats going on in your SPMLv2 Service.

Just download the zip file, expand it into a directory and open the SPMLExplorer.jar file (double clicking on it should do the trick). If you have your .jar extension files set to run java -jar it should start up. If not you can always run from the command line "java -jar SPMLExplorer.jar".

The application first requires you to set up the location of the target. This is done by "File --> Open Target.." from the main menu. This will open up the below dialog box. Where you enter in the URL for the SPMLv2 Service. The default location of the servlet on your local machine will be "http://localhost:8080/spmlv2/Provisioner". You can ignore the username and password for now. This will be something for a future enhancement.

Now that you have the target set. Make sure that it is selected and then pick the operation you want to call by selecting it from the "Call --> listTargets" for example from the main menu. This will insert the xml template into the upper window. You can now change the XML content to match your scenario and then finally you can click on the Execute Button to run the command to see the results in the bottom window.

Salesforce.com Solution Overview

In the zip file you will find one project.

The SPMLv2forSalesforce project contains a group of files that implement the supported SPML operations.

The following screen capture shows the SPMLv2forSalesforce project in the NetBeans IDE.

There are 6 files that are interesting. The three java files Salesforce.java, Provisioner.java, and NamespaceContectImpl^?.java. The index.jsp and the two deployment descriptors web.xml and sun-web.xml.

Salesforce.java implements the http client to Salesforce.com. It constructs the xml documents to post and then parses the return values. Provisioner.java implements the SPMLv2 part.

Index.jsp implements a very simple configuration screen that allows you to configure the 4 connectivity parameters. It saves these into a connectivity.xml properties file that is then used by Salesforce.java to get the parameters to connect to salesforce.com.