CM WebClient File Upload Setup

CM WebClient File Upload Setup

File Upload

This guide will show you how to upload files to your Web Server from your WebClient application.

1. Import the attached zip Java Project into your Eclipse Workspace.

NOTE: If your workspace uses a Tomcat 10 server, make sure to use the FileUpload (Tomcat 10 Version). 


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. Check the option “Use an existing Servlet class or JSP”. Then click “Browse” to add the existing UploadServlet to your web project. This will update the web.xml with your new servlet.



5. For the Web Project, select the Deployment Assembly property and click 'Add…'. Select Project, then select the FileUploadServlet project. Click 'Add…' again, then 'Archives from Workspace', then 'Add…' again. Now expand the FileUploadServlet project and select the two commons*.jar files.


6. In your WebClient.properties file, add the following setting.

# Upload Servlet Location
Define.WSUPLOAD=/{Your Web Project name}/UploadServlet

The default value will be /{Your Web Project name}/UploadServlet. If you want to change the url-pattern for your upload servlet in the web.xml file, the “/UploadServlet” part of this setting will need to change to whatever you set your url-pattern to:

 <servlet-mapping>
        <servlet-name>UploadServlet</servlet-name>
        <url-pattern>/UploadServlet</url-pattern>
 </servlet-mapping> 

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

8. Create two fields “UploadFileName” and “UploadControl” with the following triples and values:




9. Add the field “UploadFileName” to the ~WebUploadShell panel in a region called “UploadP”.

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

UploadFile:OtherFormsArea:template=UploadFileEdit:default

NOTE: There are 2 upload templates “UploadFileEdit” provides a Browse button to allow the file to be selected, while “DragUploadFileEdit” provides a region where a file can be dragged to.  Both templates take up the size of the edit control on the panel and display a progress bar within the region while the file is being uploaded.

Currently the “UploadFileEdit” template is the only one that can be used multiple times on the same panel, each time must use a unique control name.

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

12. Create a source code object “SaveUploadDestination”. Add 2 parameters fields “UploadFileName” and “UploadControl”.  Add the following source code:

For environments using Tomcat 9 or older:
import com.adcaustin.webplex.WebPlexLog;
import javax.servlet.http.*;
// Store the upload destination in a session attribute so it can be retrieved by the UploadServlet
try {
        HttpServletRequest request = (HttpServletRequest) getApp().getFromUserStorage("javax.servlet.http.HttpServletRequest" );
        HttpSession session = request.getSession();
        session.setAttribute(&(2:).toString() + "UploadDestination", &(1:).toString());
} catch (Exception e) {
        WebPlexLog.errorLog(e, "Error setting session attribute");
}

For Environments using Tomcat 10 or later:

import com.adcaustin.webplex.WebPlexLog;
import jakarta.servlet.http.*;

// Store the upload destination in a session attribute so it can be retrieved by the UploadServlet 

try {       
      HttpServletRequest request(HttpServletRequest)getApp().getFromUserStorage("jakarta.servlet.http.HttpServletRequest"); 
      HttpSession session = request.getSession();
      session.setAttribute(&(2:).toString() + "UploadDestination", &(1:).toString());
    } catch (Exception e) {
            WebPlexLog.errorLog(e, "Error setting session attribute"); 
    }    

NOTE: The upload template allows for multiple upload controls on the same panel, so you will need to call this code for each control, passing in the control name each time.  The control name is the first part of the control name parameter before the first colon, so in the example above it will be “UploadFile”.
If you want to extract the names of the uploaded files from js to plex, see the following section: "How to extract the names of uploaded files".

 13. In the action diagram for “~WebUploadShell”, add the following code:


Map the parameters of the API Call passing in the panel field and control name:


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

15. In the “Edit Point Set Upload Folder”, you will need to set the location on the Web Server 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.


How to extract the names of uploaded files

1.       In order to extract the names of the selected and uploaded files, first you must create a local variable with 3 fields. The "String_FileNames" field stores the string with all the names of the uploaded files. The "CurrentFileName" field stores the individual name of the currently selected file within the "String_FileNames" field. And the "Validation_Flag" field (type: FIELDS/YesNo) is used to see if there are any other names left within the "String_FileNames" field.



2.       Create the following source code:


            {
                String OriginalFileNamesString = &(1:).toString();
               String FileName = &(2:).toString();
                String Flag = &(3:).toString();


                FileName = OriginalFileNamesString.substring(0,OriginalFileNamesString.indexOf(";"));
                &(2:).fromString(FileName);
                OriginalFileNamesString = OriginalFileNamesString.replaceAll("^.+?(?=);", "");
                &(1:).fromString(OriginalFileNamesString);
                if(OriginalFileNamesString.indexOf(";") == -1){
                               Flag = "N";
                               &(3:).fromString(Flag);
                }
            }

 

In the action diagram add the following code. This code must be placed on an event that's tied to the "Modified" physical event. (The ProcessUpload<String_FileNames> local variable must recieve the string containing all the file names before the source code is executed).




 


4.  Add the next Define in the webclient.properties in order to execute the code to extract the names.

     


Additional Notes
By default, the upload template will allow a single file to be uploaded at a time. It can be configured to allow multiple files at a time on supported browsers* by adding the “multiple” parameter to the control name, e.g.

UploadFile:OtherFormsArea:template=UploadFileEdit:default:multiple

* Due to a limitation in Internet Explorer, only single files can be uploaded at a time.

