What API’s are Available for RTC and What Can You Extend?

Posted on by

This post is about what is available as API for RTC. I will try to provide you with some information about the available API’s. It was confusing to me in the beginning, so I assume others face the same problem.

This post assumes you already read the post about Setting up Rational Team Concert for API Development. Learning to Fly contains references to the most important posts for beginners. Please also consider to look into the Interesting Links page for more examples and downloads.You should understand the RTC Process Fundamentals if you want to do any extension or automation.

The post RTC Process Customization – What you can and cannot do is also a great resource to understand the basics.

The first API’s are only mentioned for completeness. They are not covered in this series of posts, but might be in the future.

REST and OSLC APIs

RTC provides some REST API’s that can be used to access and manipulate data. It also provides OSLC based APIs to access some of its data. See Consuming Rational Team Concert’s OSLC Change Management V2 Services to get started. See the Open Services for Lifecycle Collaboration Workshop and Using Perl to access the JAZZ REST API as an entry point. See Lyo OSLC 4J as a potential framework to access OSLC and REST APIs. This blog post provides you with a different browser extension to use for creating REST and OSLC URL’s.

JavaScript API

RTC provides a limited JavaScript API that can be used for Attribute Customization. The JavaScript API is very limited and allows only to access attribute data in the context of the work item the attribute customization runs. See this blog post or go directly to the Process Enactment Workshop for the Rational solution for Collaborative Lifecycle Management 2012 for some examples.

Relevant links

Available Java APIs

There are really two Java API’s available in RTC, and although they have much in common, there are differences that are important to understand if you want to use them. The following API’s are available

  • The Server API that is used in the server part of RTC (and JTS)
  • The Client API that is used by the Eclipse Client and the Plain Java Client Libraries

The server API is used by server extensions. Server extensions must extend com.ibm.team.repository.service.AbstractService. To get other services use com.ibm.team.repository.service.AbstractService.getService(Class) providing a server service class. Note, the server services used must be entered as prerequisite in the server extensions plugin.xml.

The client API is typically retrieved by using com.ibm.team.repository.client.ITeamRepository.getClientLibrary(Class) providing a client service class.

Please see the relevant examples for details.

RTC Server API

The RTC Server API is used in extensions to RTC that are deployed on the server. Examples for these kind of extensions are Operation Advisors, Operation Participants, Server Tasks and other extensions that are run on the server. The RTC Server API is shipped with the RTC SDK that you set up to have an environment for development. This API is typically found in packages called com.ibm.team.*.service and the interfaces are usually named *Service or *Server for example IWorkItemServer.

This blog has several examples for how to extend RTC using the server API. For example

RTC Common API

Parts of the API are available on the client and on the server. The way you get the API depends on if you have a client or a server extension, however, the services are available as client libraries as well as as services. This API is typically found in packages called com.ibm.team.*.common and the interfaces are usually named *Common for example IWorkItemCommon. In some cases the required services are provided by the extension mechanism. This allows to write some extensions that run on the server, as well as on the client. A good example are Attribute Customization providers. You can find examples in these posts

RTC Client API

The RTC Client API is used in Extensions to any of the Eclipse based RTC clients as well as in the RTC Plain Java Client Libraries. This API is typically found in packages called com.ibm.team.*.client and the interfaces are usually named *Client for example IWorkItemClient. The RTC Client API is shipped with the RTC SDK and partially shipped with the Plain Java Client Libraries.

What? The Client API is shipped twice? Why would anyone do that?

RTC Client SDK

The reason for shipping the client API in the RTC SDK and the Plain Java Client Libraries is really simple. You need it in the SDK to develop extensions for the Eclipse based RTC clients. The SDK provides you with the source code and allows to search the code in the Eclipse Plugin Development Environment PDE. Strictly speaking, you would not need the source code to develop the extensions, because the Eclipse client has the relevant parts of the API already installed as plug in’s and that is enough to be able to write extensions. However, it makes development so much easier. The RTC (client) SDK also ships some internal classes and tests that you can use to find examples for the API usage.

Plain Java Client Libraries

If you just want to run a small Java application to do some automation outside of the Eclipse client, you would need only the JAR files for the API, and some JAR files that it depends upon. It would be quite some effort to identify the JAR files in the Eclipse client you need. So the Plain Java Client Libraries  has the required JAR files bundled for you to use. This makes setting up a Plain Java Client application you developed much easier.

The Plain Java Client Libraries ship only the documented and public API. They are missing a lot of RTC Eclipse client specific code.

The post A RTC WorkItem Command Line Version 2 provides an extensive example for using the API to create and modify work items.

Extending Eclipse based Clients

When mentioning you can develop Extensions to the Eclipse based RTC Clients, that was no typo. The Jazz SCM Command Line as well as the Jazz Build Engine and Toolkit are also Eclipse based clients that can be extended. You can find an example for extending the Jazz Build  Toolkit in this post from Robin. The Eclipse Extension mechanism works for all Eclipse based clients.

There are several posts on this blog that talk about the client API. For Example

What is the Difference Between Client And Server API

Although you can often reuse the client API some things are different in the client and the server API so you need to be careful. The Services and Client Libraries have differences in how they are called and what they provide. Creating, getting and manipulating elements is sometimes slightly different in both API’s and you might need data on the server that you don’t have on the client and the other way round.

What can you Extend and Access?

The Server API allows to extend

  • The RTC Server with operational behavior, event handling, jobs and the like.

The Client API allows to extend

  • The Jazz  Build Engine and the Build System Toolkit
  • The SCM Command Line
  • The RTC Eclipse client
  • Potentially any other Eclipse based client

The Client API allows you to access

  • The RTC server and the data in its repository
  • Parts of the JTS server, for example the User and License management

What can’t you extend?

As far as I know you can not extend the Visual Studio Client, nor the Windows Shell, because both are not Eclipse based.

The available Extension Points and Operation ID’s are explained here.

Why is the API Designed the Way it is?

If you start working against the API, you will realize that, from a human perspective, sometimes things appear overly complicated. For example if you work with enumerations, you need to look up all the literals to find one that has the same Label value as your string you want to use to set it.

My personal view on this is, the API is a byproduct of what needed to be developed to design clients and servers. In the client for example, you will typically have views, that need to show more than one element. Or you have drop down boxes to select enumeration values. This just requires to get at all the data such as literals, project areas etc. needed to be displayed in that context. There is just no need to be able to provide a method that takes some string and looks up an item that has a display value that matches that string.

If you want it to be easier, you can always wrap pieces of code up to better fulfill your requirements and reuse that code.

Don’t Mix Client and Server API

You need to be really careful, to understand what client API is and what server API. Client API usually has client in the package name and you get the services with getClientLibrary() calls. Server code usually has server in the package name and you get services using gerService() from the AbstractService type you extend.

There are some packages with common in the package name, and contain common code that can be used on client and server. Still, you would get the common classes using getService() on the Server and the analogous Client Library with getClientLibrary() on the client.

If you mix the Client and the Server API in a server extension, you might find it works in Jetty – because that potentially has the client and the server part available in the SDK. But once you deploy the  extension on the server it will not load because it can’t find the required bundles. The same applies for client extensions.

The next post will go into the details of the client API.

41 thoughts on “What API’s are Available for RTC and What Can You Extend?”

  2. Hi Ralph,

    Can you let me know in RTC client can I add or remove the context menu option. When we browse the work ticket through our query in query window we get list of work-ticket matching those query. Now when we right click on any column of any work ticket we get some context menu options related with those work ticket. I want to disable some of the context menu in RTC client. Please help me how can I do that.

    I tried below steps:
    1. Added RTC -SDK 4.0.2 into target of RTC plugin development. Windows->preferences -> target
    2. Created new plugin project
    3.Changed plugin.xml

    But nothing works.

    Please can help me.

    Regards,
    Vinod Kumar Singh

    Reply ↓

  3. Hi Vinod,

    if you want to contribute to context and other menus in the RTC Eclipse client, this is rather an Eclipse question. I would suggest to go to http://eclipse.org and search there for how to do it. For example: http://eclipse.org/articles/Article-RCP-3/tutorial3.html or http://www.eclipse.org/resources/resource.php?id=494 .

    You schuld also consider to get yourself a book around Eclipse Extensions.

    I have created menu contributions in the past and also extended existing menus. Menus are provided using just some extension points and there are also examples available as templates if you create a plugin project.

    Having said that, you can extend menus, if you know the menu paths. You can typically not remove menus. to do that, you would have to remove the associated xml from other contributing plug in’s. Eclipse is made for extending and not reducing capabilities.

    Reply ↓

    • Hi Ralph,

      Thank you for your response.

      I have been developing some plugin for RTC but now that I have to remove some options from popup menu when we right click on any object. I have to disable those option that I don’t want common users to use it. It should be like admin restrictions.

      I don’t see option to send you the screenshot or else I would send you the screenshot for some popup menu from which I want to disable some of the options from it or complete remove those options from that popup menu. Using plugin spy I know the exact class that is responsible for displaying those popup menu. But my changes are not even reflecting anything in RTC neither my code is going in debug mode for client RTC. I don’t know why RTC client is going in debug mode. 😦

      Kindly guild me on this.

      Thanks and Regards,
      Vinod Kumar Singh

      Reply ↓

      • As mentioned in my first reply, there is, as far as I can tell, no mechanism to suppress other plugin’s extensions in Eclipse. This has nothing to do with RTC API’s, but is mainly an Eclipse extending issue. You can only extend Eclipse, not limit it (as far as I know). This is also more an Eclipse question, so you should probably look for help in the Eclipse forums.

        The only way I would think remotely possible, to remove menu items, would be to find the JAR file that contains the extensions plugin.xml that contributes the menu, to uncompress said Jar, to hack the XML and remove (for all users) the menu definition, to repack the hacked Jar and to copy it over the original.

        I’d consider that unsafe and would opt against that attempt.

    • I will have a look once I have some time, but I don’t have a lot of experience with REST. You should wait for forum members to answer. There is also an OSLC workshop in the jazz.net/library and some links you could follow in my interesting links section.

      Reply ↓

    • Clement, I am sorry, but it looks like I am not going to be able to help here. I will look into OSLC and REST if I find the opportunity. Currently it does not look like that is going to happen soon.

      Reply ↓

  5. Pingback: How to automatically create and link WI based on RM | ycon blog

  6. Hello Ralph ,
    Is it possible to create trigger (If a state is changed in Work Item / A particular value of attribute changes) of using Java Client API,s

    Reply ↓

  7. Hi Ralph,
    I’ve read your blog but i didn’t find an answer or maybe I didn’t understand,
    Is it possible to create trigger which alert project members every time a baseline is created?
    Thanks.

    Reply ↓

    • The blog explains how to fly and also some example trips and lessons to get started. You want to know how to land on a particular building roof. There is no description for landing on that roof here.

      From the Operation ID’s and extension points, I am pretty sure there is no way to do what you want.

      There might be a remote chance to trigger on delivery of a baseline.

      I am still puzzled, why you guys always want to spam your users e-mail.

      Reply ↓

  8. Hi Ralph

    We are looking to move a work item to a different project area once the work item goes into a particular state. We want the work item to move once the state is changed and the work item is saved. Any pointers on which API should we using for the same ?

    Reply ↓

    • I think this is a bad idea and likely complex with mapping to be done in your move.
      I would search for how the move work item in the Eclipse client works.

      Reply ↓

      • You can try to implement this as a work item save follow up action. In any case you would likely use the Server SDK Java API.

  9. yes..we are looking at save follow up action as the use case. However we are not sure which particular API from server SDK will help us in achieving this.

    Reply ↓

    • IWorkItem workItem = IWorkItemServer.createWorkItem2(IWorkItemType);
      IWorkItemServer.saveWorkItem3(workItem, null, null, additionalParams);

      IWorkItemServer.saveWorkItem2() or IWorkItemServer.saveWorkItems() are available as well

      If you want to do this kind of work, you should follow my getting started link and enable yourself to search the SDK.

      Reply ↓

  10. Hi Ralph,
    We use CLM application for defect track, though CLM sends out the email notification but I wanted to build a reminder tool, stuff like desktop notification for chrome or firefox to remind the resources on their defect count and actions. Can you please let me know how can it be done ?, Also does CLM exposes any API’s so I can get the CLM feeds which I can make use to my reminder.

    Regards,
    Pradeep

    Reply ↓

  11. Im working on a project where a user will enter a work item ID and it will return the URL to the webpage for that work item to allow them to quickly find details for it, however i cant seem to figure out how to find the URL for the work item that it is searching for, any suggestions from anyone would be a great help.

    Reply ↓

  12. Hi Ralph,
    I am working on a project to automate the process of proving a user access to a work area. I am planning to write a Java REST API, to read a list of user IDs, Roles and the Work area name and provide access to those users for that work area. Do you have any sample program to take that as reference and develop the Java code for my project.
    Thanks for your help.

    Thanks,
    Thamizh

    Reply ↓

  14. Hi,
    Is it possible to extend the Timesheet table function? My client wants to be able to edit the Owner field so that a user can log hours for other users.

    Reply ↓

  15. Pingback: IMPORTANT LINKS FOR CLM(for beginners) – Knowledge Sharing Center

  16. Hello,
    One query, we are planning to take databackup from RTC. Like all stories,features, tasks created since 5 years. Along with the attachments, history, comments etc.

    I tried to write a query and extract the info to CSV file but that didn’t give me attachments, history and comments. Is there any API available which we can use.

    Thanks and regards
    Venu

    Reply ↓

Leave a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.