Answer: RTC Extensions.

I’ve been turning my focus to RTC Extensions recently, and that means I’ve been buried in learning this deep area. The fact is, this is the most technical and complex area of RTC customization, and probably the most difficult to find information about.

The first place you should look for information about extending RTC is the RTC Extensions Landing Page. It’s being reviewed now and should be available on Jazz.net soon. I wrote this as a way of collecting all the existing information about extensions in one place. There’s actually quite a bit of information out there about extensions. Start with the Landing Page (when it’s posted) and you’ll gain access to a lot of material.

Even so, learning about RTC Extensions is a steep mountain to climb. Extensions are built as Eclipse plug-ins, which is great because it provides a consistent and well understood way to extend RTC. This is true for both client-side and server-side extensions. But if you don’t already know how to write Eclipse plug-ins, it’s one more technical hurdle to jump over. The good news is that there are great books out there that teach you Eclipse plug-in development.

The RTC Eclipse API is also not fully documented. This is partly by design – the official API is not the complete API. The RTC development team is cautious about supporting interfaces and classes that may change significantly in the future. But you’ll inevitably need some unofficial API calls to accomplish what you want to do. In fact, only parts of the client-side API are official, and none of the server-side API is official. But many extensions need both server and client side actions.

The result is that there’s some searching, experimenting, and admittedly frustration when you build an extension. Your first extension will be the toughest because you’ll be learning where you need to look to find things, and you’ll be learning the basic philosophy of how to things done in RTC.

As my colleague Rolph Schoon says, one of the best ways to learn extensions is by monkey-see monkey-do. Or more accurately, code monkey-see, code monkey-do. Leverage the sample code, step through SDK source code when possible, etc. The Extensions Landing Page will provide some extensions that you can use as code samples, and we’ll be building more.

Also, don’t run right to extensions when you want to add a new feature or customize a process. Given the learning curve and the fact that you’re writing/debugging/maintaining code, go for easier solutions if possible. Create work item templates, customize your process template, or work through the Eclipse or Web UI to accomplish what you need. If you can’t get to where you need to go that way, then turn to using the RTC API.

More to come, stay tuned.

Here’s an excerpt:

The concert hall at the Syndey Opera House holds 2,700 people. This blog was viewed about 9,700 times in 2011. If it were a concert at Sydney Opera House, it would take about 4 sold-out performances for that many people to see it.

Click here to see the complete report.

In an earlier blog I made it clear (I hope) that you can’t change the public URI of a CLM application, no matter what. While this may change in the future, it’s the law of the land right now.

But sometimes you want to move an application to a new server for load balancing or performance. And sometimes you might need to use a different URL to access your CLM products due to changes in your IT environment. How is that accomplished?

There are two strategies you can use: Virtual hosts and reverse proxies. It can be a little confusing as to when to use which one, so here’s a summary.

Virtual Hosts

Use virtual hosts to move a CLM application from one machine to another. The URL you’re using to access the application is the same, but the underlying IP address must change. This is all done via a DNS server and is transparent to the users. The pre-requisites for using virtual hosts are:

• Each application’s public URI must describe a unique Fully Qualified Domain Name (FQDN). Said another way, each application must have its own server name. For example, the JTS would be at https://mycorp.dev.jts.myserver.com:9443/jts and RTC would be at https://mycorp.dev.rtc.mydepartment.com:9443/ccm. If the jts and ccm applications use the same server name, e.g. https://mycorp.myserver.clm.com:9443/jts and https://mycorp.myserver.clm.com:9443/ccm you wont be able to move them to different machines because you can’t map the same IP address to two different locations (servers).
• The port number cannot be changed. Sometime people think you can change a port number or root context, but they are actually part of the public URI so they can’t change. When you move the application to a new machine, you need to use the same port number as the old machine.

Take these two constraints into consideration when you install any CLM product. If you do, you’ll be able to easily move them to other machines as your needs change.

Reverse Proxy Server

Reverse proxies allow you to do all sorts of magic to a URL. While you can’t change the public URI of a CLM application, a reverse proxy can re-map parts of the URL such as the FQDN and port number. So if you need to change the way a CLM application is accessed, you can do so by having the reverse proxy re-map everything so it’s transparent to the CLM application (and the users). The CLM application continues to use the same public URI that you installed with.

Reverse proxies require FQDNs. If you used localhost, an IP address, or a non-FQDN for your public URI, you’re out of luck. Your solution in this case would probably be to install a new version of CLM using an FQDN and use that for all new projects. This situation is only possible if you are using (or have upgraded from) a CLM product prior to version 3.0.1.

Check out Dave Chadwick’s article on how to plan for the future with URIs, which covers this topic in more detail.

Use this page as your one-stop-shop for technical information about the upgrade.

There’s a link to the the WAS trial download from the CLM download pages. After you get a permanent license (try speaking with your account rep or Passport Advantage), you’ll need to upgrade the trial to a permanent product. You can get the instructions here:

• Upgrade from trial in WAS version 7
• Upgrade from trial in WAS version 8

Parameter Description: Value: Type

• cursor_sharing: SIMILAR: Fixed (could consider force, we do have queries with literal values but I don’t think they are repeated enough to matter)
• db_block_size: 8192: Fixed (seems fine, larger is better but seems to be lot’s of arguments about going to 32 k)
• db_cache_size: 51200000: Fixed
• db_cache_advice READY Fixed
• db_file_multiblock_read_count: 8: Fixed (Oracle recommends letting the system set this)
• Instance_names: <sid>: Fixed
• java_pool_size: 16777216: Fixed (we don’t use in db java)
• large_pool_size: 0: Fixed
• log_buffers: 819200: Fixed
• open_cursors: 20: Fixed (up it if you are getting errors)
• shared_pool_size: 38400000: Fixed
• undo_management: AUTO: Fixed
• undo_retention: 300: Fixed
• processes: 50: Fixed (15 + number of user sessions + 1)
• pga_aggregate_target: 51200000: Fixed
• Workarea_size_policy: Auto: Fixed
• undo_tablespace: UNDO01: Fixed
• audit_trail: Db: Fixed

