You can access IBM’s Rational DOORS via a web browser, using the IBM Rational DOORS Web Access (DWA) web server. But doing so can be tricky due to the many configuration files and the lack of documentation to guide troubleshooting the installation. This post captures the lessons I learned when I installed DWA for a client. I suspect it can save up to 100 hours.
IBM Rational DOORS Web Access (DWA) is a web-based client that provides access to create, review, edit, and discuss requirements held in an IBM Rational DOORS database. DWA is also a web front-end which can be used to develop an application that can communicate with the DOORS database via the OSLC REST API.
There are several “how-to” IBM web pages and blogs for set up. Here are several additional tips and tricks for keeping DWA stable and running smoothly.
Several components are installed with DWA. These components include DWA (a Tomcat-based web server), a message broker, a single interop application. These components are installed by default on one DWA server but in a clustered, performance driven environment, the components can be installed on different machines with a front-end load balancer (like Apache), as illustrated. But I digress, let’s get back to troubleshooting your DWA install.
Before installing, first ensure that your DWA is the correct version for your DOORS database server. Refer to the IBM Rational DOORS Web Access compatibility page for more information.
As you’re installing DWA, ensure DWA is installed in a folder name that does not contain a space. For example, install it in “DWA” not “Doors Web Access.” If you have a space in the folder name, DWA will be unable to launch.
Once the installation of DWA has completed, how do you test it? Log into DWA using the URL provided by the installer (e.g. http://localhost:8080/dwa/dwa.jsp). If you can’t connect, the fun begins! Time to troubleshoot.
Is DWA running? Did it start with the service? If the service didn’t start successfully, you can run DWA from the command line and view each of the components running in a separate window. Watch the windows closely and you might see an error, like “connection refused,” which indicates that DWA has trouble connecting to the DOORS database server. Running DWA from a command window by running the server.start.bat command is a great way to troubleshoot these problems.
Maybe an error scrolled by too quickly? Take a look at the “server/festival/festival.log” file with your favorite editor, like WordPad or Notepad++.
Has DWA been running for a while and suddenly stopped? Review the “festival.log” file for errors. You might see an “out of memory” error. Memory is limited for each of these three components, especially on older DWA setups which run in 32-bit JVM mode. You can increase the JVM three-fold, from a default of 512 MB maximum to 1,536 MB, especially if you’re using IBM Rational DWA 9.6.0.1 or earlier. More can be allocated by changing the “server.start.bat” file.
On Line 36, you will see the following command
set JAVA_OPTS=%JAVA_OPTS% -Xmx512M -XX:+HeapDumpOnOutOfMemoryError
The value after -Xmx defines the upper limit of RAM allowed to the JVM. Change it to –Xmx1536M.
If, after setting memory to the max, an “out of memory” appears, what do you do now? You’re probably running DWA 9.5 which has a known memory leak. The solution is to upgrade to 9.6.
Another component called the “Interop” (short for interoperation) automatically starts as the user load increases. This eats up more physical memory and increases CPU utilization. IBM documentation suggests only one interop per CPU core. Any more interops drag down system performance. When all the interops have started and CPU is still overloaded, it’s time to think about setting up a DWA cluster.
You may want to configure the components to run on different ports, or maybe the DOORS database was installed on a non-standard port. If so, you’ll need to run the “dbadmin” command stored on the DOORS database server.
Dbadmin Warning
Usually “dbadmin” will not report any errors when it fails – it will simply print out fewer lines of text. When dbadmin runs correctly it will display six lines of “dbamin” text like this:
There are many configuration files in DWA. The most important file is “festival.xml.” According to IBM documentation, “you must configure the ‘festival.xml’ file. If you do not edit the values in the version that is installed by default, Rational DOORS Web Access does not run correctly.” Since IBM does not offer a script to validate these settings, you need to either do it yourself or rely on a professional services firm. This blog on the IBM site discusses the many configuration options in DWA as a hint on where to start.
While IBM recommends load balancing Rational DOORS Web Access, there will be occasions which require you reboot both the IBM Rational DOORS database server and IBM Rational DWA server. For example, perhaps you ran the dbadmin command to connect DWA to a non-standard DOORS database port and there are still connection errors in the log. Maybe it’s time to restart the DWA and the DOORS database server. For this reason, these two applications should run on their own dedicated servers.
The final tip, once you’ve tried all the other previous suggestions, is to turn on debug logging. Go to the server/festival/config folder and rename the “festival-log4j.xml” file to “festival-log4j.xml.bak.” Then rename the “festival-log4j.xml.support” file (which has debug logging turned on) to “festival-log4j.xml.” Restart the DWA server (not just the service), and additional log files will be created. When the problem is fixed, be sure to restore the original “festival-log4j.xml” file, as the log files can be quite large.
These tips should get you closer to a working DWA install. Even though you got it working once, you could have future problems keeping it running. Send us a line at ConnectALL via our Contact Us form and we’ll be glad to give you a hand.
Johnathan McGowan is a Sr Solutions Architect at ConnectALL. He is responsible for customer-facing technical resource for the ConnectALL integration tool. He works with Account Managers to assess prospect needs and build demo integration solutions, guide prospects through product evaluations, and assist clients with their production deployments.
