What's the deal with the CLM Public URI?

Far too many times I have seen the mistake where a customer has installed one or many of the CLM applications and either failed to set the Public URI or set the Public URI to something that is not appropriate, such as a host name tied to the network infrastructure.

It is important to give thought beforehand about how you would like your clients to access your CLM links and applications. This means, that a scalable URI design needs to be created (to allow more applications to be added) even before the first CLM application is deployed.

Why is it important? Its important because the URI is the de-facto unique identifier that customers and integrations will use when linking to CLM data. Any change to this URI (due to a host name changing for example) can have implications to not only links embedded in emails and bookmarks but other application integrations (including the CLM integrations RM, CCM and QM).

You generally want a URI that reflects the static business meaning of the data that is being linked to. For example: https://jazzdev.ibm.com/ccm is good, https://aix61boxonmydesk.ibm.com:7255/ccm is not because it identifies both the hardware hosting the application and the port.

Some customers have asked why we cannot have the CLM application figure it out itself (like the 2.x products did). Yes, the 2.x era products allowed this and, yes, resulted in unpredictable link behaviour. (It is not allowed any more.)

Here is the problem : There is no reliable way of getting the host name of a machine because the machine itself may not know what it is (if its behind a proxy for example.)

If no public URI is set,  an attempt is made by using something like:

InetAddress.getLocalHost().getHostName()

What does this return? Well.. as Java is the CLM implementation technology. it seems that this is determined by the rules specified here

http://docs.oracle.com/javase/6/docs/api/java/net/InetAddress.html#getHostName%28%29

 

Reverse lookup behaviour is really determined how the network and DNS is configured.  An example sequence to determine the URL could be:

1. If Public URI is set then no reverse lookup needed the public URI setting is used. end.
2. If public URI is not set, the host name must be determined through getting the IP address for the primary network device then name resolution will do.
• look in the host file
• DNS Reverse lookup

Some problems with this:

1. If server IP address is not resolvable on the server itself (either in hosts file nor lookup) then an exception is thrown and IP address is used.
2. If DNS is misconfigured, IP address can return as host name
3. Some other network misconfiguration/bug is causing getLocalHost call to return 127.0.0.1/localhost
4. Which host name? Which network device? There could be many combinations.

Even if this worked, it is still not good enough!

Why? Simple example exercise.. I want to host RTC on my work laptop, and i don't know what my public URI should be.

Let me try to find out.

From hostname command:

[kuschel@tpborisk7 conf]$ hostname
tpborisk7.ibm.com

Cool.. let's do an IP lookup on the host name:

[kuschel@tpborisk7 conf]$ nslookup tpborisk7.ibm.com
Server:      5.4.3.2
Address:    5.4.3.2#53

** server can't find tpborisk7.ibm.com: NXDOMAIN

No good. This is because i do not have a DNS entry for my laptop's host name.

Let's try my NIC IP Address?

[kuschel@tpborisk7 conf]$ ifconfig eth0
eth0      Link encap:Ethernet  HWaddr F0:DE:F1:58:9B:7D 
          inet addr:192.168.2.35  Bcast:192.168.2.255  Mask:255.255.255.0

Do a reverse lookup on the IP:

[kuschel@tpborisk7 conf]$ nslookup 192.168.2.35
Server:        5.4.3.2
Address:    5.4.3.2#53

** server can't find 35.2.168.192.in-addr.arpa.: NXDOMAIN

Also not good.. DNS has no entry for this IP.  Even if it did, it would be purely local to the subnet! (192.168.x.x).

My Wireless NIC? Resolves locally on my home network but not publically.

Ah! Thats right, I am using VPN:

Now what is my ip address (I am using a VPN tunnel)?

[kuschel@tpborisk7 conf]$ ifconfig tun0<
tun0      Link encap:UNSPEC  HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00 
          inet addr:5.4.3.100  P-t-P:5.4.3.100  Mask:255.255.252.0

What is the hostname that corresponds to this IP?

[kuschel@tpborisk7 conf]$ nslookup 5.4.3.100
Server:        5.4.3.2
Address:    5.4.3.2#53

Non-authoritative answer:
100.3.4.5.in-addr.arpa    name = tpborisk7.torolab.ibm.com.

