Archive for documentation

File Upload for WebClient

Follow the attached steps to implement a file upload from your browser to the web server.

1)    Import the attached (“FileUploadServlet”) Java Project into your Eclipse Workspace.File Upload

2)    Right click your Java Project, and select Properties. Under “Java Build Path”, add reference in the Projects tab to the “FileUploadServlet” project. And in the Libraries tab, add a reference to the “commons-io-2.1.jar”, which is in the “FileUploadServlet” project.

3)    Right click your Web Project, and select Properties. Under “Java Build Path”, add reference in the Projects tab to the “FileUploadServlet” project.

4)    Right click your Web Project, select New, then Servlet. Add the existing UploadServlet to your web project. This will update the web.xml with your new servlet.


5)    In your file, add the following setting. The value should be /”Your Web Project”/upload. If you want to change the url-pattern for your upload servlet in the web.xml file, the “/upload” part of this setting will need to change to whatever you set your url-pattern to:

        # Upload Servlet Location



6)    In Plex, create an upload pattern function called “~WebUploadShell”. This should inherit from “~WebShell” and “~DetailPopup”.


7)    In “~WebUploadShell”, add a field to the panel called “UploadFileName”, in a region called “UploadP”. This field will inherit from “FIELDS/FileName” and have two values added to it which are shown below.


8)     In the panel editor for “~WebUploadShell”, hide the label for “UploadFileName”, and add the following control name to the edit for “UploadFileName”:



9)    In the panel editor for “~WebUploadShell”, create an event called “UploadComplete” and attach it to the “Updated” physical event for the “UploadFileName” edit control.


10)    In the action diagram for “~WebUploadShell”, add the following code:


11)    Now that the patterns are created, have whatever function you want to have upload capability inherit from “~WebUploadShell”.


12)    In the “Edit Point Set Upload Folder”, you will need to set where you want the file to upload to UploadP<UploadFileName> and do a Put UploadP. If you need to perform code when the upload completes, please put this code in the UploadComplete event. When running, the UploadFileName field will appear as an upload button. When clicked, it will take you to a file selection window, when selected, the file will begin uploading.


NOTE: The placement of the UploadFileName field in the panel is based on a different html form than that of regular WebClient. It positions relative to the top of the panel, not relative to other objects. So, it will take some experimentation to get the placement exactly how you want it.

Running CA Plex Java on (virtually) any platform

Is Java truly write once run everywhere? In years past, it was often not the case but in the modern day it is more or less true. And you can run your Plex Java apps on many platforms with good performance, given a supported database and JRE. This is a very nice situation for the ISV or corporate developer who needs to rehost.

In practice is is advisable and desirable to run and debug a CA Plex java app on a Windows or another platform during the development process, such as Mac OS, Linux, iOS, Unix (Aix), or zOS. By far the easiest way to accomplish this is by using the free Eclipse IDE, or if you already have IBM Rational – then you can use this version. The Eclipse (Rational) product runs on virtually every major computing platform, from PC’s to the big iron iOS or zOS. If you do purchase a Rational version, you will have the added benefit of being able to debug not only Java, but RPG and COBOL as well. This is nice if you are trying to debug a full featured multitiered web app, running both in the web container and back end server. WebClient supports this style of application architecture.

The examples below use Eclipse for Mac and CA Plex 7.0, but the steps are the same regardless of platform or version. Mac OS is particularly useful for mobile device development, for example you can run your CA Plex WebClient apps on iOS devices such as iPhone and iPad by using Xcode and Phonegap.

First Step – Install the Eclipse or Rational IDE

Before installing, download and install a matching JDK from Oracle using this link. The JavaSE version is appropriate for most cases.

Next, download and install Eclipse or Rational IDE. You can download a open source version of Eclipse from this link to match your target platform, or go to IBM for a version that runs on an IBM host (PowerSystems, zOS) (warning, fees may apply). We recommend downloading the J2EE version so you get most necessary tooling included.

Second Step – Create a Java Project and Link your Plex source

