Sitworld: Portal Client Java Web Start JNLP File Cloner


John Alvord, IBM Corporation

Draft #3 – 15 April 2020 – Level 0.56000

Follow on twitter


In the next year or so, most ITM Enterprise customers will be converting to Java Web Start Portal Clients. The major browser vendors are abandoning java applets – see Appendix 1 below for three references. Oracle Java itself is abandoning applets. There is no purpose arguing or worrying about it, the change is coming. Happily the ITM Portal Client has the Java Web Start [JWS] as a fully supported option. This post is about how to make the transition and how to do it efficiently. A new tool is made available here to reduce the work involved. The Java Web Start Portal client actually performs better because it is not burdened with an ever changing browser software environment.

The following assumes you have an existing environment with existing TEPSIs and ior files. Converting to JWS is one transition. This post is also important if you need to extend or change an existing JWS environment, such as converting from port 1920 to 15200 or switching from http/15200 to https/15201 or adding an access for a set of users beyond a NATed firewall. It can also be used for tasks like having clients that need to use a Fully Qualified Domain Name instead of a shortname.

If you want to learn more about TEPS Interfaces – TEPSIs – see this blog post for a full background on TEPSIs.

Background – Java Web Start JNLP Files

JNLP stands for Java Network Launching Protocol.

A  default JWS TEP session is started with a command something like this

     javaws “http://<portal_server_host_name&gt;:15200/tep.jnlp”

The actual command line form will often be different. For example the javaws program object may have a full path definition so a known good [for TEP] java level is used instead of the changeable system level. Some environments may require quotes and others not.

In that initial tep.jnlp file, early on you will see


Later there will be a serious of extension tags like this

<extension href=”ka4_resources.jar.jnlp” name=”ka4_resources.jar”/>

The extension tags are used to define the extension jar files that need loading. There will be more extension jar file swith every new agent and sometimes with maintenance. In the above line, there is a file ka4_resources.jar.jnlp and in the first few lines you will see


Each set of base file [like tep.jnlp] and extension files must be consistent. If you want to change to https and 15201, every one of these files must be changed. The codebase= value on the base and each extension file needs to be altered.

Changing the Default tep.jnlp and component.jnlp

If you are changing the default for all users, the solution is pretty easy. There are two files tep.jnlpt  and component.jnlpt

Windows: <installdir>\config

Linux/Unix: <installdir>/config

Early on in each file you will see this line


What you do is replace that with what you need like


and then when you reconfigure the browser, the tep.jnlp and all the extension files will get written

Windows: MTEMS right click on TEP/Browser, select reconfigure…, click OK

Linux/Unix: ./itmcmd config -A cw

Java Web Start and JNLP File Cloning

The big work comes when you have more than a single connection. For every non-default user connection you need cloned and renamed base base file [like tep.jnlp] and all the extension files [like ka4_resources.jar.jnlp]. All the names and have to be changed, the codebase= always needs changing and sometimes you need to add protocol or databus property values. This cloning work must be repeated after any maintenance or after a new agent is installed – including agents you write with Agent Builder.

This manual work is lengthy and hard to perfect. The purpose of this Clone Tool project and blog post is to speed the process and make it more reliable.

Project Installation

A zip file is found found jwsbuild.0.56000. There is are two files and jwsbuild.ini. Install them somewhere convenient.

Perl is usually pre-installed in Linux/Unix systems. . For Windows you may need to install from or any other source. The program only uses Perl core services and no CPAN modules are needed. has been tested with

Windows: This is perl 5, version 20, subversion 1 (v5.20.1) built for MSWin32-x64-multi-thread

Linux: zLinux with Perl v5.8.7

Initialization file – default jwsbuild.ini

Here is an example jwsbuild.ini file

basename tep.jnlp


target C:\projects\Packages\jwsbuild\target

clone outside https://ADMINIB-DN65QI8:15201/ iiop outside.ior

There are four controls

basename: optional, default is tep.jnlp

base: directory where the existing jnlp files are stored

target: directory where the cloned jnlp files are stored

clone: clone name, codebase value, optional protocol and optional ior file name

The clone control has two to four parameters: 1) Clone name,  2) codebase URL value,  3) an protocol specification and 4) if protocol is iiop then this is the ior record name. This control file assumes that there is a a TEPSI defined with the name outside. The codebase is the URL needed from the TEP environment to access the TEPSI.

First Step – Create the jwsbuild.ini file

You may not need a TEPSI. For example some users may need to use a fully qualified name for the TEPS host while other users can use a shortname. Just create a clone control that looks like this:

clone miami

The same technique could switch some users to secure http

clone miami

Or you might want that connection to use http instead of iiop

clone miami http

If your url will use TEPSIs,  inventory the TEPSIs you have or will create. If you are unsure  read ==>this<==.

The existing ior files are found here

Windows: <installdir>/CMB

Linux/Unix: <installdir>/<arch>/cw

Windows: MTEMS, right click on TEPS, select Advanced, select Configure TEPS Interfaces…

Linux/Unix: view <installdir>/config/cq.ini and get data from the environment variables

Second Step – Create the cloned JNLP files and Test

Make a safety copy of the base directory files for use in a back out.

After having written the jwsbuild.ini file, run the cloning tool


This will create cloned jnlp files in the target directory. In the above example there will be tep_miami.jnlp, ka4_resource_miami.jar.jnlp and one for every other extension file.

Copy the cloned files into the base directory. The original base files are not changed. However if you are doing this a second time, you may be altering existing JNLP files. The first few times it would be good to view the cloned files manually and validate them.

You can test immediately after the files are copied – no TEPS recycle is needed. Test out the default and each access as needed.

JWSBUILD Parameters

-ini   specify an alternate initialization file


This document explains how to use jwsbuild to create the cloned jnlp files needed to start Java Web Start Portal Client sessions.

Sitworld: Table of Contents

Feedback Wanted!!

Please report back experience and suggestions.

Not all combinations have been tested. If you use the jnlp cloning tool and experience problems, please let the author know.

Appendix 1 Java Applet Future References

Firefox dropping Support of NPAPI Plugins

Oracle dropping Support in Java SDK 9

How will Java be supported in Chrome after Chrome drops the NPAPI support?

History and Earlier versions

There is a zip file with program objects. This list references historical levels in case the current level shows a problem.



Photo Note: New Cruise Ship Under Construction Winter 2016


One thought on “Sitworld: Portal Client Java Web Start JNLP File Cloner

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: