For our first example, I chose something simple and easy, but it will clarify the process in a very objective way. Most steps in this example will be repeated for almost all plugins you will need, in fact the main change is usually at the source code.
In this example, we will develop a plugin that check summary description of a WorkItem and if this description contains the character "#", the plugin will not let this WorkItem to be saved. As I said, a simple example, but changing just one line of code, you can audit what you want in the summary of the WorkItem (eg: Avoid numbers, forcing some specific content)
Let's get started. First let's create a new Plug-in Project
Let's call it "rtc-summary-check-advisor."
We don't need to mark any option (activator, UI contributions, API analysis):
With the project created, select Dependencies tab and add most frequently used plugins as required (com.ibm.team.process.service, com.ibm.team.workitem.common, com.ibm.team. workitem.service, com.ibm.team.process.common, com.ibm.team.repository.common, com.ibm.team.repository.service) and import the package org.eclipse.core.runtime. After that, it is important that you save the project to refresh the workspace.
A pause now for important explanations. Before we continue we need a brief definition about extensions points and their relationship with the RTC. Well, Extension points are, as the name suggests, entry points where the plugins runs on system. In the RTC, these entry points are pre-defined by its API. In my work, the vast majority (95%) of the customizations that I develop uses as entry point the save workitem event. For this event there are basically two types of plugins: Advisors and Participants. Advisors are the preconditions and the Participants are known as follow-up actions. It is important to consider that IBM suggest as good practice (and I follow as a rule) that if a plugin will change the state of a workitem, it must be a participant. Advisors should not change the data, they only validate it.
With this in mind, let's select Extensions tab and add our Extension Point for this plugin. And since this is a pre-condition and will not change the state of the workitem, let's use an Operation Advisor.
Look for: com.ibm.team.proccess.service.operationAdvisors. This option only appears if you have correctly added the required plugins as mentioned earlier.
Fill the following fields:
id: Identifier of the advisor
class: Java class that will be called by the advisor
name: Name by which the advisor will be identified in the process settings.
operationId: Id of the operation where the advisor will be injected.
Now we add an extension service. For this simple example we would not need an extension service, but as in most complex plugins will need to load services from RTC API, I thought I would show you the complete way.
Right click, New -> extensionService
Type an id and use the same class used in the extension point.
Click implementationClass to create the class, it extends AbstractService and implements IOperationAdvisor.
Now we implement the class with the following code:
We will explore more details about programming in future posts, but with the comments and because it is a simple example, you will have no difficulty understanding the logic.
Now we need to create a feature and a site for our plugin. This is very simple.
Create a new Feature Project
Let's call it rtc-check-summary-advisor-feature
Now in Plug-ins tab, let`s add our plugin, as shown in sequence below.
Now let's create a Site Project
To speed up the development we can create the site in the server folder. The recommended folder is server\conf\ccm\sites\YOUR_SITE_FOLDER, in our case \server\conf\ccm\sites\rtc-check-summary-advisor-site.
Similar as we did with the plugin, we will add our feature to created site:
Now we build our site, right click site.xml file, and select PDE Tools -> Build Site
Before starting the server, we must create a provision file for our site to load. This file should be created in the \server\conf\ccm\provision_profiles. Create a text file with the following content and name it rtc-summary-check-advisor-site.ini
After starting the server there is only one thing to do: Enable the advisor.
Open the project area.
Select Process Configuration, go to Team Configuration -> Operation Behavior, look for Work Items -> Save Work Item (server) and click Add to add our Advisor.
All done! Now if you try to save a Work Item typing the "#" character in the summary will receive this message.
That is it, I hope this material help you guys. In coming posts I will bring more examples and will focus more on programming. The level will increase, I will assume that you've got the basics and I will focus in the API.
Source code is available for download
Leave your comments, critics, suggestions. Your feedback is very important to make me improve the material. Despite the fact that I'm relatively "old" in development world, I am entirely new in this area of articles, blogs and video lessons.
Some spelling errors may occur. If you find any misspelled words, let me know.