Go to menu File / New, select other, then select Java project



Give it a name of your choosing



Third Step – Add ObRun and JDBC / Third Party Jars

Copy and paste any external jar files you may need into the project root. This includes both CA Plex product jars and JDBC jars for database access. Note – you can leave the jar files in place and add to the class path or reference by path. However, if you do this the resulting Java project is easily not portable between machines.

If you are not using WebClient, you will need to make sure the ObRun.jar is copied from the Plex product files. If you are using WebClient, then this will happen automatically when you add the WebClient nature to the project. See the WebClient user manual

After you copy and paste the jars into the project, you need to configure the build path to use the jars.



Select the jars you copied from the first step


Final Result


Fourth Step – Link to your CA Plex generated source

In this step simply link to the CA Plex generated source directory (under your model GEN folder). First remove the src directory from the build path and from the project. Next you will  link the Src subdirectory (with an exclusion to Res), and then link the Res directory.

Go to the build path and start with an empty screen. If you see a src folder, first remove from this screen then go back and delete the directory from the project itself.


If you get the message “directory exists with a different case” later it is because you need to remove the default src directory first!

Next, add a source folder for Plex bitmaps / GIFs. Copy the Plex BMP3 files into this directory


Next, use the link button to link to your CA Plex Gen/Src directory, where your Java source resides


Add an exclusion pattern to exclude the Res source directory (it will be added in the next step)


Link the Res directory in the same manner as Src


Your final build path for source should look like this:


Fifth Step – Compile and check for errors

Eclipse will automatically and incrementally build your CA Plex source as you generate – and will do so much faster that you can generate!

Check the “Problems” tab for any errors. Usually these errors are the result of C++ code injected into the java code. You will need to variant / clean up any native C++.


Sixth Step – Set up a run configuration

Click on the green “Play” button drop down to access the “Configurations” menu. Select this.


Type in the Name, Project (or browse), and the main class “ObRun.ObPanel.ObLaunch”


Click on the arguments tab

Type in the package.class name followed by “path= “, e.g. MobileApp.ConfMenu “path= “. Note the space between the = and final quote.


Congratulations, you are running Plex Java natively (in this case on Mac OSX Lion accessing MySQL)


Implementing an Ajax TreeView

