Requirements Management (RM) Converter application configuration and troubleshooting guide
Rosa Naranjo, Jeff Hardy, Terry Caudill
Last updated: September 27, 2013
Build basis: IBM Rational Requirements Composer, 3.0.1.x, 4.0.x; IBM Rational DOORS Next Generation 4.0.x
The Rational Requirements Management (RM) Converter application renders the read-only view of RM graphical artifacts. It is an independent application that you can deploy with IBM® Rational® Requirements Composer or IBM® Rational® DOORS® Next Generation, or deploy separately in a delegated configuration.
This document describes how to install and configure the RM Converter application for both standard and delegated configurations.
Installing in a delegated configuration
Downloading the converter.war file and preparing to deploy it
Deploying on WebSphere Application Server
Installing on a Tomcat application server
Configuring the converter proxy
Server error: "CRRRW8010E A server error prevented the generation of the content"
Headless (console mode) Linux environments
Virtual framebuffer and exporting the display
Testing for system dependencies
Converter diagnostic tool
The RM Converter application is supported on the following platforms only:
- Red Hat
- SUSE Linux
- Linux for System z
- X11 Server or Xvfb - X11 virtual frame buffer
- GTK 2+
The RM Converter application cannot run on IBM AIX, Linux for Power, Solaris, or IBM i systems at this time.
Important: If your RM installation is on a platform that the RM Converter application does not currently support, use the delegated converter configuration option.
The RM Converter application has the following software
prerequisites. These packages must be installed on the same system
as the RM Converter application. If you are running in a delegated
configuration, these packages are not required on the RM
server, but are required on the delegated converter system only.
No additional software packages are required.
The standard installation for the RM Converter application is
done during the installation of the RM application. The converter .war
file, which packages the RM Converter application, is deployed to the
selected web application server at the same time as the RM
application is installed.
To install the RM Converter application, follow the installation instructions in the Rational solution for Collaborative Lifecycle Management (CLM) Information Center at https://jazz.net/help-dev/clm/topic/com.ibm.jazz.install.doc/topics/t_s_server_installation.html.
If you installed the application on a Linux system, you must complete additional steps. After you install the application but before you start the web application server, complete these steps:
- Make sure that the X11 server or Xvfb application is started.
- Make sure that the DISPLAY environment variable is set.
Tip: You can add the previous steps to the start-up script for the web application server.
If you installed the application in a clustered environment, you must complete the post-installation steps on each of the nodes that are running the converter application.
For IBM® WebSphere® Application Server implementations, you must set the DISPLAY environment variable within the startNode.sh script because the nodes are started remotely by using the WebSphere Application Server Deployment Manager component.
You can install the RM Converter application in a delegated configuration where the converter is installed and hosted on a server that is separate from the RM application. Typically, use this configuration when the RM application is being run on a platform that the RM Converter application does not support.
The overall scenario for deploying the RM Converter application to an alternate server is as follows:
- Install the RM application on server1 by using IBM Installation Manager. If you plan to use WebSphere Application Server, complete additional steps to install it.
- On server1, start the web application server and run /jts/setup.
- Deploy the RM Converter application converter.war file to an application server on server2.
- Copy the CLMInstallDir/server/rrcweb directory from server1 to a similar location on server2.
- In the web application server on server2, define JAZZ_HOME. Make sure that the value is similar to this example: CLMInstallDir/server/conf. That directory is a sibling directory to the rrcweb directory from the previous step.
- On server2, start the web application server.
- In the conf/rm/fronting.properties file on server1, modify the com.ibm.rdm.fronting.server.ConverterURL value to have the host name of server2.
- On server1, stop and restart the web application server.
Before you can deploy the RM Converter application, you must download the converter.war file and make it available on the server that you are installing it to.
- On Jazz.net, download the converter application for the appropriate platform.
- Extract the converter.war file, open the /WEB-INF/eclipse/plugins/ subdirectory, and look for a platform-specific file. Three versions of the converter.war file exist: one
for Windows platforms, one for Linux platforms, and one for Linux System z platforms.
- For Windows platforms, look for /WEB-INF/eclipse/plugins/org.eclipse.equinox.launcher.win32.win32.x86*.jar.
- For Linux platforms, look for /WEB-INF/eclipse/plugins/org.eclipse.equinox.launcher.gtk.linux.x86*.jar.
- For Linux System z platforms, look for /WEB-INF/eclipse/plugins/org.eclipse.equinox.launcher.gtk.linux.s390*.jar.
- Copy the converter.war file from the server where the RM
application is installed.
Important: Do not use this method if the RM system is on a different platform than the converter system.
- After the converter.war file is available, you can install and configure it by completing the instructions in one of the following sections. Complete the instructions for your specific web application server.
- Log in to the WebSphere Application Server Admin console as an administrator.
- To install the converter.war file, from the left menu, click Applications > Install New Application.
- On the New Application page, click New Enterprise Application and then browse on the local file system to the converter.war file.
- Select Detailed - Show me all installation options and parameters, and then click Next. On the page with the warning message, click Continue.
- When you are prompted to select installation options, keep the default settings and click Next.
- On the “Map modules to servers” page, select the converter.war module checkbox and click Next.
- On the “Map Virtual Hosts” page, make sure that the Mapping to the default host check box is selected.
- On the “Map context roots for Web modules” page, make sure that the context root is /converter. Then, click Next.
- On the “Map security roles to users or groups” page, you do not need to map security roles to users or groups for the RM Converter application.
- On the “Summary” page, click Finish.
- To complete the installation, click save directly to the master configuration.
- To check whether the application is properly installed, click Applications > Application Types > WebSphere enterprise applications. If the application was properly installed, it is listed with a red X, which indicates that the application is not started yet.
- Start the RM Converter application.
You can install the RM Converter application on an Apache Tomcat application server in either of two ways:
- Follow the instructions in the Installing the application: Standard installation section to install on the new converter server system.
- Manually copy the Tomcat directory, CLMInstallDir/server/tomcat, from the RM system to the new delegated converter system.
In either approach, the only web application archive that is required is converter.war. Before you start the Tomcat server, you must remove the other web application archive files:
- Navigate to the CLM installation directory at CLMInstallDir/server/tomcat/webapps.
- Remove all of the web application archive (.war) files in the directory, except for the converter.war file.
- Start the Tomcat server.
On the RM server that hosts the RM application, you must modify the
fronting.properties file to indicate the location of the RM Converter application. In
the server installdir/server/conf/rm/fronting.properties file, modify the following entry:
com.ibm.rdm.fronting.server.ConverterURL=https\://converter server URL\:converter server SSL port /converter/htmlgen
Important: By default, the URL that you use to access the RM server starts with https. If
the URL that you use starts with https, make sure that the URL in this parameter uses https:
When the RM converter application fails, you might see this message: CRRRW8010E A server error prevented the generation of the content.
The RM application has two separate and distinct methods for handling graphical artifacts and documents, such as business process diagrams, use-case diagrams, parts, sketches, storyboards, and screenflows:
- The RM Converter application, which generates a visual rendering of a document for view-only mode.
- A browser add-on plug-in for editing documents. You must download the plug-in and install it on your browser.
The RM Converter application runs exclusively on the server and has specific graphical dependencies that must be met on the server. The first time that you use the browser add-on plug-in to edit a graphical document, the plug-in is downloaded from the server. However, the browser add-on plug-in runs exclusively on the client.
If you get the CRRRW8010E error, the problem is on the server. The problem is not related to the browser add-on plug-in.
Even if the converter cannot render the graphical document, you can still edit the document if you installed the plug-in. In the editor, the Edit button is still available and you can see your content. However, after you save your changes, exit the editor, and return to view mode, the converter cannot generate the content and you cannot see the work that you just saved. To see your work, open the editor again.
In the current release of the RM application, the converter is supported only on a subset of server platforms: Windows, Linux, and Linux System z. If the RM server is installed on an unsupported platform, errors might occur. If errors occur, take either of these steps:
- Move the installation to a supported platform.
- Delegate the converter onto another supported platform. For
more details, see the Installing in a delegated configuration section.
The converter is supported on both Tomcat servers and WebSphere Application Server. If you use a Tomcat server, deployment occurs automatically. If you use WebSphere Application Server, deployment must be done manually. Make sure that the converter was successfully deployed. For more details, see Deploying CLM applications on WebSphere Application Server in the Information Center.
As mentioned earlier, the RM Converter application has graphical dependencies that must be met in order to function. At its most basic level, the RM Converter application uses the Eclipse Standard Widget Toolkit. Therefore, the converter application might run on other platforms that Eclipse supports.
Because Windows platforms inherently provide a graphical user interface
(GUI), issues are rare when you run the converter application on Windows servers. However, Linux platforms are commonly configured for a headless, or console-only, mode and
therefore require additional setup and configuration to support the converter application.
To generate a rendering of a graphical artifact, the server that runs the converter application requires a display to process the graphical requests. However, that display is not accessible in a headless configuration. To resolve this issue, you can install the X virtual framebuffer (Xvfb) on the system to capture the display. For more information, see Workaround: On Linux systems, the Rational Requirements Composer server does not start in console-only mode.
Note: That article was originally authored as a technote for the Rational Requirements Composer version 2.x release; however, the underlying requirement that the article addresses still exists in versions 3.x and 4.x, and in releases of Rational DOORS Next Generation.
In addition to the information in the article, keep these other points in mind when you configure for Xvfb:
- Port conflicts for the display
In the article, the steps specify the use of display port 1 on
when Xvfb is started and when you export the DISPLAY environment
variable. However, depending on how the server is configured and is being used, that port might already be in use; for
example, by a vnc tool that is connecting to the server. In such a case, select a different port, such as 3, and ensure that the same value is being used by both Xvfb and the export commands.
- X11 authentication (xhost)
While trying to access the X11 server, some systems might encounter permission errors like this one:
Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable.
In such a situation, you might need to use xhost + or create an .Xauthority file to grant the appropriate permission.
- Disabled X11 forwarding
If you are using a tool such as vnc to connect to the server, make
sure that X11 forwarding is disabled so that proper routing to the
frame buffer can occur.
Because the converter application is based on the Eclipse Standard Widget Toolkit libraries, certain platform requirements must also be met. The log files typically do not provide much
information about which prerequisite is missing, and in general,
all that you are likely to see are entries such as these:
- Exception in thread "Display Thread" org.eclipse.swt.SWTError: No more handles
- Exception thrown : java.lang.NoClassDefFoundError:
org.eclipse.draw2d.ColorConstants (initialization failure)
The most basic dependency is for Gtk+. More specifically, the
version of Standard Widget Toolkit that the converter application uses requires Gtk+ 2.2.1 and its
dependencies. You can check which version of Gtk you are
running by entering this command: rpm -q gtk2.
To test Gtk+ dependencies:
- Find the Gtk+ shared object library. Depending on the architecture of the server, that library is in either the /usr/lib directory or the /usr/lib64 directory.
- Look for a file that has a name like this one: libgtk-x11-2.0.so.0.
- After you find the appropriate file, enter this command: ldd filename. The libraries that Gtk+ requires are listed.
- If an entry is shown as "not found", you must install the appropriate package to get that library.
If you have a proxy or reverse proxy configured for your RM environment that uses whitelists, you might need to add the following entries to your http server authentication and proxy whitelist files:
- Modify http server authentication with these entries:
ModuleCKAuth "ˆ/converter/htmlgen" "optional"
ModuleCKAuth "ˆ/rm([0-9][0-9])?/resources/" "optional"
ModuleCKAuth "ˆ/rm([0-9][0-9])?/query" "optional"
ModuleCKAuth "ˆ/rm?/service-document$" "optional"
- Modify whitelist entries:
ProxyPass /converter/htmlgen https://server_name:server_port/converter/htmlgen
LdapConfigFile ldap configuration property file location
ProxyPass /rm/ https://server_name:server_port/rm/
LdapConfigFile ldap configuration property file location
For more information, see work item 45897.
An experimental diagnostic tool is available for the RM converter application. For more information, see the RRC Converter Diagnostic Tools page.
About the author
Rosa Naranjo is a member of the Jazz Jumpstart team. The
Jazz Jumpstart team is a worldwide group of development
specialists who bring new and advanced Jazz-based technologies to
customers. Please direct feedback and comments to firstname.lastname@example.org.
Jeff Hardy is a member of the Rational Requirements Composer team. Please direct feedback and comments to email@example.com.
© Copyright 2012, 2013 IBM Corporation
|Products||Downloads Community||Our Story|