design management tips and troubleshooting · dm tips & troubleshooting applying patches to...

DM Tips & Troubleshooting

Design Management Tips and Troubleshooting Author Kevin CornellVersion: 1.2 (Sep 6, 2013)Note to Developers maintaining this document: It resides in the RTC DM Server team stream in the plug-in com.ibm.xtools.rmps.user.docs (component DM Server Documentation).

Table of ContentsINTRODUCTION.....................................................................................................................................3

ACRONYMS.................................................................................................................................................3

INSTALLATION.......................................................................................................................................4

INSTALLING DM TRIAL LICENSES....................................................................................................................4MISSING APPLICATIONS AFTER AN INSTALL........................................................................................................4IHS REVERSE PROXY INSTALLATION OF DM AND VVC...................................................................................4JTS SETUP AUTHENTICATION ISSUES WHEN USING WEBSPHERE............................................................................4UNINSTALLING DESIGN MANAGEMENT............................................................................................................5

UPGRADING DESIGN MANAGEMENT..............................................................................................7

MISMATCHED UPGRADE TOPOLOGIES..............................................................................................................7UPGRADES INCLUDING VVC AND REQUIREMENTS MANAGEMENT........................................................................7VVC REPOTOOLS MIGRATION COMMAND..........................................................................................................8DM UPGRADE MANAGER.............................................................................................................................8REVERTING A DM UPGRADE TO A PREVIOUS RELEASE........................................................................................9

REPORTING...........................................................................................................................................11

REPORTING WITH RPE (TUTORIAL).............................................................................................................11REPORTING WITH SERVER SECURITY SET TO TLS V1.2.....................................................................................11AUTHENTICATION ERROR BROWSING REPORT PARAMETERS..............................................................................11

GENERAL TROUBLESHOOTING......................................................................................................12

GENERATING DIAGNOSTICS..........................................................................................................................12ISA LITE UTILITY.....................................................................................................................................12IBM JVM DIAGNOSTICS...........................................................................................................................12JFS INTERNAL METRICS (ICOUNTERCONTENTSERVICE)...................................................................................12LOG FILES................................................................................................................................................13APPLICATION HTTP LOGGING.....................................................................................................................13ENHANCED DM APPLICATION LOGGING..........................................................................................................14DATABASE ERRORS....................................................................................................................................14

Database Error CRJAZ0265I importing a large model.....................................................................14Database Connection Error CRJAZ2654E........................................................................................15

IHS REVERSE PROXY LOGGING...................................................................................................................15INDEX CORRUPTION - WEB PAGE HANGS......................................................................................................15REPOTOOLS COMMAND RUNS OUT OF MEMORY.................................................................................................15INSTRUMENTATION OF DM (METRICS)...........................................................................................................16LINUX DISPLAY ISSUES..........................................................................................................................17PUTTING AN APPLICATION SERVER INTO DEBUG MODE........................................................................................17

Copyright IBM Corporation 2013 - 1 - 06/09/13


APPLYING PATCHES TO DM.........................................................................................................................17

USEFUL TIPS..........................................................................................................................................19

DB2 COMMANDS......................................................................................................................................19RSA DOMAIN EXTENSION APPLICATION.......................................................................................................19DM INCOMING LINKS SECTION....................................................................................................................20OTHER LINKS............................................................................................................................................21

LEGAL NOTICES..................................................................................................................................22



IntroductionThis article contains support information about various topics related to Design Management (DM). Although these tips correspond to DM 4.0.3 and later, many are applicable to earlier releases.