Authoritative answers can be found from:
5.in-addr.arpa    nameserver = ns.ibm.com.
5.in-addr.arpa    nameserver = ns2.ibm.com.
5.in-addr.arpa    nameserver = ns3.ibm.com.
ns.ibm.com.    internet address = 5.3.3.3
ns2.ibm.com    internet address = 5.2.1.2
ns3.ibm.com.    internet address = 5.1.2.3

Bingo! So I should use tpborisk7.torolab.ibm.com as it seems to be publicly addressable but its simply a bad public URI (machine name plus location).

So how is CLM supposed to figure this out? My laptop has have 10 network devices, some with resolvable names, some not.

What is also key here is that neither my NIC nor my host name is the real public address!

One cannot expect the CLM applications to figure this out as there is simply not enough information. (It could even use something like an IP address if it cannot resolve a name.)

Hence the need for a Public URI!

Put the same thought behind the CLM public URI as you would for a URL you would host pages or application for the general public on the internet. It should be thought of,designed and owned by CLM!

Luckily, For people who are in the unfortunate predicament of having a bad public URI, there is hope in 4.0 with server rename.

Automated builds using Visual Studio and Rational Team Concert

This is the third part of a blog series on using Rational Team Concert (RTC) with Visual Studio (VS). In part 1, I showed how to set up a basic solution in visual studio integrated with Rational Team Concert. In part 2, I provided a working OSLC sample which we will use in an automated build. We will set up an automated Jazz Build for Visual Studio using using the Jazz Build engine.


In order to do this you will need (in addition to the those required for the previous two parts):


-The Jazz Build Engine 3.0.1.2
-Rational Team Client for Eclipse 3.0.1.2


You may wonder why you need the eclipse version of Rational Team Concert. While you can, request builds, examine build status and see build results from visual studio, you can only create build definitions with the eclipse client at this time. So you will need to unzip the client  launch eclipse and connect to the project area to do this. To understand how to do this you can take a look at the CLM information center (Hint: Go to Team Artifact view and create a repository connection)


To keep text editing to a minimum I will provide the visual studio solution which has all the files required to perform an automated build. You can find it here. Unzip this over the corresponding directories in the solution created in the first two parts or if you are starting from here just unzip this and add it to the correct components (as specified in the first part) in RTC.

This is what should be done:


1. To keep things simple we will set up the automated build on the same machine as the visual studio.  Install the Jazz Build Engine (JBE) in the default directory. In my case, this is the C:\Program Files (x86)\IBM\TeamConcertBuild directory. You will see that all property files are configured with the assumption that the build engine is installed here. 


2. To, once again, keep things simple, we will use the current user (the one you used to log into visual studio) as the build engine user. The first thing we need to do is create a workspace which will be used by the build engine to do the build. Go into Visual Studio and create a new repository workspace from the "OLSC Stream". Right click on the OSLC Stream in the project area and click "New Repository Workspace..."

Call the workspace "OSLC Build Workspace" but do not load the workspace when asked as it will solely be used for build 
purposes.

2. At this point we will need to prepare some files in order to facilitate the build. We will be using the MSBuild process to perform our build and we will need to augment it so that it communicates with the jazz repository once it starts and finishes.  MSBuild uses the .proj files to build and we need to modify this file to add some pre and post-build hooks. To do this we would need to change the "OSLC Consumer.proj" file. To modify this file from visual studio it needs to be unloaded and edited. This can be accomplished by right clicking the project in visual studio, click unload and then subsequently "Edit OSLC Consumer.proj". 
Navigating to the end of the file you will see that the following has been added towards the end of the file:



<Import Project="..\OSLCProperties.xml" />
  <Target Name="BeforeBuild" Condition="'$(fetchDestination)'!= '' ">
    <Exec Command="$(AntCommand)-DactivityLabel=startActivity $(propertyFile) $(jazzbuildxml) startActivity" />
  </Target>
  <Target Name="AfterBuild" Condition="'$(fetchDestination)' !='' ">
    <Exec Command="$(AntCommand) -DactivityLabel=publishActivity $(propertyFile) $(jazzbuildxml) publishActivity" />
   </Target>

This uses an OSLCProperties.xml which contains the properties that are used here: $(AntCommand),  $(propertyFile) and $(jazzbuildxml). The $(fetchDestination) will be passed into MSBuild using a command line argument defined in the build definition. (We will do this later).