The WebClient TreeView advanced control was designed to work with existing Plex Active/TreeView pattern functions with minimum changes to the action diagram. Read the following for the instructions (note this article was authored by Andrew Leggett, Senior Consultant for ADC Austin. He can be reached at

For example, you may want to implement a function that looks like this as a page in a browser.

To prepare an existing Active/TreeView or ShowTree function for WebClient.

  1. Attach the WebClientControls group model as a library to your group model. Note this is a separately licensed model.


2.  You can now inherit from the WebClient/_Abstract.~TreeView function.

3. If you have existing action diagram code to display a TreeView control, the only addition you will need to make is to add a ‘Go Sub TreeView Refresh’ statement at any point where you need to update the control in the browser.  This subroutine behaves similarly to a ‘Put’ statement.  For a new TreeView function, follow the article ‘Implementing a Tree Control’ in the Plex Help.

4. When exiting the function, make sure you exit with ‘Go Sub Terminate’, as this subroutine inherits the code necessary to cleanly dispose of the tree control in memory

5. If you are displaying images for your tree nodes, you will need to make these available to the web application with the following steps: (Note: the SelectedImage property is not currently supported)

6. In Eclipse, your Web project will contain a ‘WebContent’ folder which contains the run-time resources for your web application.  Create a folder directly under ‘WebContent’ and name it ‘images’ (it is case-sensitive).

  • Copy any bitmaps that your application uses to the ‘images’ folder.

  • The web application is case-sensitive, so you need to ensure that the bitmap names match those in your model.  The Plex TreeView uses Name objects scoped to the Scripts function to get the bitmap names; e.g. MyTreeView.Scripts/FNC option NME/Image 1.  The bitmap name is stored in the literal value of the name object.  Compare these names to the bitmaps in your images folder, and rename the files if appropriate.

To see a worked example of the TreeView pattern, download the WXPCourse61 example model.

Deploying CA Plex/WebClient Apps on IBM WebSphere

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

 This guide has been written by Matt Fleming, Application Consultant and WebClient support technician. Matt can be reached by contacting WebClient support, or at


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!

Deploying WebClient Applications using Tomcat/Apache with SSL

There are benefits to running secure production WebClient/Websydian applications under a combination of both Tomcat and Apache. This configuration can be the highest performance option, and can be run under SSL for security. Tomcat and Apache are both free, open source software that are proven in high performance production environments. While lacking some of the management features of advanced web application servers like IBM Websphere, the reduced cost mitigate this in many cases.

The following diagram depicts a high-level view of the architecture:

There are two major components in the setup: the Apache web server and a Tomcat servlet container.

Apache is a fully-featured web server, meaning it has the ability to serve static pages to users while offering a variety of options that provide value in web environments. Strictly a web server, it has no ability to serve dynamic pages, in other words, content that changes with user input or other sources of data. Dynamic pages might be implemented with Apache by using different mechanisms like modules to allow execution of languages like PHP and Perl. In this scenario, the mod_jk module is used to connect Apache with an existing Tomcat installation, obtaining the equivalent result of enabling Apache to serve dynamic pages but with help from an external service.

A web client is defined as a single user requesting content from a web server. The web server will handle requests and return a response for each client’s request. This is the basic interaction between clients and servers in web applications. In this setup, web clients will be able to establish a secure communications channel between them and the server by using the HTTPS (HTTP over SSL) protocol. HTTPS support is provided by mod_ssl, an extension module for the Apache Web Server.

View all the details on the setup here.

Accessing and Controlling Web Sessions

Accessing Sessions from your CA Plex / WebClient application

Since WebClient applications are running on web servers, the concept of the session tracking can be important. Session tracking is a mechanism that is used to maintain state about a series of requests from the same user (that is, requests originating from the same browser) across some period of time. Typical session data that can be of interest is the authenticated user (if any), the URL used to start the web application, the session id, method (GET or POST), query parameters, etc. In this blog entry, we will show you the basics of accessing this information, including supplying an CA Plex XML import file so you can import the example directly into your model.

Technical Details

Your CA Plex application under WebClient has access to the session information from the action diagram by using source” code. The mechanism used is the getFromUserStorage and SetToUserStorage CA Plex API’s (See topic “Storing and Using Third Party Class Instances” in the Plex help). You use the key “javax.servlet.http.HttpServletRequest” to access the session information. The API information can be obtained from a Java Servlet reference, for example here.

Here is an example CA Plex Source Code object to get session information:

Here is the source code to cut and paste:

 //Initialize class with parameter
 import javax.servlet.*;
javax.servlet.http.HttpServletRequest MyReq = (javax.servlet.http.HttpServletRequest)(getApp().getFromUserStorage("javax.servlet.http.HttpServletRequest"));
javax.servlet.http.HttpSession MySess = MyReq.getSession();
if(MyReq != null)

And the end result:


You can also access the CA Plex model import XML from this link. This will create a session entity object in your model with the source code object and the simple user interface seen above.

Customizing CA Plex / WebClient with stylesheets and templates

Putting CA Plex applications on the web with Websydian WebClient i+ is straightforward, in most cases it is literally as simple as adding one triple “myfunction is a ~webshell”. However, without CSS/stylesheets and html formatting, the web page looks as basic as the original CA Plex function – which is often not visually appealing. For example, here is what a simple EditDialog function will look like out of the box:


Fortunately WebClient makes it easy to incorporate CSS and HTML techniques to create a more distinctive look. The look and feel can be incorporated throughout the application by using standard Plex inheritance. The rest of this post shows you the steps so you can do this yourself. The steps are applied against the example model supplied with WebClient.

First download this zip containing HTML and CSS. You will use these files in the exercise.


  1. Create a standard webshell function

Most Plex developers are familiar with this concept. Enter two triples like the screen print below.

2. Inherit from the new function

3. Create a web template file

Switch over to Eclipse/Rational and insert a new template into your project. For simplicity we will add directly to the WebClient template folder, but typically you will add this to a new project folder with your WebClient customizations. To add the new template, copy the StandardShell-page.wcli file into this folder. This template is very simple – it references a style sheet, and incorporates a logo and a banner.

4. Copy the supplied CSS files and Image files

Copy the supplied CSS files into a new folder in your web project. CSS supplies the look and feel of the web pages. Virtually all elements of the page are under style sheet control – including grids, buttons, fields, etc. You can dramatically change the look and feel of the page through some simple HTML – if you know what to do. CSS is beyond the scope of this blog, but there is a wealth of information out there on what can be done. Also copy the image files into the images folder.

5. Gen and build, and view results

Quite a dramatic result for very little work! For extra credit, change the logo in the template, and the background color. You can change the logo in the StandardShell template, and the color in the standardgeneral.css. Use the hex color code, for example ffff33 is canary yellow. Here are some color codes.

WebClient Deep-linking/Automation – Part 2 of 3

In this second installment of the three part deep linking series, we will show the steps necessary to create a simple url access (“deep link”) into any Plex function by WebClient. If you missed the first installment, the introduction to WebClient deep linking, you can access it by clicking here. Although this simple example shows a function with just one input parameter, Plex functions with complex parameter structures can be called using this technique, including functions with MOV variables. There will be more detailed information on the XML call structure used in the final installment of the series.

Please follow these steps

  1. Create a new custom servlet in your web project.

    Right-click on wxpcourse60web à select New à select Other… à expand web folder à select Servlet à type deeplink for Java package and Class name à click Finish.



  1. Edit

    Copy and paste the code provided (DeepLinkJavaZip) to the newly created servlet.

    Change the package name to deeplink.

    Change the class name to deeplink.

Modify input variable name and field name in the new servlet.

    final String plexXML =

"<PlexFunction xmlns="">


Name="Input"><Field Name="ItemID">" +

encodeToXML(myVariable) +



Modify webclient URL from

final String webclientURL = “/webclient/test”;


final String webclientURL = “/webclient/deeplink”;

Note: String webclientURL = the link to webclient servlet without context path

Save changes.

  1. Update wxpcourse60web libraries.

    Right-click on wxpcourse60web à select Properties à select Java Build Path à open Libraries tab à click on Add External JARs… à browse to your <WebsydianWebClient installed directory>jetty6.1.7lib folder à select servlet-api-2.5-6.1.7.jar

  2. Turn off Websydian Web Client Project Builder.

    Right-click on wxpcourse60web à select Properties à select builder à uncheck Websydian Web Client Project Builder (if checked)

  3. Add new parameter in J2eeProxy.prop file.

    Expand wxpcourse60web project à expand WebContent à expand WEB-INF à open J2eeProxy.prop file with text editor à add the following parameter

    webclient.entry.url.deeplink = WXPCOURSE60.WXwF

    Save changes.

  4. Change deeplink servlet mapping.

    Expand wxpcourse60web project à expand WebContent à expand WEB-INF à open web.xml with text editor

    Change webclient servlet mapping to


    Change deeplink servlet mapping to


Save changes.

  1. Build the project and publish to the web server.


  2. To call the function, open a web browser and enter the following URL.




WebClient Upgrade Instructions Posted

Developers who are upgrading their version of WebClient from 1.4.x to a new version can find the upgrade instructions posted in two places:

WebClient Wiki

On the main page under English documentation

WebClient Portal Site

Under developer content / software downloads. You must self-register on the site to download software and documentation from this area.

WebClient Japanese Manuals Posted

Japanese language manuals have been posted to the Websydian WebClient documentation wiki.
The translation was done by the Japanese WebClient distributor, Takaya Corporation.

© 2013 CM First Group - All rights reserved