Author name

Wed, 29 Jun 2016

5 min read

Requirements Management (RM) Converter application configuration and troubleshooting guide

Rosa Naranjo, Jeff Hardy, Terry Caudill, Paul Boney
Last updated: April 11, 2017
Build basis: IBM Rational Requirements Composer, 3.0.1.x, 4.0.x and IBM Rational DOORS Next Generation 4.0.x, 5.0.x, 6.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.

Supported platforms
When is the converter required

Prerequisites
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

Installing in a separate web container
Deploying to a new WebSphere Application Server profile
Installing a new Tomcat application

Configuring the converter proxy

Troubleshooting
    Server error: “CRRRW8010E A server error prevented the generation of the content”
    Platform issues
    Red Hat Enterprise Linux 7
    Class cast exceptions
    Headless (console mode) Linux environments
        Virtual framebuffer and exporting the display
        Testing for system dependencies
    Allowlisting
    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.

When is the converter application required?

The graphical editor browser add-on has been removed in 6.0.3 in favor of the HTML-based Diagram Editor. For DNG 6.0.3 and later, if you are not migrating from an earlier version, or if you do not need to view graphical artifacts created with the graphical editor browser add-on, then the converter application is not required.

Prerequisites

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 https://jazz.net/help-dev/clm/topic/com.ibm.jazz.install.doc/topics/t_s_server_installation.html.

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:

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.

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 startNode.sh 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:

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 rrcwebdirectory from the previous step.
On server2, start the web application server.
Reconfigure the RM application by following the steps in Configuring the converter proxy. In those steps, server1 is the RM server and server2 is the converter server.

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.

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.

Deploying on WebSphere 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.

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:

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.

Installing in a separate web container

You might need to run the RM Converter in its own web container to avoid conflicts or server crashes. For example, you must use a separate web container to avoid the JVM crash issue.

The overall scenario for deploying the RM Converter application to a separate web container is as follows.

Note: Change the following tokens to the correct values in the following commands:

WAS_username
WAS_password
JazzInstallDir
nodeName
serverName
server_name:server_port

Deploying to a new WebSphere Application Server profile

Start the main profile that contains RM.
Using the main profile’s admin console, uninstall the converter application.
Create a second profile for the converter. Note the secure port number, which is referred to in these instructions as converter_profile_port.
Note: Look in /opt/IBM/WebSphere/AppServer/profiles/Converter60/properties/portdef.properties and use the value of WC_defaulthost_secure as the converter_profile_port.
In this example command, the startingPort specifies the HTTP port; the converter_profile_port must be the secure (HTTPS) port.
```
/opt/IBM/WebSphere/AppServer/bin/manageprofiles.sh -create -adminUserName WAS_username -adminPassword WAS_password -templatePath /opt/IBM/WebSphere/AppServer/profileTemplates/default -profileName Converter60 -startingPort 10443 -omitAction defaultAppDeployAndConfig -enableAdminSecurity true
```

Start the converter profile.

/opt/IBM/WebSphere/AppServer/profiles/Converter60/bin/startServer.sh server1

Add the JAZZ_HOME custom property to the server.
- Manual method:
  - WebSphere Admin console > Servers > Server Types > WebSphere application servers > server1 > Java and Process Management > Process definition > Java Virtual Machine > Custom Properties > New…
  - Name: JAZZ_HOME
  - Value: file:///JazzInstallDir Example: file:////opt/IBM/JazzTeamServer
