Deploying CA Plex/WebClient applications on the IBM WebSphere Application Server can be more challenging that on Tomcat – although the process is largely the same conceptually, WebSphere has more features, options, and versions available. This guide is written with IBM i in mind, but the steps can be generally applied to other versions of WebSphere running on Windows, Linux, AIX, or zOS. Please note that this guide only covers a small portion of total subject of WebSphere administration – for further information, please visit IBM. One good link to start from is http://www.ibm.com/developerworks/websphere/
This guide has been written by Matt Fleming, Application Consultant and WebClient support technician. Matt can be reached by contacting WebClient support, or at mfleming@adcaustin.com.
Preparation
The first consideration that you will want to address when deploying WebClient with WebSphere on the IBM i is that you have compatible versions. WebClient requires Java 1.5 or better. WebSphere versions 6.0 and below do not use Java 1.5 and are therefore not compatible, so you will need version 6.1, 7.0 or higher. Additionally, you will need to verify that the version of i5 OS is using Java 1.5 or better. Furthermore, you will want to verify that all of IBM’s recommendations for deploying WebSphere are met, including the correct version of the operating system on the IBM i.
Once you have verified the versions, the next thing to consider is the differences that exist between the windows based deployment in Apache Tomcat or Jetty and the iSeries. To prepare your WebClient application we will help you address these differences.
The first thing to look for is the references that the web project uses for logs and other files. Locate your web project (usually named [projectname]web) in Eclipse, and expand the view of that project in the JavaEE perspective. You should see your WebContent folder there. Expand that, and then the WEB-INF subfolder within it. This is where the J2eeProxy.prop file is that contains the references that we will need to change.
If you are going to be doing continual development, it is best comment out any windows-specific entries that we will change below by placing a # symbol in front of the line. You can then make a separate entry for the IBM i specific values. This approach makes it easy to switch back and forth as you can test on the windows side before packaging for deployment.
Look first for the section entitled “Websydian Server section”. One of the first entries there is ‘websydianserver.ipaddr’; ensure that this has the proper reference to your iSeries. In that same section there are two entries for files. One for the license file and one for the log file. These paths will likely be in windows format by default. These entries ( ‘websydianserver.log.file’ and ‘websydianserver.licensefilepath’) will need to be changed to an IFS file path (or other file system path depending on platform). This file path that you enter here needs to be a path that exists and that is accessible at runtime by the web server.
Next, in the ‘Log section’, you will also need to change the entry for ‘servlet.log.file’. As before, this needs to be a valid IFS path, and needs to be accessible at runtime. Also, ensure that the read/write permissions are set up correctly for these locations so that at runtime these log files can be accessed.
Another good step in ensuring that your WebClient application is ready to deploy is to test it using Jetty or Apache Tomcat before beginning the process of deploying to WebSphere. That will ensure that your application has all of the necessary references that will be included in the deployment of the application, and will help you test minor fixes more quickly. If your WebClient application is missing a reference or has an error it is best to fix it before packaging the application for deployment in WebSphere. Don’t forget to make sure that when you test in Windows, that you comment out the IBM i specific entries with the # symbol, and remove that symbol from the Windows entries. Also make sure that you do the reverse before packaging for deployment to WebSphere.
Packaging for deployment
This step is quite easy. However, as mentioned, it is best to ensure that the WebClient application works in Windows before doing this step. This will help you in troubleshooting and in ensuring that you don’t have to re-deploy multiple times.
After making the preparations listed above (ensuring that the entries in the J2eeProxy.prop are set to the proper IBM i specific values), go to the JavaEE view in Eclipse. Right click on your web project, and go to the Export option. Click on WAR File, and you will see a dialog for the WAR export. For the Web Module value, leave it as the name of your web project; you should not have to change it. Select a path for the destination value where you want the WAR file to be copied to, and click Finish.
This process will build a Web Application Resource file using your WebClient web project, and all of its references. When it is finished the .war file will be ready to deploy to WebSphere.
Deploying in WebSphere
If you have used it before, you know that WebSphere can be a very complicated tool. Even small deployments can be difficult without the proper expertise in the WebSphere product. The good news, however, is that as far as deploying goes, there is nothing specific that WebClient requires that is not common to other project deployments in WebSphere.
Before you begin the deployment, you will need to identify context root for the war file. This information is stored in your web project, so we will get that before continuing. To see this information, right click on your web project (the same one that you packaged in the .war file) and select Properties. In the window that comes up, click on the Web Project Settings in the list on the left. What you will see on the right-hand side of the window is the Context Root. Copy the text from that box, and save it for later reference. You can then cancel out of this window.
The remainder of what needs to be done to deploy WebClient in WebSphere is within WebSphere itself. [Please note that different versions of WebSphere may have slightly different wording or differently designed screens] You will need to bring up the Administration Console in your browser to begin. (refer to your WebSphere documentation for details about the Administration Console). You will need to click on the menu item ‘Applications’ to expand it, then click on the ‘New Application’ option.
There will be several options for new applications; you will need to select the ‘Enterprise Application’ option. On the following screen, you will choose the ‘install’ option to deploy your web application in WebSphere. Once you choose this, it will give you a dialog that allows you to select the location of the file. Select the .war file that you packaged earlier and click ‘Next’.
For our purposes, we will select the ‘Fast Path’ option for settings since, as stated previously, WebClient does not require special settings or additional steps in WebSphere. Click next after selecting ‘Fast Path’ to bring up the installation options. If your environment requires specific settings, you can set them up here. Please refer to the WebSphere documentation for the purpose and affect for each setting. The default settings should be acceptable if your environment does not require additional configuration.
The next step is for mapping the module to the server. This is for environments that have distributed servers and load balancing. Clicking next will bring up the only screen where we have to add some information. All web applications must specify their context root, and WebClient is no exception. Paste the text we copied from the context root of your web project here, and then click next.
The Summary is next screen to display. Quickly review that the settings match your environment, and click Finish. That will deploy the web application to WebSphere. In order to actually use the WebClient application however, you must first start the server from the Administration Console; it does not start automatically. The name in the list of servers to start will be the same as the Context Root that you specified.
Now that the WebClient application has been deployed and is started, the next thing to do is to bring it up in the browser. The URL format is the same as it is in Tomcat or Jetty. The first part of the URL will be whatever the installation of WebSphere has specified it to be. It is followed by /[context root]/webclient
You will now be able to run your application under WebSphere!