AcronymsCCM - Change and Configuration Management (also known as Rational Team Concert)DM - Design Management (refers to either Rational Software Architect DM or Rhapsody DM)IHS - IBM HTTP Server (reverse proxy server)ISA - IBM Support Assistant utility (ISA Lite)JAF - Jazz Application Framework (a newer SDK used by DM and VVC but not CCM)JFS - Jazz Foundation ServicesJTS - Jazz Team ServerJVM - Java Virtual Machine (e.g., IBM's J9 JVM)LDAP - Lightweight Directory Access ProtocolRM - Requirements Management (also known as Rational Requirements Composer)RPE - Rational Publishing EngineRRDG - Rational Reporting for Document Generation RSA - Rational Software ArchitectRSADM - Rational Software Architect Domain Extension Application for DMSDK - Software Development KitVVC - Versions, Variants and Configurations (also known as Configuration Management)WAS - WebSphere Application Server



InstallationInstalling DM trial licensesDesign Management delegates its user authentication and licensing to the Jazz Team Server (JTS) application. Regardless of your topology (single application server or distributed servers) you must install the DM trial licenses into the same application server that the JTS is installed into.

Missing applications after an installThe installation of Design Management 4.0, 4.0.1 and 4.0.2 automatically installed some of the applications required for DM, such as VVC (Configuration Management). In DM release 4.0.3 and later, these applications are being shipped as individual installable components. If they are not installed, either JTS setup for Design Management fails or Design Management will not work properly. Also, remember to install these extra components when you are performing an upgrade from a previous release.When either RSA DM or Rhapsody DM are installed, VVC must also be installed. The installable component for VVC is called “Configuration Management”. Do not confuse this with “Change and Configuration Management (CCM) which corresponds to Rational Team Concert.When RSA DM is installed, the RSA domain extension application must also be installed. The installable component is called “IBM Rational Software Architect Extension for Design Management Domain Extension”. In other sections, this component corresponds to the application with the rsadm.war file.

IHS Reverse Proxy Installation of DM and VVCIf a topology includes the IBM HTTP Server (IHS) along with DM, attempts to access DM either via the IHS server or directly using its WAS server address may result in a 404 error. For example, if you try to access https://<host:port>/dm/scr you might get the error “Error 404: ProxyServlet: /dm/scr”. This can occur when DM or VVC are installed into WebSphere and the web server (IHS), where WebSphere has been configured for clustering. DM and VVC currently do not support clustering.To fix the issue, shut down the WAS server and add the following line to the teamserver.properties files for both DM and VVC (e.g., <DM_installDir>/server/conf/dm/teamserver.properties). Then restart the WAS server.

com.ibm.team.repository.cluster.isInCluster=false

JTS setup authentication issues when using WebSphereDM and VVC delegate their authentication to the JTS application. When the WebSphere application server is used, you must define the security role mappings (JazzAdmins, JazzUsers, etc.) for the JTS application. If you forget to set these mappings, when you first try to log into /jts/setup you will get authentication errors. If this happens, in the WebSphere console click Applications > Application Types > WebSphere Enterprise Applications > jts_war. Under Detail Properties, click “Security role to user/group mapping”. This page shows the user groups for the Design Management Server that you must map to users or groups in your security realm (LDAP server).



Uninstalling Design ManagementIn situations where the initial install of Design Management had problems, you may need to uninstall DM in order to try again. The topology, single server or distributed, the application server, Apache Tomcat or WebSphere, and the type of database used affect how DM is uninstalled.The following steps assume DM and VVC have been registered with JTS and that you are familiar with the application server in which DM and VVC are deployed. All or some of the following web application archive (.war) files may have been deployed on the application server: dm.war, rdmhelp.war, vvc.war, vvchelp.war and rsadm.war.

1. Unregister both DM and VVC. In a web browser, go to the jts/admin page and click the Server command link. In the left panel select the registered applications page and remove the applications associated with “/vvc” and “/dm”.

2. If the application server is WebSphere, use the WebSphere console to uninstall the deployed DM and VVC related applications corresponding to the .war files listed above. Then shut down the WebSphere server. If the application server is Tomcat, shut down the server.

3. Delete any cached application data (plug-ins) for DM and VVC. If the application server is WebSphere, go to the <WAS_installDir>/profiles/<profileName>/logs folder. Delete any log files associated with the .war files listed above. In the folder <WAS_installDir>/profiles/<profileName>/temp/<hostnameNode01>/server1 delete any folders corresponding to the .war files.

If the application server is Tomcat, go into the <DM_installDir>/server/logs folder and delete the applicable log files. In the folder <DM_installDir>/server/tomcat/work/Catalina/localhost delete any folders corresponding to the .war files listed above.

4. Use the Installation Manager to uninstall the Design Management component, the Configuration Management (VVC) component and possibly the RSA-DM domain extension component.

5. Delete any saved data for DM and VVC. In the <DM_installDir>/server/conf folder, delete the dm and vvc folders if they still exist. If the RSA domain extension folder <DM_installDir>/server/confrsa exists, delete it too.

In the situation where you want to attempt the registration and set up of DM and VVC again, you do not need to completely uninstall and re-install DM. Instead of performing steps 4 and 5 above, perform the following steps.

4. Reset the DM and VVC databases. If you are using DB2 or another commercial database, delete the previous DM and VVC databases and create them again. If you are using Derby, go into the <DM_installDir>/server/conf/dm/derby folder and delete the folder repositoryDB. Then unzip the repositoryDB.zip file again in that same conf/dm/derby folder. Do this same process for VVC in the folder server/conf/vvc/derby.

5. In the server/conf/dm folder, you will see the teamserver.properties file and several corresponding backup files. Look at the size and creation date of the backup files and the oldest file should be approximately 10K in size. If you open this file with a text editor such as Notepad or Wordpad, you will see that it contains comments for each property setting. The other teamserver*.properties files do not have these comments. This is the original file that was installed so rename it to teamserver_original.properties and never delete or modify this file. Delete the remaining copies of teamserver.properties. Copy and paste the original file and rename the copy back to teamserver.properties.

Perform these same teamserver.properties steps for VVC in the folder server/conf/vvc.



At this point you should be able to run a custom /jts/setup again to register and finalize VVC and DM.



Upgrading Design ManagementThe upgrade process for Design Management contains many steps and it is quite easy to make mistakes. The Design Management Interactive Upgrade Guide provides the steps that need to be performed given your topology. If the CLM applications (CCM, QM or RM) are also being upgraded, there is a separate interactive upgrade guide where many of the steps are similar and you must merge the steps accordingly from both guides.All Jazz based applications are currently upgraded using a side by side procedure where both the old and new releases of Design Management are installed on the same machine but must use separate installation folders, or packages, when using the Installation Manager. If you are using the Tomcat application server, each installed release has its own Tomcat server so you effectively have two separate instances of DM, which may share the same databases, so backups of those databases must be performed at the beginning of the upgrade process. If you are using the WebSphere application server, the upgrade process will uninstall the .war files for the old release of the applications, change the JVM custom property JAZZ_HOME to the new release installation folder and then deploy the new .war files. Again, the same databases are used so backups must be performed.

Mismatched Upgrade TopologiesWhen performing a Design Management upgrade, a side-by-side upgrade process is used. This means the newer release of same applications are installed on the same machine as the old release. There are several restrictions:

1. The topology of the new release must be identical to the old release. In the old release, if several applications were deployed in the same application server (Tomcat or WebSphere), the corresponding applications from the new release must also be deployed in the same application server.

2. The installed features for Design Management must match. If the old release of Rhapsody Design Management did not contain the Simulink feature, the new release of Design Management must not include that Simulink feature.

3. If one application is being upgraded, all of the applications deployed on the same application server must be upgraded. Even if JTS is deployed in a different application server, it must always be upgraded to the highest release of the other applications being upgraded.

4. If DM is upgraded, VVC must also be upgraded to the same release, even if VVC is deployed in a different application server.

Upgrades Including VVC and Requirements ManagementThe upgrade processes for VVC and RM both require an upgrade step to be performed after the applications from the new release have been deployed and the application server restarted.The Requirements Management application has several migration steps at the page https://<host:port>/rm/web/projects/migration that have to be performed.The VVC migration requires a special repotools-vvc command to be run after the server has started. This VVC command must only be run after the RM migration has completed. Until the RM migration is complete, the JTS application is in migration mode, which will cause the VVC repotools command to fail.


http://pic.dhe.ibm.com/infocenter/rdmhelp/v4/index.jsp?topic=%2Fcom.ibm.rcam.install.doc%2Ftopics%2Froadmap_clm_upgrade.html


VVC repotools migration commandAs part of the upgrade process for DM 4.0.3 and later, when the application server is started for the first time after running the upgrade scripts, the following VVC command must be run.

repotools-vvc.xx -migration_vvc_updateResourcesCommand credentialsFile=credentials.txt

This command sends a request to the VVC application to perform its migration. The repotools command then waits for a response. If there is a lot of data in VVC or the server is slow, this repotools command may abort with an error indicating a timeout occurred. If this happens, wait 10 minutes and run this repotools-vvc command again. If the migration in VVC completed successfully, the repotools command should return immediately with a success response.

DM Upgrade ManagerThe final process of DM migration happens automatically after the application server has been started. The Design Management Upgrade Manager runs in a separate thread every time the server is restarted. This upgrade manager will install new ontologies and resources needed for the newest release of DM, but it will only perform these upgrade steps once. For most of the DM server restarts, the DM Upgrade Manager determines that nothing needs to be performed and it stops immediately. Unfortunately the progress of this DM upgrade manager can only be determined by continually examining the dm.log file. On Linux, you can use the “tail -f” command on dm.log.When you examine the DM log file, you should see the following messages for the DM Upgrade Manager:• INFO com.ibm.xtools.rmps.dtk.setup.DTKConfigurationUpgradeManager - Started Design

Manager Upgrade Manager. It is a background process that could take a long time to complete, especially if re-indexing is performed. While upgrade is running, please do not use the server.

• (many other messages for various upgrade manager steps may appear here)• INFO com.ibm.xtools.rmps.dtk.setup.DTKConfigurationUpgradeManager - Stopped upgrading

Design Manager Server. The upgrade operation completed successfully.

An upgrade from releases 4.0, 4.0.1 or 4.0.2 to later releases requires a complex upgrade step where separate index resources are merged into their corresponding model resources by the IndexResourceMigrator. This IndexResourceMigrator also logs several messages to the dm.log file and is the last main step performed by the upgrade manager. In the DM log file, a successful upgrade should also contain the following messages before upgrade managers's “stopped upgrading” message:• INFO com.ibm.xtools.rmps.frontservice.jaf.models.IndexResourceMigrator - Merging index

resources into their corresponding model resources.• INFO com.ibm.xtools.rmps.frontservice.jaf.models.IndexResourceMigrator - Updating the query

scope resources.• INFO com.ibm.xtools.rmps.frontservice.jaf.models.IndexResourceMigrator - Updating

uncommitted edit sessions.• INFO com.ibm.xtools.rmps.frontservice.jaf.models.IndexResourceMigrator - Deleting unnecessary

index resources.• INFO com.ibm.xtools.rmps.frontservice.jaf.models.IndexResourceMigrator - Starting the re-

indexing process. This will take quite some time, so please be patient.



• INFO com.ibm.xtools.rmps.frontservice.jaf.models.IndexResourceMigrator - Index resource upgrade completed in xx minutes. Subsequent JFS re-indexing took yy minutes.

The index resource conversion requires every model resource to be read and written and uses bulk read/write operations with 200 resources at a time. However, the latency of the Java garbage collection mechanism can result in an out-of-memory error. This memory error will not be shown in the dm.log file because it occurs at the JVM level. If the DM Upgrade Manager aborts, check the error messages in the JVM stderr log file. For Tomcat, this is the server/tomcat/logs/catalina.log file. For WebSphere this is the profiles/<profileName/logs/server1/SystemErr.log file. If an out-of-memory error occurs during the DM index conversion step of the upgrade manager, the model resources could be corrupted. The safest approach is to uninistall the newer release completely and to start over. See information in a following section titled “Reverting a DM upgrade to a previous release”.Before attempting the upgrade the second time, an extra JVM system property must be defined to reduce the size of the bulk reads/writes. With Tomcat, add the flag

-Dcom.ibm.xtools.rmps.IndexResourceMigrator.bulkSize=10” to the JAVA_OPTS variable in the server.startup script file. For WebSphere, add another custom JVM property (on the same WebSphere console page that JAZZ_HOME is defined) where the property name is “com.ibm.xtools.rmps.IndexResourceMigrator.bulkSize” and the value is 10.

The last action performed by the IndexResourceMigrator is to start the re-indexing process. If this re-indexing fails for some reason, the last IndexResourceMigrator message “ Index resource upgrade completed” may not appear in the log file. You must ensure the DM index is created. Shut down the application server and in the <DM_installDir>/server folder, run the command:

repotools-dm.xx -reindex (where .xx is .bat on Windows and .sh on Linux)

Reverting a DM Upgrade to a previous releaseIf you are using the Tomcat application server, the installation directory for the new release of DM contains a second Tomcat server, so there is no need to uninstall any applications from Tomcat. However, if you are using the WebSphere application server, the process to revert to the older release will require the new applications to be uninstalled and the old applications to be re-deployed. This is included in the steps below.With either application server, if you are using a commercial database product such as DB2 or Oracle the DM and VVC databases are modified during the upgrade process so backups must be made. The process to revert to the older release will require the databases to be restored from those backups.The following steps assume the new release of Design Management has been installed, database backups were created and the upgrade process for VVC and DM has been attempted. As part of the upgrade process, all or some of the following web application archive (.war) files may have been deployed on the application server: dm.war, rdmhelp.war, vvc.war, vvchelp.war and rsadm.war.

1. If the application server is WebSphere, use the WebSphere console to uninstall the deployed (new release) DM and VVC related applications corresponding to the .war files listed above. If the installation also included the JTS and CLM applications, those applications must also be uninstalled. In the WebSphere console, select the application server entry, expand the Java Process Definition section and go to the Java Virtual Machine (JVM) page. Select the custom properties link and change the path for the JAZZ_HOME and log4j.configuration properties so



that they correspond to the installation folder of the old release of DM. Then shut down the WebSphere server.

If the application server is Tomcat, shut down the server.

2. Delete any cached application data (log files and plug-ins) for DM and VVC. If the application server is WebSphere, go to the <WAS_installDir>/profiles/<profileName>/logs folder. Delete any log files associated with the .war files listed above. In the folder <WAS_installDir>/profiles/<profileName>/temp/<hostnameNode01>/server1 delete any folders corresponding to the .war files. Delete the JTS and CLM related war folders if they were co-installed with DM.

If the application server is Tomcat, a separate installation folder was used for the new DM release. A subsequent uninstall of the new release of DM will clean up any cached data.

3. Restore the databases for the original release. If you use a commercial database such as DB2 or Oracle, during the upgrade process you were instructed to make backups of the databases for DM, VVC and possibly JTS and the CLM applications. You must restore those databases.

If you were using Derby, during the upgrade process you copied the databases for each application from the original installed release of DM to the installation hierarchy of the upgrade release. Therefore, the Derby databases in the original installation should not have been modified so nothing needs to be done.

4. If the application server is WebSphere, start the server and use the WebSphere console to redeployed and start the DM and VVC related application war files from the original release. If JTS and the CLM applications were deployed in the same WebSphere server, their application war files must also be deployed again. After deploying JTS or CCM, remember to set the security role mappings for those applications.

If the Tomcat server was used, simply restart the server in the original DM installation folder.If after the restored DM version starts and you notice errors in the dm.log file related to SPARQL queries, the index may have gotten corrupted. Shut down the application server (WAS or Tomcat). Open a command window and go to the original <DM_installDir>/server folder. Run the command repotools-dm.xx -reindex (where .xx is .bat on Windows or .sh on Linux). After the re-indexing completes, restart the application server.

Copyright IBM Corporation 2013 - 10 -

06/09/13


ReportingReporting With RPE (Tutorial)There is extensive documentation and examples for Design Management reporting with RPE on the Jazz.net wiki page:

https://jazz.net/wiki/bin/view/Main/DMReportTutorial

Reporting with server security set to TLS v1.2The Design Management application contains the Rational Reporting for Document Generation (RRDG) engine, which is the same report generation engine that is part of the Rational Publishing Engine (RPE) product. If the TLS v1.2 security is used, by default the RPE engine will not be able to authenticate requests with the DM reporting service when obtaining resource data.The RPE engine embedded in DM needs to have its TLS logic turned on by setting the JVM argument:

com.ibm.rational.rpe.tls12only=trueFor a Tomcat application server, this JVM argument (-Dcom.ibm.rational.rpe.tls12only=true) can be added to the JAVA_OPTS variable in the server.startup script file. For a WebSphere application server, the WebSphere console must be used to define the custom JVM property “com.ibm.rational.rpe.tls12only” with a value of true. This custom property is defined on the same WebSphere console page as the property JAZZ_HOME.

For more information on how to set up your server and web browser to support TLS v1.2, see the Jazz.net article “Enabling compliance with SP 800-131A“

https://jazz.net/wiki/bin/view/Main/SP800131a

Authentication Error Browsing Report ParametersThere are some cases where you create a report in the DM web UI and on the Parameters tab of the report, clicking on the Browse button for a parameter results in an authentication error. Depending upon which application you initially logged into on the web (e.g, /dm, /jts, /ccm, etc.) the authentication data stored in your browser will be different. DM is built on the Jazz Application Framework (JAF) SDK which delegates authentication to JTS and uses access token cookies to store the authentication data.If you logged into /jts/admin or /jts/setup, these access token cookies are not defined and the report parameter browsing logic in JAF is not able to authenticate the request. To solve this issue, log out of the web UI and log back into /dm/web.


06/09/13

https://jazz.net/wiki/bin/view/Main/SP800131a

https://jazz.net/wiki/bin/view/Main/DMReportTutorial


General TroubleshootingGenerating DiagnosticsJazz application diagnostics can be useful in tracking down a problem. All Jazz applications including JTS, DM and VVC support the running of diagnostics and exporting the results. For JTS, in a browser go to the /jts/admin page and click the “Server” link. In the left panel of the subsequent page select Diagnostics. For other Jazz applications such as DM and VVC, go to their admin page (/dm/admin or /vvc/admin), click on the Application link and in the left panel select Diagnostics.

ISA Lite UtilityAn installation of Design Management automatically includes the IBM Support Assistant Lite utility. This utility can be found at <DM_installDir>/support/ISALite. For more information, seehttp://pic.dhe.ibm.com/infocenter/clmhelp/v4r0m3/index.jsp?re=1&topic=/com.ibm.team.concert.doc/topics/t_using_the_isal.html

IBM JVM DiagnosticsBy default, most installations of Design Management will use the IBM J9 JVM. This JVM contains a health center agent that provides monitoring and problem diagnosis for applications that it runs. Before the health center tooling can be used, the corresponding agent in the IBM JVM needs to be enabled.If the Tomcat application server is used, edit the server.startup script file and add an extra JAVA_OPTS parameter as follows:

Windows: set JAVA_OPTS=%JAVA_OPTS% -XhealthcenterLinux: JAVA_OPTS =”$JAVA_OPTS -Xhealthcenter”

If the WebSphere application server is used, in the WAS console, go to Java Virtual Machine page for your WebSphere application server and in the Generic JVM Arguments text box add “-Xhealthcenter”.For more information on the health center agent and how to enable it see:http://pic.dhe.ibm.com/infocenter/hctool/v1r0/index.jsp?topic=%2Fcom.ibm.java.diagnostics.healthcenter.doc%2Ftopics%2Fenabling_was.html

Additional information on the Health Center can be found at:http://www.ibm.com/developerworks/java/jdk/tools/healthcenter/

JFS Internal Metrics (ICounterContentService)JAF (or JFS) has a built in service that keep metrics on its actions, such as the times spent performing SparQL queries. The metrics can be obtained using the internal IcounterContentService in DM, VVC or JTS using a web browser. For DM's metrics, simply enter the following URL:

.../dm/service/com.ibm.team.repository.service.internal.counters.ICounterContentService/


06/09/13

http://www.ibm.com/developerworks/java/jdk/tools/healthcenter/

http://pic.dhe.ibm.com/infocenter/hctool/v1r0/index.jsp?topic=%2Fcom.ibm.java.diagnostics.healthcenter.doc%2Ftopics%2Fenabling_was.html

http://pic.dhe.ibm.com/infocenter/clmhelp/v4r0m3/index.jsp?re=1&topic=/com.ibm.team.concert.doc/topics/t_using_the_isal.html


Log FilesEvery jazz application creates a log file with errors, warnings and other information. When any kind of problem occurs, first examine dm.log. Depending on the problem you may also need to examine rsadm.log, jts.log and vvc.log.With a Tomcat server, these log files reside in <DM_installDir>/server/logs and with WebSphere they reside in <WAS_installDir>/profiles/<profileName>/logs.In some cases a catastrophic JVM error occurs, such as out-of-memory, but these will not be logged in any of the application logs. There are application server specific logs for such messages that would typically be output to the console window. With a Tomcat server, this output is captured in <DM_InstallDir>/server/tomcat/logs/catalina.log (or catalina.out on Linux). With WebSphere, these messages are captured in <WAS_installDir>/profiles/<profileName>/logs/server1/SystemErr.log and SystemOut.log.

Application HTTP loggingIn some cases the warnings and errors that are logged are not enough to understand the issue. Many issues can occur with the communication between the Jazz applications such as between DM and JTS or DM and VVC. All of the Jazz applications use the Apache log4j framework for logging information. Each application contains its own log4j.properties file in the /server/conf/<application> folder (e.g., server/conf/dm/log4j.properties). Additional entries can be added to these log4j.properties files and the associated messages will be output to the corresponding application log file. If a log4j.properties file is changed you must stop and restart the application server for those changes to take effect. When the server is stopped, it is always a good idea to delete or rename the existing log files so that when the server starts again new log files will be created.To get debugging information between jazz applications, add the following line to the log4j.properties files of the applications you wish to monitor:

log4j.logger.org.apache.http=DEBUGThis HTTP debugging flag will result in a lot of messages being output to the log files so the logs will become huge very quickly. However, log4j has a maximum log file size and a backup mechanism to save older log files. There is also a maximum limit to the number of these backup log files that are kept so that the server will not run out of disk space. Therefore, this apache.http debug flag should be enabled for a short time or else logged data will be automatically deleted. To use this HTTP wire debugging do the following:

1. Stop the application server.

2. Modify the corresponding applications log4j.properties file to enable HTTP debugging.

3. Start the application server.

4. Quickly perform the desired actions and then stop the application server.

5. Modify the log4j.properties file to disable HTTP debugging and save copies of the log files.If the actions to perform are complicated and the maximum number of backup log files is reached, the following two properties in the log4j.properties file can be modified to either increase the maximum log file size or to increase the number of backup files kept:

log4j.appender.file.MaxFileSize=10MBlog4j.appender.file.MaxBackupIndex=5


06/09/13


Enhanced DM application loggingFor Design Management, the apache.http debugging does not log the HTTP requests received by DM from the web browser. Tracing can be turned on for the RmpsFrontService in DM where it will log a message when a request is received and a second message when that request is complete. The second message contains the time taken to process the request. Since many requests are received by a server simultaneously, multiple JVM threads are created to process those requests and the messages in the log file will be interspersed.If you are using DM 4.0, 4.0.1 or 4.0.2, add the following log4j.properties line:

log4j.logger.com.ibm.xtools.rmps.frontservice.RmpsFrontService=TRACEIf you are using DM 4.0.3 or later, add the following line instead:

log4j.logger.com.ibm.xtools.rmps.frontservice.jaf.RmpsFrontService=TRACE

To debug a timing issue, you may also want to trace the SparQL queries made by DM. To turn sparql query times on add the following log3j.properties line:

log4j.logger.com.ibm.xtools.rmps.frontservice.sparql.internal.JfsSparqlService.times=TRACE

Database ErrorsThe following Jazz.net article contains information on some basic database errors:

https://jazz.net/wiki/bin/view/Main/ServerTroubleshootingFAQ#Common_Database_Errors

Database Error CRJAZ0265I importing a large model

In addition, a common DM problem that occurs when importing a large model with DB2 is the -964 SQL error:CRJAZ0265I The virtual storage or database resource is not available. SQL: Insert Into REPOSITORY.ITEM_CURRENTS (ITEM_UUID, STATE_UUID) VALUES (?, ?) SQL Exception #1 SQL Message: DB2 SQL Error: SQLCODE=-964, SQLSTATE=57011, SQLERRMC=null, DRIVER=4.14.88 SQL State: 57011 Error Code: -964In this case the transaction log ran out of space. You can use the following commands on DB2 to resolve this:

1. Check the current transaction log size:db2 get db cfg for <database> | grep LOGPRIMARY

2. Increase the size to something larger:db2 update db cfg for <database> using LOGPRIMARY <new size>

100 is the maximum value for the transaction log pages. LOGFILSIZ can also be adjusted to change the size of each page.


06/09/13

https://jazz.net/wiki/bin/view/Main/ServerTroubleshootingFAQ#Common_Database_Errors


Database Connection Error CRJAZ2654E

During an installation of DM using DB2, an SQL error CRJAZ2654E was reporting indicating the database connection was invalid. The actual message was:

The server was unable to connect to the database because the database connection syntax is invalid. Verify the syntax in your teamserver.properties file. See the Jazz Team Server log for more information.ID CRJAZ2654E.

This error occurred even when the database properties and password in the teamserver.properties file were good. A solution was tracked down to some invalid setting, which is described in this forum post:http://www.coderanch.com/t/306316/JDBC/databases/SQLServerException-TCP-IP-connection-host

IHS Reverse Proxy LoggingIf the topology includes the IBM HTTP Server (IHS), then logging for the plug-in can be enabled via the WebSphere console and the corresponding web server. In the WebSphere console, go to Servers > Web servers > webserver1 > Plug-in properties > Plug-in logging > Log level and change the log level to Trace. After you save the configuration, you will have generate the plugin-cfg.xml file and propagate it to the IHS server.The IHS server's log file (e.g., <HTTPServer_installDir>/Plugins/logs/webserver1/http_plugin.log should contain the additional information.

Index Corruption - Web Page HangsMost Jazz applications, such as DM and VVC, maintain an index so that queries can be performed quickly. Almost every DM web page performs one or more queries against this index to obtain the appropriate data to be displayed. If this index gets corrupted for some reason, such as when the application runs out of memory, queries cannot be performed. As a result, DM web pages will appear to hang as they attempt to obtain the data. This can usually be confirmed by examining the dm.log file and looking for errors related to “sparql” queries and the JFS indexer.If the application index gets corrupted, the application may automatically try to recreate the index but that usually fails (especially if the application is already out of memory).To recreate the index, shut down the application server and in a command window go the the <DM_installDir>/server folder and run the command:

repotools-dm.xx -reindex (where .xx is .bat on Windows and .sh on Linux)Some Jazz documentation appends the “-all” parameter to the above command, which will also recreate the history index. For DM, this history index is not used so it does not need to be recreated.For JTS and VVC, equivalent repotools commands can be run (repotools-jts.xx or repotools-vvc.xx). Since JTS and VVC might use the history index, you may append the “-all” parameter.contain the additional information.

Repotools command runs out of memoryIn some cases, repotools commands such as -reindex may run out of memory. These repotools commands are typically run offline and the memory arguments defined for the application server (Tomcat or


06/09/13

http://www.coderanch.com/t/306316/JDBC/databases/SQLServerException-TCP-IP-connection-host


WebSphere) will have no effect.You need to increase the memory for the repotools command itself. Edit the corresponding repotools-dm.xx script and change the value of the line that appends “-Xmx1500M” to the VMARGS variable. A value of 1500M is 1.4 GB so double it by setting -Xmx3G.

Windows script: set VMARGS=%VMARGS% -Xmx3GLinux script: VMARGS=”$VMARGS -Xmx3G”

Instrumentation of DM (metrics)Beginning with Design Management 4.0.2, DM is shipped with code to perform instrumentation of the application which collects and maintains metrics on its performance. By default this instrumentation logic is disabled.If you are using DM 4.0.2 or 4.0.3 perform the following steps:

1. Stop the application server

2. With a WebSphere application server, go to <WAS_installDir>/profiles/<profileName>/installedApps/<hostnameNode01Cell>/dm_war.ear/dm.war/WEB-INF/eclipse/configuration. Rename config.ini to config.orig.ini and then make a copy of config.instr.ini and rename it to config.ini.

With a Tomcat application server, go to <DM_installDir>/server/tomcat/webapps/dm/WEB-INF/eclipse/configuration. Rename config.ini to config.orig.ini and then make a copy of config.instr.ini and rename it to config.ini.

3. Delete the cached plug-in data in the application server. With WebSphere, go to <WAS_installDir>/profiles/<profileName>/temp/<hostnameNode01>/server1 and delete the dm_war folder.

With Tomcat, go to <DM_installDir>/server/tomcat/work/Catalina/localhost and delete the dm folder.


The DM instrumentation page is then accessed by https://<host:port>/dm/instrumentation.

For more information, see the article:https://jazz.net/wiki/bin/view/Main/InstrumentingTheDesignManagementServer

For DM 4.0.4, an extra step is required in addition to the steps above. Before starting the application server in step 4 above, you must define the following additional JVM property:

“com.ibm.xtools.rmps.instr.isEnabled=true”If the Tomcat application server is used, edit the server.startup script file and add an extra JAVA_OPTS parameter as follows:

Windows: set JAVA_OPTS=%JAVA_OPTS% -Dcom.ibm.xtools.rmps.instr.isEnabled=trueLinux: JAVA_OPTS =”$JAVA_OPTS -Dcom.ibm.xtools.rmps.instr.isEnabled=true”


06/09/13

https://jazz.net/wiki/bin/view/Main/InstrumentingTheDesignManagementServer


For WebSphere, add another custom JVM property (on the same WebSphere console page that JAZZ_HOME is defined) where the property name is “com.ibm.xtools.rmps.instr.isEnabled” and the value is true.

Linux DISPLAY IssuesIn DM releases 4.0 thru 4.0.2, the diagram rendering in Design Management was performed in the DM application. Since DM 4.0.3 a separate RSA-DM domain extension application must be installed and this application now performs the diagram rendering. Diagram rendering is performed using the Eclipse SWT framework and it requires a valid DISPLAY.An error such as “org.eclipse.swt.SWTError: No more handles [gtk_init_check() failed]” in the rsadm.log file (or dm.log in older releases) usually indicates that the DISPLAY variable is not set up correctly. The following link contains instructions for setting a valid DISPLAY on a headless system:

https://www-304.ibm.com/support/docview.wss?q1=RN2.0.0.1&rs=3499&uid=swg21410023

Additional information can be found at:https://jazz.net/wiki/bin/view/Main/RRCConverterTroubleshooting

Putting an application server into debug modeThere may be situations where support of IBM developers need to connect to an applications server with a Java debugger in some Integrated Development Environment (IDE), such as Eclipse.For a Tomcat server, stop the server. At the command line, run server.startup.bat -debug. By default, the server will be listening on port 8000.For a WebSphere server, in the WAS console go to Application server > server1 and select the Debugging service link. Check the box “Enable service at server startup”. The default JVM debug listening port is 7777, which can be changed. Save the WAS configuration and restart the server.

Applying patches to DMIn some cases a hot fix or a patch needs to be applied to an installed DM application. The patch or hot fix usually contains one or more plug-in .jar files that need to be replaced. Both the Tomcat and WebSphere application servers cache the plug-in data when the server is started, so patching the server requires this cached plug-in data to be recreated.

1. Stop the application server

2. For each plug-in .jar file provided go to <DM_installDir>/server/conf/dm/sites folder and locate the plug-in in one of the <site>/plugins folders. Usually the patch instructions will indicate which plug-in site contains each plug-in .jar file. Rename the original plugin jar file (e.g., xxx.jar to xxx.jar.save) and copy/paste the plug-in jar from the patch. Verify that the saved and new .jar file names have the same plug-in name, version and qualifier date.

3. Delete the cached plug-in data in the application server. With WebSphere, go to <WAS_installDir>/profiles/<profileName>/temp/<hostnameNode01>/server1 and delete the dm_war folder.

With Tomcat, go to <DM_installDir>/server/tomcat/work/Catalina/localhost and delete the dm folder.


06/09/13

https://jazz.net/wiki/bin/view/Main/RRCConverterTroubleshooting

https://www-304.ibm.com/support/docview.wss?q1=RN2.0.0.1&rs=3499&uid=swg21410023




06/09/13


Useful TipsDB2 CommandsWhen a DB2 database is used, it is sometimes quicker to perform actions using a command line interface instead of using the DB2 Control Center. To use the DB2 command prompt, you may need to run the “db2cmd” program.

Creating databasesdb2 create database vvcDB using codeset UTF-8 territory en PAGESIZE 16384db2 create database dmDB using codeset UTF-8 territory en PAGESIZE 16384

Listing databasesdb2 list database directory

Deleting databasesdb2 DROP database <databaseName>db2 DROP database <databaseName>

RSA Domain Extension ApplicationWhen you install RSA-DM on Windows or Linux you must include the RSA domain extension application., During JTS setup, this RSA domain extension application is automatically registered with DM. You can check this by navigating to /dm/admin and clicking on the 'Domain Extension Servers' link in the menu. You'll see that the URL for a domain extension server looks like https://<host:port>/rsadm which should have the same host/port as your DM installation. This RSA domain extension server should show as Online and be enabled.In some situations, such as if you install DM on AIX or if you want more than one domain extension server, you need to manually add or modify the list of domain extension servers. The RSA domain extension server application does not run on AIX.You can add a domain extension server by adding its URL in the form https://<host:port>/rsadm and ensuring the enable button is checked. If the server is not showing as 'Online' then something is wrong with your domain extension server (check that it is indeed running, on that host:port). There may also be an issue with firewalls, so check your firewall settings.Even when your domain extension server is showing as 'Online' and 'Enabled', there may still be problems. Symptoms include:* When you try to view an RSA domain diagram (e.g., UML, BPMN, DP&A), you get the "Unable to load diagram" message.* Import fails, including the creation of the MTM Sample or RSA Sample ProjectIf DM and the RSA Domain extension server are on different machines, ensure that the two machines can communicate. This may not be the same problem as firewalls, but rather an effect of the certificate warnings that are often see in web browsers when connecting to a new host:port. To make sure the machines can communicate, do the following:


06/09/13


1. On the actual (physical or virtual) machine that hosts DM, open a web browser.

2. In that web browser, attempt to connect to the RSA domain extension server's URL, e.g., https://<host:port>/rsadm

3. If there is a certificate warning, accept the warning and permit the browser to continue connecting to the RSA domain extension application. There will be an error on the page, which is irrelevant. The point here is to make sure that then DM machine can talk to the RSADM machine.

4. The two servers can now communicate. Attempt to view the diagram again, for instance. Note: only the first connection must be done from the host machine. Once that has succeeded, you can return to your normal process.

DM Incoming Links SectionIn a DM resource editor on the Links tab, there is an outgoing links section and an incoming links section. Users who have created OSLC links from resources in other DM projects or in other Jazz applications to the given resource may expect to see those links listed in the incoming links section, but in most cases they will not be shown.In order to create OSLC links between DM resources and resources in another Jazz application (e.g., CCM, QM, RM, DOORS) a friend server connection must be established between the applications and in the DM project, an association must be created with the project in the other application. When OSLC links are created in DM to resources in the other application, the link resides in DM and is displayed in the UI as an outgoing link. Links created from resources in RM, CCM and DOORS to DM resources are actually created in DM via the OSLC REST API. Thus these links also appear as outgoing links in DM.The incoming link section for a DM resource is only used to show links created between resources in DM. If links are created between resources in the same DM project area, they should show up in the incoming links section.However, DM is built upon VVC which provides resource versions, configurations (workspaces and snapshots) and dependencies between configurations. Because the OSLC links that are created are also versioned, incoming links are found be issuing queries based on the current configuration. If you create project associations between two projects in DM, you will be able to create links from resources in one project to resources in a different target project, but you will only be able to choose resources in the target project but only resources that reside in the default workspace. If you then switch to the target project and open the target resource, the incoming links section will not show the link because there is no dependency between the two project configurations (the project area association is not a dependency in VVC terms).The current mechanism to create cross project links in DM is to create a snapshot in the target project and to set a workspace dependency to that snapshot in the source project. The source project workspace identifies a specific version of the source resources and the target project snapshot identifies a specific version of the target resources. This mechanism allows multiple workspaces in the same source project to have links to different versions of the same resource in a target project.For example, suppose you have two DM project areas (P1 and P2) which have resources R1 (in P1) and R2 (in P2) that you want to create a link between.:

1. In the project area editor for P1, do not create an association to P2 (remove it if defined).

2. When in a workspace of project P2, create a new snapshot (e.g., P2-S1).

3. When in a workspace of P1, open its current configuration.

4. In the workspace configuration, switch to the dependencies tab and add a new dependency to the


06/09/13


snapshot P2-S1.

5. Open some resource R1 in that workspace of P1 and create a link. In the add link dialog, the project P2 will be listed, even though there is no project association between P1 and P2. Select P2 and browse to the appropriate resource (R2). The outgoing link to R2 is shown in R1.

6. Switch to project P2 and select the snapshot configuration P2-S1. Open resource R2 and the incoming link from R1 is shown.

The link resource in P1 does not store any version information about the target resource in P2. That is determined by the snapshot dependency in the corresponding P1 workspace, which allows other workspaces in P1 to depend on different P2 snapshots and therefore different versions of the target P2 resource.

Other Linkshttps://jazz.net/wiki/bin/view/Main/JazzDebuggingBasicshttps://jazz.net/wiki/bin/view/Main/ServerTroubleshootingFAQ


06/09/13

https://jazz.net/wiki/bin/view/Main/ServerTroubleshootingFAQ

https://jazz.net/wiki/bin/view/Main/JazzDebuggingBasics


Legal notices

© Copyright IBM Corporation 2013.

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan, Ltd.3-2-12, Roppongi, Minato-ku, Tokyo 106-8711 Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.


06/09/13


This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM websites are provided for convenience only and do not in any manner serve as an endorsement of those websites. The materials at those websites are not part of the materials for this IBM product and use of those websites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

Intellectual Property Dept. for Rational SoftwareIBM Corporation5 Technology Park DriveWestford, MA 01886U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.


06/09/13


All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

If you are viewing this information in softcopy, the photographs and color illustrations may not appear.

Trademark acknowledgments

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at www.ibm.com/legal/copytrade.shtml.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.


06/09/13

http://www.ibm.com/legal/copytrade.shtml

design management tips and troubleshooting · dm tips & troubleshooting applying patches to...

Documents