- Example command: Set up the converter profile using the clm_was_config.py script, as described at https://jazz.net/wiki/bin/view/Deployment/DeployWASJython.
```
/opt/IBM/WebSphere/AppServer/profiles/Converter60/bin/wsadmin.sh -language jython -user WAS_username -password WAS_password -f JazzInstallDir/server/was/clm_was_config.py JazzInstallDir/server/conf
```
Deploy the converter application. Use the WebSphere Admin console to install the converter.war file, or use a deployment script.
Example command: Use the distributed deployment script, as described at https://jazz.net/wiki/bin/view/Deployment/DeployWASJythonDistributed.
```
/opt/IBM/WebSphere/AppServer/profiles/Converter60/bin/wsadmin.sh -language jython -user WAS_username -password WAS_password -f JazzInstallDir/server/was/clm_deploy_distributed.py nodeName serverName JazzInstallDir/server/tomcat/webapps/ converter
```
Restart the profile for the custom property to take effect and to start the converter application:
```
/opt/IBM/WebSphere/AppServer/profiles/Converter60/bin/stopServer.sh server1 -user WAS_username -password WAS_password  /opt/IBM/WebSphere/AppServer/profiles/Converter60/bin/startServer.sh server1
```
Note: You must restart the profile for the custom property to work. If you skip this step, the converter will not work.
Verify that the converter works by opening https://server_name:converter_profile_port/converter/htmlgen in a browser. You should see a successful diagnostic test.
Configure the converter proxy.
Verify that a graphical artifact can be rendered.

Installing a new Tomcat application on the same server

Stop the existing Tomcat instance, if it is running:
```
JazzInstallDir/server/server.shutdown
```

Create a new Tomcat instance:

cp -r JazzInstallDir/server JazzInstallDir/server.converter

Remove unneeded files:

rm -rf JazzInstallDir/server.converter/tomcat/webapps/*.war JazzInstallDir/server.converter/tomcat/webapps/converter/ JazzInstallDir/server.converter/tomcat/work/Catalina/localhost/converter/ JazzInstallDir/server.converter/conf

Move the converter from the original Tomcat instance into the new one:

mv JazzInstallDir/server/tomcat/webapps/converter.war JazzInstallDir/server.converter/tomcat/webapps/

Modify the ports of the new Tomcat instance. In the following commands, change the second port number to the desired port. The port that was originally 9443 is referred to in these instructions as converter_profile_port.

sed -i -e 's/9443/9445/g' JazzInstallDir/server.converter/tomcat/conf/server.xml  sed -i -e 's/9080/9082/g' JazzInstallDir/server.converter/tomcat/conf/server.xml  sed -i -e 's/9009/9011/g' JazzInstallDir/server.converter/tomcat/conf/server.xml  sed -i -e 's/9005/9007/g' JazzInstallDir/server.converter/tomcat/conf/server.xml

Start the new Tomcat instance:

JazzInstallDir/server.converter/server.startup

Start the original Tomcat instance:
```
JazzInstallDir/server/server.startup
```
Configure the converter proxy.
Verify that a graphical artifact can be rendered.

Configuring the converter proxy

The RM application has a setting for the URL of the converter that must be updated if the server or port of the converter is different from that of the RM application.

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/fronting.properties file on the RM server, modify the com.ibm.rdm.fronting.server.ConverterURL value to have the host name and port of the converter.
```
com.ibm.rdm.fronting.server.ConverterURL=https://converter_server_name:converter_server_port          /converter/htmlgen
```
2. On the RM server, stop and restart the web application server.
If you are using version 5.0 or later, follow these steps:
1. On the RM server, 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
```
https://converter_server_name:converter_server_port/converter/htmlgen
```
  and then click Save at the top of the page.
  
  Version 5.0 or later does not require the RM application to be restarted; the change will take effect immediately.

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:com.ibm.rdm.fronting.server.ConverterURL.

Troubleshooting

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.

If you have deployed the converter application in WAS, and you receive the CRRRW8010E error even though the converter diagnostic page displays a successful test, some additional configuration steps may be required.

Solution:

Verify that the converter is running by opening https://server_name:converter_profile_port/converter/htmlgen in a browser. Ensure that it displays a successful diagnostic test.
Clear the WAS cache. On Linux, run <your_WAS_directory>/AppServer/bin/clearClassCache.sh
Clean the following WAS directories under the relevant WAS profile:
- Logs
- wstemp
- temp
Restart the server

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:

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.

Red Hat Enterprise Linux 7

On Red Hat Enterprise Linux 7 or later, the converter might cause a JVM crash that looks like the following stack trace.

*** buffer overflow detected ***: /opt/CLM60/server/jre/bin/java terminated  ======= Backtrace: =========  /lib64/libc.so.6(__fortify_fail+0x37)[0x7f32c9001a57]  /lib64/libc.so.6(+0x10bc10)[0x7f32c8fffc10]  /lib64/libc.so.6(+0x10d9c7)[0x7f32c90019c7]  /lib64/libglib-2.0.so.0(g_spawn_sync+0x230)[0x7f3275f830a0]  /lib64/libglib-2.0.so.0(g_spawn_command_line_sync+0x75)[0x7f3275f83775]  /lib64/libgio-2.0.so.0(+0xbe08b)[0x7f3276bd008b]  /lib64/libgio-2.0.so.0(g_dbus_address_get_for_bus_sync+0x28a)[0x7f3276bd192a]  /lib64/libgio-2.0.so.0(+0xcaaae)[0x7f3276bdcaae]  /lib64/libgio-2.0.so.0(g_bus_get+0x56)[0x7f3276bdcba6]  /lib64/libgio-2.0.so.0(g_bus_watch_name+0xd0)[0x7f3276be8a20]  /usr/lib64/gtk-2.0/2.10.0/immodules/im-ibus.so(+0x446e)[0x7f32707dc46e]  /lib64/libgobject-2.0.so.0(g_type_class_ref+0x4ae)[0x7f3276255a9e]  /lib64/libgobject-2.0.so.0(g_object_newv+0x279)[0x7f327623e1e9]  /lib64/libgobject-2.0.so.0(g_object_new+0x104)[0x7f327623e964]  /usr/lib64/gtk-2.0/2.10.0/immodules/im-ibus.so(ibus_im_context_new+0x12)[0x7f32707dcfc2]  /lib64/libgtk-x11-2.0.so.0(+0x12ce66)[0x7f327c7c5e66]  /lib64/libgtk-x11-2.0.so.0(+0x12d789)[0x7f327c7c6789]  /lib64/libgtk-x11-2.0.so.0(+0x12dcc4)[0x7f327c7c6cc4]  /opt/CLM60/server/tomcat/work/Catalina/localhost/converter/eclipse/configuration/org.eclipse.osgi/bundles/84/1/.cp/libswt-pi-gtk-3659.so(Java_org_eclipse_swt_internal_gtk_OS__1gtk_1im_1context_1set_1client_1window+0xf)[0x7f327cd63417]  /opt/CLM60/server/jre/lib/amd64/compressedrefs/libj9vm24.so(+0x2af85)[0x7f32c3eacf85]

If this problem occurs, you must run the converter in a separate web container. For more information, see Installing in a separate web container.

Class cast exceptions

If the temp directories of WebSphere Application Server are not cleaned when the converter.war file is upgraded, the converter might not function. In this case, the converter.log file will contain java.lang.ClassCastException errors.

To resolve this issue, stop the profile, clean the temp and wstemp directories, and restart the profile. For more information, see the step about deleting temp files in the Changing WebSphere Application Server installations and instances help topic.

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:

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.

Allowlisting

If you have a proxy or reverse proxy configured for your RM environment that uses allowlists, you might need to add the following entries to your http server authentication and proxy allowlist 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 allowlist entries:
ProxyPass /converter/htmlgen https://server_name:server_port/converter/htmlgen <Location /converter/htmlgen> LdapConfigFile ldap configuration property file location ProxyPassReverse /converter/htmlgen </Location> ProxyPass /rm/ https://server_name:server_port/rm/ <Location /rm/> LdapConfigFile ldap configuration property file location ProxyPassReverse /rm/ </Location>

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 rosy@us.ibm.com.

Jeff Hardy is a member of the Rational Requirements Composer team. Please direct feedback and comments to jefhardy@us.ibm.com.

<edited 2023-04-06 by IBM to update terminology>

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Feedback

Was this information helpful?

2 people rated this as helpful.