Implementing IBM RSA and IBM ClearQuest integration: UML to State-Machine with RSA plug-in
Upcoming SlideShare
Loading in...5
×
 

Implementing IBM RSA and IBM ClearQuest integration: UML to State-Machine with RSA plug-in

on

  • 1,133 views

http://rational-tools.info...

http://rational-tools.info
This article demonstrates the process of creating a Rational Software Architect plugin that integrates with ClearQuest. The featured plugin grabs an entity from ClearQuest's database and outputs it as a UML state diagram in RSA. The complete source code for the plugin is included with the article.

Statistics

Views

Total Views
1,133
Views on SlideShare
1,133
Embed Views
0

Actions

Likes
0
Downloads
6
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

Implementing IBM RSA and IBM ClearQuest integration: UML to State-Machine with RSA plug-in Implementing IBM RSA and IBM ClearQuest integration: UML to State-Machine with RSA plug-in Document Transcript

  • Implementing IBM RSA and IBM ClearQuest integration: UML to State-Machine with RSA plug-in Alexey Chernikov, Alexander Novichkov, CM-Consult. CM-Consult, 2010 www.rational-tools.info info@rational-tools.info
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Alexey Chernikov– R&D senior specialist in CM-Consult. Has broad experience working with Java. Primary fields of interest include machine learning, computer vision, software engineering and 3D graphics. Alexander Novichkov – Consultant of software analysis and development methodologies. 14+ years in Software Development, 10 years in Software Configuration Management 9 years in IBM Rational Successful track at CM-Consult technical sales organization More than 30 publications about IBM Rational Process Execution and Improvement • Development Process Management according to RUP, MSF, ISO 12207 Specialties Rich and successful experience in presales and sales and service engagements Pre-sales and post-sales activities on CM portfolio and Enterprise Modernization: Presentation and demo, Proof of concept, Sales engagements, Proposal answers, Marketing events, Training, Coaching, Sales enablement, Business Strategy, Business Development, Business Management, Technical Management, Competitive Analysis, Software Engineering Specialties: Projects management • Concepts, practices and applications of PMI/PMBoK and CMMI • RUP, MSF Agile and others agile methods • Processes and methodologies • IBM Rational ClearCase, ClearQuest, RequisitePro, PurifyPlus, Robot, Subversion • Automation of processes • Integration between CM tools and development IDEs • IT managemen 2
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Table of contents Introduction ............................................................................................................................................ 3 Introduction to RSA ................................................................................................................................. 5 Developing a Rational Software Architect plug-in ...................................................................................... 6 General notions ............................................................................................................................................... 6 Installing a plug-in in RSA .............................................................................................................................. 7 Integrating RSA and ClearQuest ............................................................................................................... 7 ClearQuest JNI................................................................................................................................................ 7 Developing a plug-in to integrate IBM Rational ClearQuest and Rational Software Architect..................... 11 Implementation requirements ........................................................................................................................ 11 Creating and configuring the plug-in ............................................................................................................. 12 Connecting the plug-in to ClearQuest ............................................................................................................ 16 Getting the list of ClearQuest databases ........................................................................................................ 17 Getting the list of schemas located in a ClearQuest database ......................................................................... 17 Getting the list of entities in a ClearQuest database ....................................................................................... 18 Getting the list of states and transitions for a ClearQuest entity ..................................................................... 19 Visualizing a state machine in UML.............................................................................................................. 19 Putting it all together ..................................................................................................................................... 20 Conclusion ............................................................................................................................................. 33 Resources .............................................................................................................................................. 33 Introduction Years of experience with IBM’s change management tool – IBM Rational ClearQuest – have brought to light both its good and bad sides. While there is no doubt in the flexibility of the mechanism for creating and editing change management schemas (creating forms, programming states and transitions for change requests), one can notice a drawback in the process of programming the state transition matrix when defining the lifecycle of a change request. In a simple scenario, a CM Manager first develops the structure of a Change Request and describes its lifecycle in a UML diagram (this is the abstract, descriptive level, see Picture 1). After a cycle of approval, the diagram is sent to a transition matrix programmer (perhaps the Change Management Administrator), who creates a low-level implementation of the process in IBM Rational ClearQuest, based on the UML diagram. This is an ideal scenario, which isn’t as common in practice as it should be. The Change Request lifecycle is often programmed directly into IBM Rational ClearQuest, and the UML model is never created. 3
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 1. The “Defect” change request’s lifecycle as a UML diagram As a rule, the processes used in an organization don’t remain frozen – they evolve with time. As a process evolves, the schema of a process (in ClearQuest), and its UML model must both be changed. Both operations are manual. So a CM administrator would have to commit the changes to the model first, then to the ClearQuest schema (or vice versa). Both operations are prone to human error: an important transition could be missed either in the schema, or in the diagram. Unfortunately, this happens all the time in practice. The disparity between the schema and model of a documented process can be as high as 30%. Often a process continues to evolve, but its description gets left behind, and the changes go undocumented. 4
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 2. The state transition matrix in IBM Rational ClearQuest. The sequence of transitions between different states in a change request is defined here. This matrix is a physical, low-level depiction of the process. The screenshot shows the transition matrix for the “Defect” change request. The solution to this problem lies on the surface: connect a UML modeling tool, like IBM Rational Software Architect, to ClearQuest, and import a Change Request lifecycle into that tool, then output the state transition matrix as a UML diagram. Such a solution would make the current state of a process readily available as a UML diagram, without the potential for translation errors. This article describes in detail how to create an RSA plug-in that will perform the outlined actions. The next logical step in making such a plug-in is providing the opportunity to export a UML diagram describing the lifecycle of a process to a ClearQuest schema, allowing for a fully automated creation process, but that is a topic of a separate article. Inset: A process can be represented as: A UML diagram (the abstract representation); A state transition matrix (the physical representation). Introduction to RSA Rational Software Architect is a modern integrated development environment based on Eclipse. Eclipse in turn is an expandable IDE; in fact, its broad capability for expansion is what makes it stand out from most other modern development environments. Eclipse is a Rich Client Platform, which means it has a micro kernel that 5
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ controls the lifecycle of the application and a host of auxiliary services, which can be accessed when integrating with the environment. RSA can be thought of as an expanded version of Eclipse, featuring additional development tools, which retains Eclipse’s ability for further expansion. Developing a Rational Software Architect plug-in The prime instrument for enhancing RSA’s functionality is the plug-in. Plug-ins can have any functionality attached to them – anything that can be written in Java can work inside an Eclipse plug-in. Plug-ins can often be very heavyweight applications, and since the environment consists of a large number of plug- ins, which must all be initialized, it usually takes a long time to launch. For this reason it can be difficult to debug plug-ins in the development environment (especially considering that it can take a long time just to update a plug-in to the latest version – RSA 7.0.0 searches all known update sites for plug-ins, and there’s no mechanism to update only a single plug- in). So for testing needs, a special Runtime Workbench is used. The Runtime Workbench has all the services required for RSA to work properly, but usually only contains a small subset of the plug-ins used in the normal workbench (the exact configuration of plug-ins used in the Runtime Workbench can be found in Window Preferences Plug-in development Target platform). However, even with the simplifications of the Runtime Workbench, RSA’s initialization can still take a rather long time. For more effective testing and debugging, a simpler type of application can be used, which, like the plug-in, has access to RSA’s inner services – the Pluglet. It can be launched directly from a working RSA instance, without the need for a Runtime Workbench. Pluglets are a feature available only in RSA, not in Eclipse. Unfortunately, Pluglets are not fit for some tasks. In Rational Software Architect 7.0.0, a Pluglet containing native calls can’t be launched more than once without restarting the environment, which beats the point of using them (it’s faster to launch a Runtime Workbench than to restart the environment). This problem arises because a native library can only be loaded in one Java class loader at a time, and on second launch the Pluglet thinks the library it needs is already loaded in another class loader, but it has no access to the loaded library. In this article we’ll emphasize using native libraries to interact with ClearQuest, so we won’t look into Pluglets any further. General notions 6
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Plug-ins can extend the user interface, perform background tasks or provide services to other plug-ins. The specific way a plug-in is connected to the environment can be configured when creating the plug-in. A plug-in can be built into almost any place in RSA’s user interface: different context menus, the Menu Bar, a custom View (that can be created specifically for the plug-in). The conditions under which the plug-in becomes accessible can also be configured – for example, a context menu plug-in might appear only when the context menu is called on files of a certain type. In this article we’ll plug into the Menu Bar, creating our own menu group. Installing a plug-in in RSA Like Eclipse, RSA has a unified system for installing plug-ins. Plug-ins are bundled together to form a Feature, and features can be installed directly into RSA from an Update Site. Update Sites can be accessed from RSA from Help Software Updates Find and install… We’ll look into the problem of installing plug-ins in more detail after we’ve created our own plug-in that integrates with ClearQuest. Integrating RSA and ClearQuest There are at least two possible ways to integrate RSA and ClearQuest: 1. By using ClearQuest’s COM interface. 2. By using a library of native functions through which ClearQuest itself functions. In this article we’ll examine only the latter. One of ClearQuest’s clients is based on Eclipse, and it makes sense to reuse the work already done on integrating ClearQuest and Eclipse. ClearQuest JNI Before we begin building our plug-in, we’ll need to get a hold of the library that will allow us to call ClearQuest’s native functions from Java, through the Java Native Interface. This library is installed along with ClearQuest. It’s contained in a compiled Java archive - cqjni.jar, which can be found in ClearQuest’s root directory (in Windows this directory defaults to C:Program FilesRationalClearQuest). 7
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ One way to quickly access the classes in that jar is to add the archive to a project’s build path, and specify the path to the natives (which is the same folder cqjni.jar is in). For normal applications this method works fine; however, when using it for plug-ins, there can be problems with testing (specifically, it’s rather hard to get the native calls to work reliably in the Runtime Workbench), so we’ll be using a different method in this article – we’ll decompile cqjni.jar, and add the decompiled .java files to our project. Though the process is described below, please note that the source code for this article contains the decompiled classes, so you can skip this section if you wish. There’s a variety of decent java decompilers available on the internet. We’ll be using jad – a console-based decompiler which is free for non-commercial use. Most of the other free decompilers (especially ones with only a graphical interface and no console counterpart) can’t decompile several files at once, which is a major drawback in our case, because CQJNI consists of a large number of classes. Jad can be downloaded from http://www.varaneckas.com/jad. After downloading and extracting it from the archive, it should be added to PATH (or you’ll have to make sure it’s accessible when working with it further). Next, you’ll need to extract all the .class files from the aforementioned cqjni.jar (any archive program that can extract .zip files can extract them from a .jar). From the folder with the extracted .class files, launch the following command in the console to decompile: jad -d CQJNI -s .java *.class As a result, the decompiled .java files will be in the CQJNI folder. There will be a few compile-time errors in the files, which we will fix manually after we add them to Eclipse. Let’s start out by creating a project which we will use to fix the classes and then verify that they work. Go to File New Other, Java Project, and call the project CQJNITest. Next, let’s import the decompiled classes into the project. From the context menu of the project, select Import, then File System (Picture 3). 8
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 3. Importing resources from the files system to RSA. In the window that appears, select “Browse…”, then find the folder with the decompiled CQJNI classes, and mark it in the import dialogue window. Change the “Into folder” field to “CQJNITest/com/rational/clearquest/cqjni” (Picture 4). 9
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 4. Configuring import parameters for the CQJNI classes Now, click “Finish”, and our project should have a package called “com.rational.clearquest.cqjni” added to it, which should contain the decompiled classes. Now, let’s fix them up so they don’t have any compile errors. There should be two classes with errors: CPUCount and CQJNIBaseObj. In CPUCount, in the only static method, remove everything after “return”, and also add throws ClassNotFoundException to the method declaration. In CQJNIBaseObj the procedureHashCode method can be rewritten in the following manner, for example: public static int procureHashCode() { synchronized(m_classLock) { _hashCode++; 10
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ return _hashCode; } } There’s another method with errors in CQJNIBaseObj - _mthclass$. It’s exactly the same as the method we fixed in CPUCount, so just make the same modifications made to CPUCount, and we’re done. Now let’s create a simple test to verify that everything is working correctly: import com.rational.clearquest.cqjni.CQAdminSession; import com.rational.clearquest.cqjni.CQClearQuest; public class Test{ public static void main(String[] args) throws Exception{ CQClearQuest cq = new CQClearQuest(); CQAdminSession as = cq.CreateAdminSession(); System.out.println(as); } } Developing a plug-in to integrate IBM Rational ClearQuest and Rational Software Architect Now we can begin to build a plug-in for RSA which will communicate with ClearQuest and perform the functions described in the introductory section. Implementation requirements The plug-in we develop must be able to: 11
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ 1) Open an IBM Rational ClearQuest session 2) Import an entity’s state transition matrix 3) Visualize the state transition matrix as a UML diagram Creating and configuring the plug-in First, let’s create our plug-in. Go to File New Other, and then select “Plug-in Project” (Picture 5). Picture 5. The dialogue for creating a new project; select “Plug-in Project”. When we select a name for the project - “RSACQIntegration”, for example, - a window with different template proposals for our plug-in will appear. A “Hello World” plug-in will automatically create a menu group called “Sample Menu” for us, which will have an item labeled “Sample Action”, which reacts to clicks by opening a dialogue window. The plug-in we’re making must also extend the menu bar, so choose the “Hello World” plug-in - it will be a good base for us (Picture 6). 12
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 6. The window with plug-in templates; we’re going to use a template that extends the Menu Bar. All the other configurations aren’t of particular interest to us right now, so from here you can simply click “Finish”. All the information about how the plug-in will embed itself into the environment is located in plugin.xml. Opening this file from RSA will take us to the Overview page of the plug-in (Picture 7). 13
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 7. General information about the plug-in, which is contained in the Overview tab of plugin.xml 14
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ If you go to the Extensions tab, you can see an overview of the plug-ins extension points, and the actions assigned to them (Picture 8). Picture 8. The Extensions tab of plugin.xml. Displays extension points of the plug-in, and the actions performed when interacting with a certain extension point. From this tab you can change the interface parameters – icons, labels, etc. Everything that can be changed from the graphic representation of the plugin.xml file that RSA shows can also be modified directly in xml, the syntax specification can be found in Eclipse’s official reference [3]. – plugin.xml extensions – . Sample Menu id RSACQIntegrationMenu, label – RSA-CQ Integration Menu; sampleGroup RSACQIntegrationGroup. 15
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Let’s change some basic parameters to personalize our plug-in. For Sample Menu, set the id to “RSACQIntegrationMenu”, and the label to “RSA-CQ Integration Menu”, and finally change sampleGroup to “RSACQIntegrationGroup”. Also, let’s make the following changes to Sample Action: Set the menubarPath field to “RSACQIntegrationMenu/RSACQIntegrationGroup”, the toolbarPath field to “RSACQIntegrationMenu”, the label field to “Import CQ States”, and finally let’s enter a Tooltip: “Imports a ClearQuest state transition matrix”. To verify that we’ve set everything up correctly, let’s launch a Runtime Workbench with our plug-in by pressing F11 (if plugin.xml is opened in the Plug-in Development perspective, RSA will automatically decide to launch a Runtime Workbench with the opened plug-in. Otherwise, you’ll probably need to set up a Run Configuration for an Eclipse Application). Picture 9. A custom plug-in embedded into RSA’s Menu Bar as a separate menu group with a single menu item. In the RSA instance that appears, there should be a menu group called “RSA-CQ Integration Menu” that was added because of our plug-in being embedded into the Runtime Workbench, and it should contain a single menu item – “Import CQ States”. If you click that menu item, a dialogue window saying “Hello, Eclipse world” will appear, because that was the default behavior automatically assigned when we created the project, which we haven’t changed yet. Our next step will be to configure our plug-in so that the “Import CQ States” button does what we need it to. Connecting the plug-in to ClearQuest 16
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Close the Runtime Workbench, we won’t need it anymore for now. In the main project, open SampleAction.java. It’s run() method contains the code responsible for opening the test window we saw earlier. You can delete run()’s contents, we’ll be writing the code that connects to ClearQuest here. To start off, let’s add the decompiled CQJNI classes to our plug-in project. You can simply copy the entire package from the test project we created earlier. Our goal is to get the states and transitions for an entity, and visualize them in UML. To do this, we’ll need to: 1) Get the list of ClearQuest databases, choose one 2) Get the list of entities in the selected database, pick an entity 3) Get the list of states and transitions for the selected entity 4) Output the states and transitions as a UML diagram To accomplish this, we’ll need to create methods that provide the appropriate functionality. The source code that comes with the article covers all that functionality, so we’ll only look at the main problems without going into too much detail. Getting the list of ClearQuest databases First we need to get the list of ClearQuest databases. In Windows, ClearQuest keeps that information in the registry. The exact location depends on ClearQuests version, which can also be retrieved from the registry. In this article we’ll assume that the 7th version of ClearQuest is being used (the code that comes with the article shows how to work with the 6th version as well). To find out the version, the following console command can be executed: reg query "HKEY_CURRENT_USERSoftwareRational SoftwareClearQuest" If the 7th version is installed, the answer will contain the following line: HKEY_CURRENT_USERSoftwareRational SoftwareClearQuest7.0.0 If we know the version, we can find out the list of databases by executing the following command: reg query "HKEY_CURRENT_USERSoftwareRational SoftwareClearQuest7.0.0CoreDatabases" A list of folders will be returned, and the database names will be right after “Databses” in the list. Getting the list of schemas located in a ClearQuest database 17
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ After selecting a database from the list, we can get the list of schemas in that database using CQJNI. We’ve already tried to perform some simple interactions with ClearQuest, and the beginning in this case will be the same as last time: CQClearQuest cq = new CQClearQuest();/* Create the application to communicate with */ CQAdminSession as = cq.CreateAdminSession();/* To get the list of schemas, we’ll need admin access*/ as.Logon(login, password, dbset);/* dbset is one of the databases from the previous step; login and password should be the ones used to enter ClearQuest Designer. The order of parameters in the various ClearQuest API calls can be found in the ClearQuest API reference [1] (the CQJNI calls from the decompiled classes won’t have sensible names unless you modify them yourself) */ CQSchemas ss = as.GetSchemas();/* This call returns a list of schemas that can be iterated*/ List<String> = new ArrayList<String>(); /* Store schema names in this list */ /* Get the names by element: */ for (int i = 0; i < ss.Count(); i++) { CQSchema s = ss.Item(i); schemas.add(s.GetName()); } Getting the list of entities in a ClearQuest database Getting the list of entities is similar to getting the list of schemas. The main difference is that now we have to use a normal session with ClearQuest, not an admin session, so the login/password should be the ones used to enter the ClearQuest client. Also, in this case databaseName is the user database. CQClearQuest cq = new CQClearQuest(); CQSession session = cq.CreateUserSession(); 18
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ session.UserLogon(login, password, databaseName, dbSet);/* The login/password to access the ClearQuest client, not the admin user/password that was used to get the list of schemas */ String[] entities = session.GetEntityDefNames(); Getting the list of states and transitions for a ClearQuest entity Once we have the list of entity names, we can get an Entity from CQ, and then we can get its list of states and transitions: CQEntityDef entity = session.GetEntityDef(entityName); String[] actions = entity.GetActionDefNames(); String[] states = entity.GetStateDefNames(); Visualizing a state machine in UML Now we need to visualize the entity’s imported state machine. We’ll be using RSA’s UML State Machine for this purpose. The source code provided with the article contains a class that creates a State Machine diagram, so just like with CQJNI, we’ll only look into the main problems here. To work with UML in RSA, we’ll first need to define the diagram’s structure, and then map that structure to a visual diagram. For our purposes, we’ll need to make a Use Case, then create a State Machine for that Use Case, then create a Region for that State Machine, and then add states and transitions to that Region. When creating a diagram for a State Machine, all the states and transitions added to the Region will be added to the diagram automatically (for most other diagram types, you’d need to explicitly map created UML elements to their diagram with a separate call). It’s best to ensure name uniqueness: otherwise, the editor will give out a warning. In the source code supplied with the article, when attempting to create a state or transition with a non-unique name, instead of creating that state/transition, the existing state/transition is returned. 19
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ To be able to create anything, we’ll need a UML Model object. The model can be selected from the list of opened models, for example, which you can get by calling UMLModeler.getOpenedModels(). The model can also be opened by name, or you can simply create a new model: model = UMLModeler.openModel(name); model = UMLModeler.createModel(name); Having a model object, you can create a Use Case in that model: UseCase uc = (UseCase) model.createPackagedElement(name, UMLPackage.eINSTANCE.getUseCase()); Note the UMLPackage.eINSTANCE.getUseCase()call – the UML element type being created is specified in this manner. UMLPackage.eINSTANCE contains methods to create most UML elements. All the other elements we outlined are created similarly. You can look at the exact procedures for creating them in the source code supplied with the article. To create a diagram for the created UseCase, RSA’s UMLDiagramHelper utility class can be used Diagram d = UMLModeler.getUMLDiagramHelper().createDiagram(model, UMLDiagramKind.USECASE_LITERAL); UMLModeler.getUMLDiagramHelper().createNode(d, uc); The final call visualizes the UseCase on the diagram. Putting it all together The article is supplied with source code that implements all the functionality discussed here. The ClearQuestIntegration class implements some convenience methods for accessing ClearQuest. CQUMLStateVisualizer can 20
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ visualize an entity’s state transition matrix as a UML diagram. Note that CQUMLStateVisualizer will only be able to create UML diagrams from a plug-in (or from a pluglet, but only once, as mentioned earlier). To finish creating our plug-in, we need to return to the run() method inside SampleAction. Using the classes from the code supplied with the article, the method should look something like this: try { int version = ClearQuestIntegration.getVersion(); /* First get the version of the installed ClearQuest instance */ List<String> databases = ClearQuestIntegration.getRepositories(version); /*Next get the list of ClearQuest database names*/ new CQUMLStateVisualizer(new CQClearQuest(), "admin", "", "SAMPL", databases.get(0), "Defect");/* To visualize an entity’s state transition matrix in UML (“Defect” in this case – the entity’s name is passed as the last parameter), we’ll need a login (2nd parameter) and password (3rd parameter) to access ClearQuest and receive the transition matrix. We’ll also need the name of the user database (4th parameter) and the name of a ClearQuest repository (5th parameter)*/ } catch (Exception e) { /* If the plug-in can’t work for some reason, print the reason, but otherwise do nothing. */ e.printStackTrace(); } After filling in the plug-ins run() method, we still need to package it so it can be effectively deployed. As mentioned earlier, we’ll need to create a Feature and an Update Site for this purpose. First, let’s create a Feature. Go to File New Other, and select “Feature Project” (Picture 10). 21
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 10. Creating a Feature Project. Click “Next”, enter a name for the Feature project (“RSACQImport”, for example), and click “Next” again. In the menu that appears, you’ll be prompted to choose which plug-ins will be a part of this Feature. In our case there should be only one plug-in: RSACQIntegration (Picture 11). 22
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 11. Selecting which plug-ins will be part of a feature. Our feature should contain the RSACQIntegration plug-in, which we created earlier. After you’ve marked it, press “Finish”. Next we’ll need an Update Site, which will allow us to install the Feature into RSA. To create an Update site, go to File New Other, then select “Update Site Project” (Picture 12). 23
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 12. Creating an Update Site Project. The only configurable parameter an Update Site has during creation is its name; let’s call it “RSACQImportSite”. After creating the project, a panel with the Update Site’s properties should be open. The properties are kept in site.xml, and are displayed in RSA in a structured way that makes them easier to modify. To be able to install our plug-in through this Update Site, we need to add the Feature with the plug-in to the Update Site. From the properties panel, select Add Feature (Picture 13). 24
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 13. The Site Map tab of an Update Site. Features can be submitted to an Update Site from this tab, and all the features in the Update Site are listed here. In the window that appears, select the Feature we created earlier (Picture 14). 25
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 14. Selecting features for an Update Site. We need to add the feature we created earlier, to make it accessible through this Update Site. Finally, select Build All. Now the Update Site is ready, and we can install our plug-in from it. To install the plug-in, go to Help Software Updates Find and Install, then select Search for new features to install, and click “Next” (Picture 15). 26
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 15. The main window for expanding RSA’s plug-in configuration. From this window, you can choose to install new plug-ins, or update the ones already installed. In the window that appears, select “New Local Site” (since the Update Site we created is currently kept on the local files system), then find the folder containing the Update Site with our plug-in (Picture 16). You can look up the location of the Update Site by selecting “Properties” from the context menu of the Update Site’s project (you can copy it from there). 27
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 16. Adding a local Update Site to the list of Update Sites from which RSA can install and update plug-ins. After you’ve selected the Update Site’s folder, click OK. The Update Site will be added to the list; mark it (also make sure the other Update Sites are not marked, we don’t need to install any other plug-ins right now), and click “Finish”. A window will appear prompting you to select which plug-ins from the Update Site you wish to install. Right now there should be only one plug-in, which should be selected (Picture 17). 28
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 17. This window allows you to select which Features are to be installed from an Update Site. We need to install the Feature we created earlier, which contains our ClearQuest integration plug-in. When you click “Next”, you’ll be taken to another window, which contains the license descriptions for the features being installed. We haven’t filled out any license for our Feature, so the description will be empty (Picture 18). 29
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 18. The license agreement window for installing features. We haven’t assigned any license to our Feature, so the license description is empty. Choose to accept the terms of the license agreement, click “Next”, and a window that allows you to choose the install destination for features will appear (Picture 19). You don’t have to change it, so you can click “Finish” right away. 30
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 19. The plug-in install location configuration window. Since we haven’t signed our feature, a warning window will appear. You can ignore it, and click “Install All” (Picture 20). 31
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 20. A window with a warning about installing an unsigned feature. After the installation process is complete, RSA will need to be restarted for the changed to take effect. After restarting, there should be a new entry in the Menu Bar – the one with our plug-in. The code provided with the article imports the “Defect” entity from the SAMPL database (i.e. there’s no interface to select another entity). Clicking on the menu item added by the plug-in creates a UML diagram that represents the entity’s lifecycle, and opens a tab in RSA that shows the diagram (Picture 21). 32
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Picture 21. ClearQuest’s “Defect” entity’s state transition matrix visualized as a UML diagram in RSA. Conclusion Practice shows that an automated method for creating diagrams of change management processes helps eliminate translation errors. It’s especially important that automation saves a significant amount of time for specialists. In conclusion, we’ll reiterate that the next logical step for such a system is creating a duplex module that supports importing and exporting entities. This way, a state transition matrix programmer’s manual labor is shifted onto the automated system, and the specialist can focus only on the process diagram. Resources [1] http://publib.boulder.ibm.com/infocenter/cqhelp/v7r0m0/index.jsp?topic=/com.ibm.rational.clearquest.apiref.doc/defa ult_topic.htm [2] http://www.ibm.com/developerworks/rational/library/08/0826_makady/index.html [3] http://help.eclipse.org/stable/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/misc/plugin_manifest.html 33
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ [4] http://www.varaneckas.com/jad 34
  • CM-Consult Company and Rational Tools project www.rational-tools.info https://twitter.com/rrationaltools __________________________________________ Alexey Chernikov– R&D senior specialist in CM-Consult. Has broad experience working with Java. Primary fields of interest include machine learning, computer vision, software engineering and 3D graphics. Alexander Novichkov – Consultant of software analysis and development methodologies. 14+ years in Software Development, 10 years in Software Configuration Management 9 years in IBM Rational Successful track at CM-Consult technical sales organization More than 30 publications about IBM Rational Process Execution and Improvement • Development Process Management according to RUP, MSF, ISO 12207 Specialties Rich and successful experience in presales and sales and service engagements Pre-sales and post-sales activities on CM portfolio and Enterprise Modernization: Presentation and demo, Proof of concept, Sales engagements, Proposal answers, Marketing events, Training, Coaching, Sales enablement, Business Strategy, Business Development, Business Management, Technical Management, Competitive Analysis, Software Engineering Specialties: Projects management • Concepts, practices and applications of PMI/PMBoK and CMMI • RUP, MSF Agile and others agile methods • Processes and methodologies • IBM Rational ClearCase, ClearQuest, RequisitePro, PurifyPlus, Robot, Subversion • Automation of processes • Integration between CM tools and development IDEs • IT managemen 35