It can be useful to be able to create custom link types for RTC. This is Interesting if a special business logic/behavior needs to be implemented and the available link types don’t fit. How can this be done?
It is surprisingly easy to do as Eduardo describes in Creating a New Link Type in his blog Extending Rational Team Concert – RTC Extending. I had to do it recently and thought it would be useful to describe the experience, adding a bit more detail to the content of the blog above.
License and Download
The post contains published code, so our lawyers reminded me to state that the code in this post is derived from examples from Jazz.net as well as the RTC SDK. The usage of code from that example source code is governed by this license. Therefore this code is governed by this license. I found a section relevant to source code at the and of the license. Please also remember, as stated in the disclaimer, that this code comes with the usual lack of promise or guarantee. Enjoy!
Just Starting With Extending RTC?
If you just get started with extending Rational Team Concert, or create API based automation, start with the post Learning To Fly: Getting Started with the RTC Java API’s and follow the linked resources.
You should be able to use the following code in this environment and get your own automation or extension working.
Please note that it is at least up to RTC 6.0.2 not possible to create custom link types that connect items in different repositories. The built in link types for example Tracks/Contributes to and Related Change request are available, but it is not possible to create custom links that behave this way.
Please note that custom link types at least up to RTC 6.0.2 are ignored by the data collection component and can not be used for reporting purposes.
Creating a Custom Link Type
All that needs to be done to create a custom link type is to create a plug-in.
Oh, no! Another Extension! Can’t I just define a new link type in the process configuration? I can literally hear it 8). Unfortunately that is not supported in RTC today. Vote for this work item if you want this kind of capability.
On the other hand, if there is really a need for business logic and operational behavior for the link type, an extension would be needed and it would not matter.
To make the new link type available in the Eclipse UI as well as in the Web UI, the plug-in needs to be deployed in the client as well as in the server. The RTC SDK calls this common API and it makes sense to follow this example.
As explained in other posts already it is crucial to come up with a good naming schema for the various projects and ID’s needed. Have a unique part in it (in my case js as infix) to be able to find it on disk and in the UI.
When creating the link type an ID for the link is needed as well as ID’s for the endpoints of the link. It is crucial to keep these values once they are chosen. If you change them while developing, you would otherwise introduce dangling references into your test model. I managed to damage my test database and got unreliable results when doing this. If this happens, it is possible to delete the folder server that sits in the same folder as the workspace and create a new test repository running the [RTCExt] Create RTC Test Database JUnit test as described in the Extensions Workshop.
This is the extensions editor for the plug-in I created:
Different to the aforementioned blog post, the plugin defines a component as well as the link type. The reason is that the component allows to see if the plugin was successfully deployed in the server. At some time in the future a component might become required as well. So I always define a component for my extensions.
You can use the context menu of the editor to add the the extension elements for the source, target, endpoints and the itemReferenceTypes.
The endpoints allow to specify the multiplicity. This has actually an impact on how the links behave. If an endpoint specifies 0..1 as multiplicity, only one item can be referenced with the endpoint. If an item is selected already and another item is chosen in the add link dialog, the old item is replaced by the new one.
The plugin.xml looks as follows
The implication of the values in the plugin.xml can be found in the extension point description that can be opened from the extension point itself. Review it to understand the options. From that description:
- id – String id for the link type.
- editors – Semicolon separated string of ids of those components permitted to create and delete links of this type. For example, the string “com.ibm.team.repository;com.ibm.team.scm” specifies the two components “com.ibm.team.repository” and “com.ibm.team.scm”. If the attribute is not present, this indicates that there is no restriction regarding which components (or client) is permitted to create and delete links of this type.
- constrained – If true, the defining component requests that Links of this link type not be created by other components (without permission, or without going through an API provided by the defining component).
- internal – If true, this link type is an internal detail of the implementation of the defining component, and is not intended as a generic link type which users can freely create, delete and view.
- componentId – The id of the component defining this link type. Component ids are declared using the
com.ibm.team.repository.common.componentsextension point. If set and if constrained=true, then only services that are part of that component may save and delete links of this type.
The itemReferenceType entry is still a bit mysterious. It is easy to review existing examples. On the com.ibm.team.repository.common.linktype extension select “Show References” in the context menu and browse through the examples. Especially the references in com.ibm.team.workitem.common are of interest. It is possible to define different kinds of endpoints, dependent on what items to link.
In this case work items are supposed to be linked to work items. Both ends select this itemReferenceType. Please be aware that this kind of links will only work within one CCM repository. It will not allow to link across repository borders. The are other CLM link types that would allow this to happen.
I added some icons for the link types that show up in the editors. For the final deployment, I made sure that the folders icons and META-INF as well as the plugin.xml file are selected in the binary build.
I tested the new link type in a Jetty based test server OSGI2 launch as well as in an Eclipse2 Application launch.
Prepare to Deploy
As already mentioned the common plugin needs to be deployed in the server as well as in the Eclipse client. Please follow Lab 6 in the Rational Team Concert 4.0 Extensions Workshop if you have never done this and want to understand how deployment works in general. The workshop explains in great detail which files you need to deploy on the server. The procedure below follows the deployment procedure on the server side. Other than in the workshop the client extension gets deployed using an update site.
To make this easier I created a Feature project as well as an Update Site project. To make deploying it in the server easier I also created a normal Eclipse project that contains the deployment folder structure as well as the provision profile INI file. The projects look as follows:
Once the Update Site project is built, It is easy to copy the site.xml file and the folders features and plugins into the folder js_custom_linktype in this project.The folders and contained files in this project can then used to easily deploy the extension on the server using copy paste. It is easy to do, reliable and repeatable.
The provision profile js_custom_linktype.ini looks as follows:
It references the sub folder in the site folder that will contain the feature and plugins folders, once it is copied over to the server for deploying.
TIP: Always delete all content of the Update Site project except the site.xml before building the update site again. I have seen cases where subsequent builds did not successfully pick up all changes.
Deploy in the Eclipse client
To deploy in the Eclipse client, use the Help>Install New Software menu, add the Update Site (browsing to the folder that represents the Update Site project) and install the extension. You can package the Update Site or provide it in a web server in a company context as well.
Deploy in the Server
Copy the generated folders and the site.xml file into the folder underneath the sites folder which is referenced by the provision profile js_custom_linktype.ini file in the serverdeploy project folder. This would be easy to automate with a build script by the way.
Now select the folders provision_profies and site with all the content and copy the into the servers folder /server/conf/ccm. Allow to overwrite the folders and request a server reset. Then restart the server.
Add the New Link Type to the Quick Information Presentation
As Sam suggests in his comment below, you also want to add the new link type so that it shows in the quick Information presentation. This is done in the Process Configuration>Project configuration>Configuration Data>Workitems>Quick Information Presentations. It allows the workitem summary page Quick Information section to show a count of and quick link to the new link in a workitem This would look like below:
Admire your work
You can now admire the result of your work in the work item editors. If not, check your deployment setup. As usually the first attempt was, of course, on a test server to not affect the production system until you have perfected your deployment process.
Too many Link Types! What to do?
If you have created all the new link types your business demanded, users might start to complain that there are too many link types and many are not needed anyways. You knew that would be coming and decided long ago to review the article Customization of work item editor presentation to show or hide link types in Rational Team Concert. to understand how to fix this issue once needed.
That was easy, wasn’t it? Now you can create behavior based on the link type.
I have tested it against a test server on Tomcat and Derby. There is no real code this time. However, as always, I hope the post is an inspiration and helps someone out there to save some time. If you are just starting to explore extending RTC, please have a look at the hints in the other posts in this blog on how to get started.