You will find the OSLCProperties.xml in the solution directory (the root directory of the work space and contains the following. You may need to adjust the JBE root directory to reflect your environment.



<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>  
    <AntCommand>"C:\Program Files (x86)\IBM\TeamConcertBuild\jre\bin\java.exe" -cp "C:\Program Files (x86)\IBM\TeamConcertBuild\buildsystem\buildengine\eclipse\plugins\org.apache.ant_1.7.1.v20090120-1145\lib\ant-launcher.jar" org.apache.tools.ant.launch.Launcher -cp "C:\Program Files (x86)\IBM\TeamConcertBuild\jre\lib" -lib "C:\Program Files (x86)\IBM\TeamConcertBuild\buildsystem\buildtoolkit"</AntCommand>
    <propertyFile>-propertyfile "C:\Program Files (x86)\IBM\TeamConcertBuild\buildsystem\buildengine\eclipse\OSLCBuild.properties"</propertyFile>
    <jazzbuildxml>-f $(fetchDestination)\OSLC\jazzbuild.xml</jazzbuildxml>
  </PropertyGroup>
</Project>

The last file needed is the actual ant file that contains the tags used to communicate with the jazz repository, the jazzbuild.xml file. It contain two activities, one that is launched after the build, "startActivity" and another that is lauched after the build, "publishActivity" that is used to publish the build result. (They are launched from the msbuild tool using the hooks in the .proj above that it uses to perform the build.)


All of these new files should be checked in and delivered into the "OSLC Stream" so that they may be used by the Build engine.

3. Now lets create a build engine and build definition in Rational Team Concert for eclipse. Launch RTC for eclipse and create a "Jazz Build Engine" build definition for the OSLC project area by right clicking on "Build Engines" and give it the name "OSLC Build Engine".  

You may now see a warning that the build engine is not running:

This is a good indication that the build engine is not running. Lets start it now.


4. To, once again, keep things simple, we will use the current user (the one you used to log into visual studio) as the build engine user. With that in mind execute run the build engine. You should see command prompt output as follows:



C:\Program Files (x86)\IBM\TeamConcertBuild\buildsystem\buildengine\eclipse>
jbe -repository https://<rtc host name>:<rtc port>/ccm -userId <rtc build username> -pass <rtc build user password> -engineID "OSLC Build Engine"
2012-03-04 10:29:29 [Jazz build engine] Running build loop...
2012-03-04 10:29:29 [Jazz build engine] Waiting for request...



Now refreshing the build engine page in RTC should eliminate the error.


5. Next we need to create a new build definition called "OSLC Build" for the OSLC project area of type "Jazz Build for Microsoft Visual Studio Solution - Jazz Build Engine"

Ensure that you select "Jazz Source Control" as a pre-build option:

Select MSTest Configuration as a post-build option.

Once you created the build it should be opened and now you must add the build engine we created previously as a supported build engine in the Overview tab.

In the "Jazz Source Control" tab we must specify the workspace we created previously for the purposes of building as the Build Workspace and also specify a directory that will be used to load this workspace during the build process called "OSLC Build Workspace". We should also specify "Delete directory before loading".

Now we must specify some details about the build in the "Microsoft Build" tab. Depending on the install path of your visual studio some of these may need to be adjusted according to your environment:

Some things to note on this page. The OSLCBuild.properties file is a file generated by the JBE that contains the properties used during a build. You also see that here we are passing in the $(fetchDirectory) property that we are using above in the .proj hook. We are using MSBuild as it is more suitable for what we want to do but it is also possible to use the Visual studio "devenv.exe" to do the build. This is usually more useful if there are some visual studio integrations that the build depends on (pre compilers, etc.).


The next tab "MSTest Configuration" is also given here but is unused at the present time and is provided for a future lab. It must nevertheless be completed in order for the build to succeed.   You may need to change the paths as appropriate:

Now you should be able to save the build definition and then you are done with RTC for eclipse.


6. Go back to visual studio and refresh the builds area and now you should be able to request a build from here. You may do so now. Leave the default options and submit.

7. After the build request has been submitted you will see it in the build queue. It may take a little while to build and return eventually with a "Completed" status and a green check mark.

8. Whether the build succeeded or not you can double click on the build to see the results, including the logs and, if successful, a link to the resulting .exe in the "Downloads" tab. If something went wrong you can examine the logs to see what the issue is.

Voila! An automated build using the JBE and visual C++!