r7 - 2013-05-14 - 10:12:14 - Main.sbeardYou are here: TWiki >  Deployment Web > DeploymentInstallingUpgradingAndMigrating > MaintainingThePublicURL

new.png Maintaining the public URL

Authors: DavidChadwick, DanToczala
Build basis: CLM and SSE

One of the primary architectural principles of the Jazz architecture is to maintain data or artifacts in only one place and link to it wherever you need to access it. In this way you have fewer problems with copied information being outdated or displayed in a less optimal way than the application designed to display and interact with that type of information. Viewers and editors are then provided by the primary application and used wherever that data is displayed as a link. This is known as the linked data concept. The links used to access these assets are standard HTTP (Internet) URLs. There are a variety of development wiki and blog entries that have been written about maintaining a stable public URL for your Jazz repository data.


This explanation is meant to clear up some common questions and misconceptions about the possibilities and issues surrounding the movement of Jazz servers, issues surrounding URL stability, and how all of this can impact your Rational Jazz CLM architecture. The basic issues imposed by a RESTful architecture will have a definite impact on the solution architecture that you put into place to host your CLM solution. What you do will depend on your overall software development tools strategy, as well as your user community.

We try to keep in mind in this discussion that while some things may be possible from a technical standpoint, they are not good paths to go down due to operational, organization scaling or performance concerns. So while it may be technically possible to deploy the CLM solution with a Derby database, the limitations of this approach make it an intelligent thing to avoid for performance and scalability reasons. The key here is to not just ask the technical questions ("Can I deploy with Derby as my back-end database?"), but to instead ask intelligent questions (("Can I support 1000 concurrent CLM users with a deployment on a Derby database?"). The answer to the first question is "Yes", but following this path will get you into trouble. Be sure to think in terms of the solution for your end users, and not get too focused on the technical questions with no context.

The rest of this article is posed as a series of frequently asked questions, along with some answers and some explanation of the answer. We will try to focus on the intelligent questions, and provide you with intelligent answers. You may note that we have a number of links to the Infocenter, which is a very good source of information.

Basic Concepts

Often an understanding of some of the basic concepts involved with a Jazz solution make things much more clear.

Why is the URL so important?

The Jazz architecture is based on some basic concepts, like REST and Internet addressable and discoverable resources. There was a funny and easy to understand explanation of REST by Ryan Tomayko's, but he has pulled that down due to people possibly mistaking it as being sexist. Now it's probably best to just do a web search for "REST explained", or the platform entry out on Jazz.net. The Jazz RESTful architecture has the various artifacts manipulated by the Jazz based tools. You can gain some basic understanding by looking the Infocenter entry on Planning your URI's.

In the Jazz environment, artifacts are considered resources, and these resources are all accessible by using a URI (or web) reference. That is how they are accessed. Relationships between artifacts are expressed as hyper-links between these REST based artifacts. So think about this. Changing the name of the base URI for your server would invalidate every resource in your repository. It would also break any of the links to your resources from other applications.

Was the public URI required in the Jazz 2.x products?

It was, but it was not enforced. There may be instances where a server was configured without a public URI. We strongly recommend that you set it, and choose a common stable URL that users have been using to access the server. You must configure a public URI prior to upgrade.

Is a public URI required in the Jazz 3.x or later products?

Yes. We have added better guidance in the Infocenter and in the server setup user interface. Setup also performs more validation to discourage configuring a potentially unstable URL (e.g., IP address, short name, localhost, etc). Unless you are setting up a demonstration environment which you will not need the data from, do NOT override these warnings, and make sure that you select a fully qualified domain name as the basis for your public URI.

Server Moves and Renames

Our Jazz customers often have questions about renaming and moving the application servers supporting the Jazz tools.

Can I move my Jazz/RTC installation to another server?

The Jazz applications can be moved to different physical machines as long as they keep the same public server root URI. A stable server URI can be preserved by DNS or reverse proxy topology. Setting up a reverse proxy server will allow you to retain the previous public server root URI, while hosting the application on a server with a different name. Remember to always use a fully qualified domain name for your public server root URI.

How can I change the public URI of my Jazz application server? Or my Jazz Team Server?

It is not currently supported to change the public URI in a CLM 3.0 solution, however starting with the CLM 4.x tools, there is a server rename operation that can be performed which will change the public URI. Support for server rename is initially limited to two scenarios in version 4.0 and 4.0.0.x: moving a pilot deployment to production, and copying a production deployment for the purpose of creating a staging test environment. In version 4.0.1, we have added support for renaming the production environment and support for many of the integrations that are not supported in version 4.0. (For details, see Impact of Server Rename and Integrated Products (Version 4.0.1). Even for the scenarios supported in version 4.0, it is important that you understand the other products that you integrate with:

  • If you are planning to move a pilot deployment to full production and your deployment includes unsupported integrations, do not perform a server rename. Your integrations will break.
  • If you are setting up a test staging environment, you must create "dummy mappings" in the mapping file for the URLs of any additional integrations in your deployment. This is to prevent contamination or linkages from the staging environment into production.

For customers that think that they may be good candidates for use of the server rename functionality, it is best to review and understand the guidance article on jazz.net.

Can I use repotools export and import to do a server move?

This is not supported. Repotools export and import are for database migration: e.g., migrating from one database vendor to another, or from one version/platform of a database to another, where native backup and restore is not supported by the vendor. Generally the off-line backup and restore facilities provided by an enterprise database will be much faster than repotools export and import. There is currently not any processing in repotools export or import that will fix all of the URL references.

I changed the public URI and it seemed to work. What's broken?

There are numerous internal references within a Jazz repository. Some examples of this are:

  • Links in opaque resources (dashboards, RTC enterprise extensions)
  • Project area URLs
  • User URLs
  • Facts in the data-warehouse - The data-warehouse tables store hashed URLs as identifiers for resources
  • Fully qualified URLs in plans or work items

The development team is assessing the impact of a public URI change and possible workarounds to some of the issues mentioned in this article.

Can I change the public URI of an RTC 2.x server?

Officially this is not supported or recommended. However, the extent to which URLs are stored in RTC 2.x is not as pervasive as in RTC 3.x or in any of the linked CLM repositories, especially if there are no cross-repository or C/ALM links. You can change the public URL prior to upgrade, with some data loss:

  • Fully qualified URLs in work items will be broken
  • Work item links in emails will be broken
  • Artifact links across repositories (e.g. to other RTC servers or RQM or RRC) will be broken
  • Facts in the data-warehouse - In RTC 2.x, this would only affect customers also using Insight for reporting
  • Any integrations to other tools will be broken

I saw the article on jazz.net about link migration - won't that fix everything (http://jazz.net/library/article/558)?

This was targeted to a specific use case where a CQ server was moved, to allow fixing work item artifact links in the RTC repository. This is NOT a general purpose server move solution, although it will likely be a part of any server move solution that is made available in the future.


Application servers are not the only servers supporting a Jazz solution. We also get questions about moving the database servers.

Can I move my database from one database server to another?

Yes you can. The database location is configured in the teamserver.properties configuration file, and it is not persisted anywhere else. Remember that you want to minimize latency between the application server and the database server, and it is not recommended to distribute it over a WAN. The latency between the Jazz application servers and their associated database repositories will have a direct impact on the performance of your CLM solution, which is what you would expect.

Is there some set of SQL I can run in the database to fix everything?

The structure of the databases that support the Jazz applications is an internal implementation detail. The table structure is optimized for reads, and thus item contents are stored in blobs. Additionally, the format of some resource content is opaque to the framework and component specific (e.g., binary, rdf, xml, etc). There is no trivial solution mechanism to reliably process all the data in the database.

You can however take some steps to tune your database for better performance. You can check the general database tuning section, as well as the specific sections for DB2, Oracle, and SQL Server.

Testing and Staging

Sometimes you just need a copy of the data that you already have, in order to provide a testing or staging environment, or to provide a demo environment. Here are some common questions on those topics.

I need to replicate a repository to a testing and staging environment. How can I do that if I can't change the public URI?

if you are using CLM 3.x or earlier, you can set up an isolated network where the hostnames are resolved to the test machine(s). Make sure that your testing clients also resolve to the test machines. See the Infocenter entry on creating a staging environment for more information.

If you are using CLM 4.0 or later, you can use the server rename functionality. It is best to review and understand the guidance article on jazz.net before attempting to use server rename for this purpose.

I have a test database that I use to give demos. I thought I could use export and import to put this on different machines or share it with others. What can I do?

Choose a test host name for your URL, e.g, rtcdemo.example.org. Anyone executing the demo can add this entry to their local hosts file and resolve it to the loopback address. This will allow you to run a demo on a single machine, with all of the artifact links kept intact.

Related topics: Server Rename

External links:

Additional contributors: JimRuehlin

Edit | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r11 | r9 < r8 < r7 < r6 | More topic actions...
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use. Please read the following disclaimer.