Responding to server rename status errors

Edit online

This topic describes troubleshooting and recovery procedures for failures during the online rename.

The server rename status UI polls applications for their individual rename status. If any of the application renames fails, the overall server rename is not completed. If you see a failure, the first thing that you should do is check the Jazz® Team Server and application logs to see what went wrong. Here is a list of common errors and how to fix them.

The UI indicates that a rename has not started

After running importURLMappings, you view /serverRenameStatus and it indicates that a server rename has not been started.

  • Look at the repotools-jts_importURLMappings.log. Verify that the command succeeded.
  • Stop the Jazz Team Server.
  • Run repotools-jts -exportServerRenameURLMappingHistory toFile=history.txt.

    The history.txt file shows the history of mapping events that were created. Verify that the results match your expectations. Also, look to see if the mapping event says "COMPLETED". If all of the mapping events are completed, the Jazz Team Server has processed everything and there is no longer a rename in progress. For details, see Reviewing a history of server renames.

You are not redirected to the serverRenameStatus page after a rename

This is expected behavior if the rename has already completed. To verify, go to https://jts.example.org:9443/jts/serverRenameStatus and check that everything is at 100% and green.

The application rename fails

  1. Check that the application is running and that you can ping it from the Jazz Team Server.
  2. Check that you can reach each application rootservices in the browser. For CCM, check https://ccm.example.org:9443/ccm/rootservices. Repeat for the other applications.

    If rootservices cannot be contacted, it could mean that the application server is down. Check first that the server is running, and verify that the application is configured properly in it's web server. Restarting the server should clear up the problem.

  3. If the application is not running, start the application. You do not need to restart the Jazz Team Server. It will continue to poll the application for status. When the application is back online, the status will be updated in the UI.
  4. If the application is running, verify that you can contact the application, such as CCM, at https://ccm.example.org:9443/ccm/appServerRenameStatus. If you get a 404 error, it indicates that the application is not a 4.0 or later application. An application must be version 4.0 or later to support server rename. You can perform an upgrade before doing a server rename. For details, see roadmap_clm_upgrade.html.
  5. Check the Jazz Team Server and application logs for more detailed error messages.
  6. Check that a .mappingEvent file is present in the server/conf/ directory of all applications.

The UI shows that the rename is complete but there are errors

In this case, the UI shows that the rename is complete, but there are errors when an action is performed against the application. This indicates that the rename is not complete.

  1. Check the application log to determine if it thinks the overall rename is complete.
  2. Stop the application.
  3. Open the application war file and go to WEB/web.xml. Look for the following elements in the XML:
    


<filter>
   <filter-name>bridgefilter</filter-name>
   <filter-class>com.ibm.team.repository.server.servletbridge.BridgeFilter</filter-class>        
</filter>
         
<filter-mapping>
   <filter-name>bridgefilter</filter-name>
   <servlet-name>equinoxbridgeservlet</servlet-name>
</filter-mapping>
  4. If these entries do not exist, then the applications never knew that the overall rename completed. Add the entries and redeploy the war file. Restart the application server and open a page in the browser that will trigger the application to start. For example, go to https://ccm.example.org:9443/ccm/admin for the CCM application.
  5. Check that the other application war files contain the entries and perform the same set of steps if the entries do not exist.

Finalize Server Rename fails

A number of things happen on the Jazz Team Server after all of the application renames are complete.

  1. Check the Jazz Team Server log to determine what finalization step failed.
  2. It is possible that there is an error updating the data warehouse. Verify that your data warehouse configuration is correct and that the database server is available.
  3. After identifying the problem, follow the General Recovery Procedures. It is not possible to retry the finalization step.

A mapping event file is missing

If your environment is distributed, it is possible that a mapping event file did not get copied to the application configuration directory. Check that the server/conf/ directory of the failing application contains a .mappingEvent file. If no .mappingEvent file is present, do the following:

  1. Stop the application.
  2. Copy the .mappingEvent file from the server/conf/jts directory to the server/conf directory for the application.
    Note: All of the .mappingEvent files for a given JTS topology are identical.
  3. Restart the application server. You do not need to restart the Jazz Team Server It will continue to poll the application for status. Once the application is back online, the status will be updated in the UI.