One of the great things about jazz.net is that it gives Jazz-based development an open source feel. You can follow the progress of this critical issue by watching (and contributing to) the work item that’s linked above.

Then I’m asked “OK, so what’s the shortcut?”

That is the shortcut.

No, really. That IS the shortcut. If you try to take a shorter shortcut you’ll end up like Homer Simpson when he said “Alright, we’re here. Let us never speak of the shortcut again.”

The long way of learning how to upgrade is the way I did it: Spend a couple of months testing upgrade scenarios without documentation. You don’t want to do that.

So instead spend a couple of days understanding the upgrade. Let the Upgrade Workshop take you by the hand and lead you through an upgrade scenario. It won’t be exactly like your scenario, but you’ll learn a lot about what’s involved in upgrading, and you’ll get great insight into general CLM product administration. You can compare the customized upgrade steps you generated to the Workshop and make notes and observations.

Read. Everything. Carefully. Yes, I know you’ve done this kind of thing before. And you’re a hot-shot technical expert. You get it, you can connect the dots on your own. I understand all that when I say “Read everything carefully.” Don’t take things for granted or you will step into a bear trap. The upgrade has many steps and many constraints. The workshop and installation steps help point a lot of those out.

The people who get into trouble aren’t the ones who aren’t technical superstars. The folks who get into trouble are the ones who haven’t read the line before and the line after the instruction they’re executing right now. I’m not being metaphorical here. I have had to help people get out of trouble by telling them to do what the line before the instruction they’re on told them to do. These are good technical people who tried to take the Homer shortcut, and now we must never speak of it again.

The people who fail when upgrading are the ones who take the “shortcut” of upgrading without understanding what’s involved first.

So do yourself a favor and take the recommended shortcut. If you don’t take my shortcut, then (as they say in Maine) “You can’t get there from here.”

Helpful Links

• Tox’s Blog: Are You Upgrading to CLM 2011?
• Upgrade Rules
• Upgrade Workshop
• Interactive Upgrade Guide
• CLM 2011 Upgrade FAQ
• CLM 2011 Sizing Guide
• CLM 2011 System Requirements
• CLM 2011 Licensing

So here’s the first thing you need to know when performing admistrative tasks on Jazz-based products:

You cannot change the public URI. You cannot change the root context. 

I’ve had discussions – long discussions – with lots of customers about this, so let me add this one thing:

Under no circumstances should you change the public URI. Under no circumstances should you change the root context.

This Jedi mind-trick is designed to convince you that you can’t change the public URI or root context after it has been set during setup. Really. You can’t. Just stop thinking about it.

You can get around this constraint by using reverse proxies or virtual hostnames. More on those in future posts. But this does not change the actual public URI or root context. Virtual hosts and reverse proxies just re-map the URLs.

I know what you’re thinking now: Why can’t I change the public URI?

Architecturally, Jazz-based products use OSLC and RESTful interfaces. This means that artifacts (data) is referenced with URLs. When a dashboard shows information from a work item, it’s getting that work item information by traversing a URL. When you get a list of dashboards to choose from, each dashboard is referenced internally by a URL. When an RTC work item links to an RQM test case, it does so through a URL.

All those URLs are written into the database. They’re not dynamically calculated. The actual URL is placed into the database.

Jazz-based products construct these URLs by using the public URI and the root context. So if your public URI is

https://my.server.com:9443

and your root context is

/ccm

then every URL that identifies information in the database starts with

https://my.server.com:9443/ccm

If you change the public URI or root context, you break all those links. And your heart will break too.

I know what you’re thinking now: Why not just do a search/replace of the URLs in the database when we change the public URI or root context? Ah, young Jedi, life is not so simple.

The table structure in the database is optimized for reads. The result is that item content is often stored as blobs (binary large objects), not simple text. And some resource content is not directly interpretable by the Jazz framework because the data is component specific. The URL in these components may be stored as binary, rdf, xml, etc. So identifying and replacing the links is not trivial.

That said, there’s plenty of discussion going on amongst developers about making public URIs more flexible. Stay tuned.

References

Dan Toczala’s article on moving CLM applications to different machines (references with URLs that are different from the public URI).

A humorous explanation of REST.

Upgrading CLM products from version 2.x to 3.0.1 is complex. There are many constraints and dependencies, and every installation is different because of the variety of platforms, environments, servers, etc, that can be used for CLM products. If you plan on upgrading to 3.0.1, you should go through the workshop.

You should also do the workshop if you plan on installing and administering CLM applications. You’ll get a lot of insight into how the products are put together. There are a lot of nuts-and-bolts the workshop takes you through that any administrator should be aware of.

If you’re wary of using enterprise-level software with CLM such as WebSphere application servers or LDAP, you should do the workshop. You won’t become and LDAP expert, but you will get a good sense of  how CLM products interacts with these common enterprise platforms. Much of the “fear factor” of using these enterprise products with RTC, RQM, and RRC will disappear by the time you complete the workshop.

The workshop has 5 labs and an appendix:

• Overview
• Lab 1: Set up CLM 2.x, WebSphere, and LDAP.
• Lab 2: Plan the Upgrade
• Lab 3: Upgrade JTS and RTC
• Lab 4: Upgrade RQM, install Data Warehouse
• Lab 5: Upgrade RRC
• Appendix A: Troubleshooting

There’s also zip that includes files and scripts used to populate CLM projects in each product and the LDAP server.

- Jim Ruehlin