Filenames can be encoded to prevent issues saving files with unsupported characters, e.g. uploading file “Chinese 工作的呢?.txt” will normally be saved as “Chinese ¹¤×÷µÄÄØ£¿.txt” but the filename can be encoded in UTF-8 as “Chinese+%C2%B9%C2%A4%C3%97%C3%B7%C2%B5%C3%84%C3%84%C3%98%C2%A3%C2%BF.txt”.

To specify this, add the “encfilename” control name parameter, e.g.

UploadFile:OtherFormsArea:template=UploadFileEdit:default:encfilename=UTF-8

The upload control displays the filename of the last file uploaded. To clear the value, just perform a “Put” statement on the control field, e.g.

Put UploadP<UploadFileName>

Switching File Upload from Tomcat 9 to Tomcat 10 in Workspace 

In the event that there’s already a workspace that is working on Tomcat 9 and wish to migrate to a Tomcat 10 server, it’s necessary to do the following steps:
1. Delete the old FileUploadServlet project from the workspace (Uncheck the option “Delete project contents on disk”) 
                             
 

2. Right click the java project, select “Properties” click on “Java Build Path” and locate the “Libraries” tab. Remove “common-io-2.1.jar” from the Java project.
 


3. Remove “FileUploadServlet” in “Projects” tab. Apply changes. 
 

4. Right click the web project, select “Deployment Assembly” and remove “commons-fileupload-1.2.2.jar”, “commons-io.2.1.jar” and “FileUploadServlet”.
 

5. Close Eclipse 

6. Open workspace’s physical folder and delete the old FileUploadServlet project 

7. Go to Eclipse once again and open the workspace, import the new FileUploadServlet project. Select “Existing Projects into Workspace” and select the new FileUploadServlet folder. 
 

 

8. Right click on the Java project, select “Properties” and then locate “Java Build Path”, on “Projects” tab add the FileUploadServlet project.  
   

 

9. On “Libraries” tab, select “Add JARs…” and add “commons-io-2.1.jar” from the FileUploadServlet project. Apply changes. 
 

 

10. Right click on the Web project, select “Properties” and locate the “Deployment Assembly” tab, select “Add..” then “Project” and then select the FileUploadServlet project. 
 

 

 

11. Once again on “Deployment Assembly” select “Add…” then “Archives from Workspace” and select both “commons-io-.2.1.jar” and “commons-fileupload-1.2.2.jar"
 

   

12. Change Java project javax imports and functions.

Since the FileUploadServlet for Tomcat 10 uses jakarta imports instead of java, it’s also important to change those imports in the java project’s source files as well. This can be achieved in three ways:  
      
A) Edit source files in Eclipse 

Expand the Plex source folder in the Java and open the ObFnc.java file of the function. In the imports section of the code, you’d be able to see “import javax.servlet.http.*”. This must be changed to “jakarta.servlet.http.*”.
      
  

Make sure that any lines referencing this import in the code are also changed. 

      
       

Also make sure that all functions using the servlet are changed and regenerated. 

B) Edit source code in Plex
      
Locate the original source code “SaveUploadDestination” and change the javax import to jakarta.       

Source code using jakarta imports:
      
import com.adcaustin.webplex.WebPlexLog;
import jakarta.servlet.http.*;

// Store the upload destination in a session attribute so it can be retrieved by the UploadServlet 

try {       
      HttpServletRequest request(HttpServletRequest)getApp().getFromUserStorage("jakarta.servlet.http.HttpServletRequest" ); 
      HttpSession session = request.getSession();
      session.setAttribute(&(2:).toString() + "UploadDestination", &(1:).toString());
    } catch (Exception e) {
            WebPlexLog.errorLog(e, "Error setting session attribute"); 
    }  
      
Save changes and regenerate functions and templates. 

C) Migrate java project using Apache Tomcat Migration Tool for Jakarta 

While one can manually change the source files to make sure those imports are using jakarta, using Apache’s migration tool would make the process of changing the imports a lot simpler and quicker without editing each java source file. 

First, download the Apache Tomcat Migration Tool here. Open windows command prompt and open the lib folder, where the jakartee-migration-1.0.9.jar is located and use the following command: 

  1.  java -jar jakartaee-migration-1.0.9.jar -profile=TOMCAT "<Path of the original Gen folder>" "<Path of the output folder, can be any folder>" 
This will create a Gen folder with the new jakarta imports instead of javax.  

Make sure to replace the old java source files with the new migrated ones before opening the workspace in Eclipse.  

Lastly, rebuild the workspace so the templates are generated. 
    • Related Articles

    • Overview of Workspace Setup

      After you have the software requirements installed, below are the steps that you have to perform to setup your workspace for CM WebClient from scratch. Each step will be discussed in details when you click on the link. Install WebClient Builder ...
    • Patch Build to CM WebClient 1.8.8

      Latest Version: Date 07/31/2025 WebClient-1.8.9-pre13614 NOTE : If the hightail link doesn't open correctly the first time, please just reload the screen, we recommend using the Chrome browser to open it. IMPORTANT: The latest eclipse plugin ...
    • CM WebClient 1.8.8 Release Notes

      Download current GA Release : Download CM WebClient 1.8.8 WebClient Mobile Updates To see the latest updates of WebClient Mobile, please visit: WebClient Mobile repository. What's New? Support Java 11 Complete functionality of DojoTimePicker.ctrl to ...
    • CM WebClient for CM M3

      Pre-requisites CA Plex dispatcher – The System i TCP/IP Dispatcher is required when the transformed applications call external iSeries objects (RPG, CL programs) Properties Configuration m3startup.properties This is the file were the AS400 ...
    • Customizing in CM WebClient

      Attach point A template for a given screen can be generated from more than one template by using attach points. The templates are arranged in order from root to leaf. An attach point is a location defined in a template that other templates further ...