Creating an Outbound Messaging Notification Service with Eclipse 3.2
Before going through this sample, please familiarize yourself with Outbound Messaging by reading the entire Outbound Messaging topic in the Force.com Web Services API Developer Guide.
The Eclipse Web Tools Project provides excellent tools for working with web services. In this sample we will demonstrate how to create an Outbound Messaging (OM) service from scratch in Java using the Eclipse platform.
This sample requires that you have Eclipse 3.2 with the Web Tools Project and Apache Axis 1.4 and Apache Tomcat 5.5.20.
Contents |
Software Installation
Apache Axis 1.4 Installation
Download Axis 1.4 [1] and save to your computer. Once the file has been saved unzip the files to a location that you can remember. For this sample we have created a directory named apache at the disk root.
Apache Tomcat 5.5.20 Installation
Next download Apache Tomcat 5.5.20 [2] and save this to your computer. Unzip the file to a location that you can remember. For this sample we will unzip to our Apache folder.
Eclipse 3.2 Installation
Download Eclipse 3.2 [3] and save this to your computer. Unzip the files to a location that you can remember. For this sample we will unziop them to a directory named \Documents\eclipse.
Web Tools Project (WTP)
The WTP is installed using Eclipse's Software Update wizard. To start the wizard, click the Help/Software Updates/Find and Install menu item from the main menu. Select the "Search for new features to install" option on the Feature Updates page of the wizard and then click the next button. You should now be looking at a short list of sites to include in your search. Place a check in the box next to "Callisto Discovery Site" and then click the finish button. Select your preference for which mirror site to use and then click the Ok button.
The Callisto Discovery Site provide access to many different Eclipse projects. We will want to expand the Callisto Discovery Site node so that we can select the appropriate project. Select the "Web and J2EE Development" option. You should notice that there is a warning shown after the selection is made. To ensure that all the dependencies required for WTP are also included, click the "Select Required" button on the left.
When the warning goes away, click the Next button at the bottom to be presented with a license agreement screen. Click the option to accept the license terms then click the Next button to view the details of the software that will be installed. To begin the installation of the selected components, click the Finish button. The appropriate pieces of software will now be downloaded to your computer. This may take 5 or 10 minutes depending on the speed of your connection. When the downloads have completed you will see a screen that allows you to install the newly downloaded bits.
Make sure you select the "Install All" button. When prompted to restart Eclipse, click the Yes button. You now have everyting installed that you will need to create you Outbound Messaging Notification Service.
Eclipse Configuration
Tomcat Server Configuration
We need to configure Eclipse so that it is aware of our Tomcat installation. This is done by configuring some properties on the workspace. To begin click the Window\Preferences... menu item from the main menu. In the list of categories expand the Server item and select the Installed Runtimes item. On the right portion of the dialog you will see a list of the currently installed and configured server runtimes. If you do not already have an entry for Tomcat 5.5 then you should click the Add button on the right. This will display a wizard like the one shown below.
Select Tomcat 5.5 and click the Next button. On the "Specify the installation directory" wizard page, enter the location that you unzipped your Tomcat download to and then click the Finish button.
Back on the Preferences dialog click the OK button to close the dialog.
Creating the Notification Service
Create a Dynamic Web Project
The first step in creating our web service is to create a new Dynamic Web project in Eclipse. From the main menu, click the File/New/Other menu item. You will see a dialog that allows you to select a Wizard for the type of Eclipse artifact we are going to create. To create the Dynamic Web project, scroll to the bottom of the list until you see the Web category. Expand this item and select the Dynamic Web Project item and click next.
On the following wizard page enter the name of the project. For the sample we will use OMTest as the project name. Make sure that you have selected the Tomcat 5.5 runtime and click finish.
If prompted to switch to the J2EE perspective respond by click Yes.
Import the Outbound Message WSDL
When you set up your Outbound Message in salesforce.com a WSDL file describing the expected web service implementation became available. You will need to retrieve this WSDL file and place into your new Dynamic Web project within Eclipse.
Generate WSDL File
To obtain your WSDL you will need to login to your salesforce.com account. Click on the Setup link in the upper right portion of the page to get to the Setup area of the application. From the navigation list on the left, expand the Customize item under App Setup. From here you need to expand the Workflow & Approvals item and select Outbound Messages. You should now see a list of Outbound Messages that have been created in your account.
Find the message that you want to test and click it to bring up the detail screen for that message.
Notice the field in the detail screen labeled "Endpoint WSDL". Clicking this link will cause your Outbound Message WSDL to be generated and shown in the browser. To save the actual WSDL file, right click the "Click for WSDL" link and select "Save Link As..." if you are using Firefox or, if you are using Internet Explorer select "Save target as...". Navigate to where you web project is located and save the file there. Be sure to give the file an extension of wsdl.
Alternatively, you can just save the wsdl to your desktop. Switch back to eclipse and activate the Java perspective. Drag the WSDL file from the disktop to eclipse and drop it on your project folder. Re-activate the J2EE perspective and we are now ready to generate our web service.
Generate Web Service
If you have followed this sample accurately you should have a Dynamic Web project created within Eclipse and your project should like similar to the one shown below.
Eclipse makes it easy to generate the stubs and skeleton of the web service based on the WSDL file that we created. To create our web service we will need to run the New Web Service wizard.
Start by click File/New/Other from the main menu. In the wizard selection dialog, scroll to the bottom of the list and expand the Web Services item and select Web Service. Click next to continue.
The next wizard page indicates the level of generation that Eclipse can do for you. The top portion is referring to items related to generating and testing the server portion of the web service. Make sure that you drag the little slider to the top for the Service Implementation. This indicates that you want to take the generation process clear through to the testing phase.
The bottom part of the wizard is for generating a web service client for this web service. We don't want to do this at this time, so make sure the little slider is placed at the lowest point and the caption above the diagram says "No client".
Back at the top of the page, select "Top down java bean web service" from the Web service type list. For the service definition we will want to use the wsdl file that we generated earlier. To specify this file, click the browse button to the right of the text field. On the resulting screen, click the Browse button here also. Find your project in the list of projects and expand it to find the wsdl file that you saved previously.
Click OK to close the wsdl select dialog and then click OK again to close the Service Definition selection dialog. Finally, make sure that the "Publish the Web Service" check box at the bottom of the wizard page has a check mark in it. Click next. Accept the defaults on this screen and click next again.
Eclipse now generates all the java files necessary to implement you Outbound Message Service. If you have configured the Tomcat settings in Eclipse correctly and your Tomcat server is not yet running, you will see this screen.
Clicking the Start Server button will start the Tomcat server and allow the web service to be deployed to it. Click next to bring up the screen shown below.
This screen gives you the option of launching the Web Services Explorer for Eclipse. Let's click Launch now. The Web Services Explorer is opened in your browser. You can book mark this page to easily return to it later.
Click the finish button to dismiss the New Web Service wizard. When the wizard closes you should be returned to the Eclipse interface and an editor should be opened on the NotificationBindingImpl.java file.
Implementing Your Service
Now that the skeleton has been generated you can right your own code to handle the Outbound Message call that is received from the platform. This happens in the NotificationBindingImpl.java file. This file is yours to customize and will not be overwritten on subsequent processing of your wsdl. You might modify your outbound message specification at a later time. If you do, you will need to re-generate and process your wsdl using the same steps that were outlined above. To preserve your changes you will need to check the "Merge generated skeleton file" option in the Web Services/Resource Management preferences.
For our sample we are going to make a simple change to the NotificationBindingImpl.java file. Instead of returning false, indicating that we did not receive the notification, we will change the return value to true. In addition, since we are going to test this from eclipse, we will add a simple System.out.println() statement so that we can see that the service was invoked from within the IDE.
Just before the return statement enter System.out.println("Hello World");. To demonstrate accessing the data that was sent on the notification, enter System.out.println(notification[0].getSObject().getName()); just before the return statement. Your NotificationBindingImpl.java file should now look like this:
Save the file.
Testing Your Service
Testing can be a bit of a tricky wicket if you are not developing on a machine that is accessible from the internet. Following the sample, we have deployed our web service to localhost:8080. It is not possible for the salesforce.com servers to make a request to that address.
We need another way to test the web service. The method outlined below is meant to be more of a validation than a full test. You should always do final testing on the actual server that will be handling the outbound messages.
You'll recall, if you've been following along, that at one point in the web service generation process we launched the Web Services Explorer. We will be using this to test our web service.
Let's take a look at the interface that is provided.
On the left are the services defined for our endpoint. On the right is additional information about the services and the place where will be exercising the web service.
To start we need to expand the NotificationBinding node on the left. This exposes the one method available via our web server, the notifications method. Clicking on the notifications node causes the right side of our interface to be replaced with the Invoke a Web Service ui.
What we are seeing on the right is a web form that will allow us to enter the data for a valid web service request as defined by our web service/wsdl. A web service request, when all is said and done, is just an xml document. This interface allows us to enter the interesting parts of the xml document without worrying about the structure, the tags, the namespaces and so on. The links by each of the fields in which we can enter data will display important attributes about that data, such as whether it's required, whether there is a minimum size and so on.
To begin testing with this tool, we will need to enter some information. The elements with the red asterisk are required. In our case we are going to just enter the minimum amount of data to get an interesting result.
Starting with the OrganizationId, we will enter some values. IDs in salesforce.com must be 18 characters in length, so we can enter any 18 characters. Remember, we are just validating that our service is up and running and can respond to requests. We don't care about "real" IDs at this point, we are really going to use them just now. For testing we will enter 123456789123456789 into each ID field - OrganizationId, ActionId and ID. We will also enter a value for the Account name. Scroll down to the bottom of the screen and enter "Joes Account" in the name field.
Now that we have the minimal valid data required we can test the service. Scroll down to the bottom of the right hand screen so that you can see the Go and Reset buttons. Click the Go button. A SOAP message is generated and sent to our web service. Our NotificationBindingImpl class is created and the notifications method is called. On the Web Services Explorer, we can see the results in the Status area. If everything was done correctly, you should see following status.
Now, what about our System.out statement? If you switch back over to Eclipse and view the Console view you should see something similar to this:
