Requirements Management (RM) Converter application configuration and troubleshooting guide

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.

Supported platforms

    Windows systems
    Linux systems

Installing the application: Standard installation

Configuring the application after a standard installation
    Configuring Linux systems
    Configuring clustered environments

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"
    Platform issues
    Headless (console mode) Linux environments
        Virtual framebuffer and exporting the display
        Testing for system dependencies
    Converter diagnostic tool

Supported platforms

The RM Converter application is supported on the following platforms only:

  • Windows
  • Red Hat
  • SUSE Linux
  • CentOS
  • Linux for System z
  • 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.

    Windows systems

    No additional software packages are required.

    Linux systems

    • X11 Server or Xvfb - X11 virtual frame buffer
    • GTK 2+

    Installing the application: Standard installation

    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

    Configuring the application after a standard installation

    Configuring Linux systems

    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:

    1. Make sure that the X11 server or Xvfb application is started.
    2. 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.

    Configuring clustered environments

    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 script because the nodes are started remotely by using the WebSphere Application Server Deployment Manager component.

    Installing in a delegated configuration

    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:

    1. 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.
    2. On server1, start the web application server and run /jts/setup.
    3. Deploy the RM Converter application converter.war file to an application server on server2.
    4. Copy the CLMInstallDir/server/rrcweb directory from server1 to a similar location on server2.
    5. 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.
    6. On server2, start the web application server.
    7. Modify server1 to use the converter on server2:
      • If you are using a release of Rational DOORS Next Generation that is earlier than version 5.0, follow these steps:
        1. In the conf/rm/ file on server1, modify the value to have the host name of server2.
        2. On server1, stop and restart the web application server.
      • If you are using version 5.0 or later, follow these steps:
        1. On server1, open https://server_name:server_port/rm/admin.
        2. In the Configuration section, click Advanced Properties and find the entry for ConverterURL.
        3. Modify the ConverterURL value to have the host name of server2, and then click Save at the top of the page.

    Downloading the converter.war file and preparing to deploy it

    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.

    1. On, download the converter application for the appropriate platform.
    2. 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.

    3. 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.
    4. 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.
    5. Deploying on WebSphere Application Server

      1. Log in to the WebSphere Application Server Admin console as an administrator.
      2. To install the converter.war file, from the left menu, click Applications > Install New Application.
      3. On the New Application page, click New Enterprise Application and then browse on the local file system to the converter.war file.
      4. Select Detailed - Show me all installation options and parameters, and then click Next. On the page with the warning message, click Continue.
      5. When you are prompted to select installation options, keep the default settings and click Next.
      6. On the “Map modules to servers” page, select the converter.war module checkbox and click Next.
      7. On the “Map Virtual Hosts” page, make sure that the Mapping to the default host check box is selected.
      8. On the “Map context roots for Web modules” page, make sure that the context root is /converter. Then, click Next.
      9. 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.
      10. On the “Summary” page, click Finish.
      11. To complete the installation, click save directly to the master configuration.
      12. 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.
      13. Start the RM Converter application.

      Installing on a Tomcat 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:

      1. Navigate to the CLM installation directory at CLMInstallDir/server/tomcat/webapps.
      2. Remove all of the web application archive (.war) files in the directory, except for the converter.war file.
      3. Start the Tomcat server.

      Configuring the converter proxy

      On the RM server that hosts the RM application, you must modify the file to indicate the location of the RM Converter application. In the server installdir/server/conf/rm/ file, modify the following entry:\://converter server URL\:converter server SSL port

      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:

      After you modify the parameter, you must restart the RM application. For instructions to stop and start the server, see the documentation for your web application server.


      Server error: "CRRRW8010E A server error prevented the generation of the content"

      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.

      Platform issues

      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:

      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.

      Headless (console mode) Linux environments

      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.

      X virtual framebuffer and exporting the display

      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.

      Testing for system dependencies

      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:

      1. 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.
      2. Look for a file that has a name like this one:
      3. After you find the appropriate file, enter this command: ldd filename. The libraries that Gtk+ requires are listed. 
      4. 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:

        1. 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"
        2. Modify whitelist entries:
              ProxyPass /converter/htmlgen https://server_name:server_port/converter/htmlgen
                  <Location /converter/htmlgen>
                      LdapConfigFile ldap configuration property file location
                        ProxyPassReverse /converter/htmlgen
              ProxyPass /rm/ https://server_name:server_port/rm/
                  <Location /rm/>
                      LdapConfigFile ldap configuration property file location
                      ProxyPassReverse /rm/

      For more information, see work item 45897.

      Converter diagnostic tool

      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
      Jeff Hardy is a member of the Rational Requirements Composer team.  Please direct feedback and comments to

      Was this information helpful? Yes No 2 people rated this as helpful.