UML2ClearQuest. UserGuide. Ver 3.0

Contents

1. List of Abbreviations and Terms

2. Glossary 

3. Introduction 

3.1 Purpose of This Document

3.2 Field of Application

3.3 Implementation

3.4 System Requirements

4. General Description 

5. Functionality 

6. Description of User Interface Forms 

6.1 Application main window

6.1.1 Main menu

6.1.2 Into ClearQuest tab

6.1.3 From ClearQuest tab

6.1.4 Documenting tab

7.1 Restrictions imposed on Visio and StarUML diagrams

7.2 Export into ClearQuest

7.3 Export from ClearQuest

7.4 Creating a document

7.5 Filling in the document template

7.5.1 Tags for specifying information about the schema

7.5.2 Tags for specifying information about record types

8. License policy 

9. Known issues and troubleshooting 

List of Abbreviations and Terms

Glossary

Introduction

Purpose of This Document

• UML2ClearQuest functionality
• User interface forms
• Module settings
• Using the module

Field of Application

Implementation

System Requirements

• ClearQuest version 2003.06.00 or later
• MS Visio (v. 2003/2007) or StarUml 5.0
• Framework .Net 2.0.

General Description

1. Designing the life cycle for ClearQuest record types. ClearQuest does not provide a tool for visual modelling of life cycles of its record types. UML2ClearQuest in turn allows importing the life cycle diagrams built by MS Visio or StarUML, i.e. it allows performing visual modelling of record type behaviour within MS Visio or StarUML and easily applying the modelling results to any ClearQuest record type.
2. Maintaining the life cycle for ClearQuest record types. When working with ClearQuest schemas it is often necessary to modify previously developed behavioural models of a record type, and UML2ClearQuest allows simplifying this process. UML2ClearQuest allows exporting the existing behavioural model from ClearQuest into MS Visio 2003 or StarUML file, modifying this model using the corresponding tool and importing results into the existing ClearQuest schema. It allows modifying state diagrams for every ClearQuest record type without using ClearQuest Designer and making these changes on basis of the same MS Visio or StarUML file.
3. Documenting the ClearQuest schema. UML2ClearQuest allows generating documentation for ClearQuest schema of any version and allows building a document both on basis of internal template and using custom templates. It simplifies modifying documentation after modifying the ClearQuest schema. Besides, UML2ClearQuest allows adding help text for fields of ClearQuest records of any type on basis of an existing document, which is more convenient than using ClearQuest Designer.

Functionality

1. Importing UML diagrams from MS Visio and StarUML and building on their basis behavioural models for ClearQuest record types. The diagrams can be imported in the following modes:
   1. Importing with creating a new record type. When this mode is used, an "empty" record type is created that will contain the defined behavioural model.
   2. Importing with deleting a state diagram. All existing states and activities are cleared and the state diagram is built over again on basis of the imported UML model.
   3. Importing with modifying state diagram. The UML2ClearQuest application determines the differences between the imported and existing behavioural models and modifies the existing model on basis of these differences.
2. When updating the existing state diagram for a record type the IBM Rational ClearQuest application determines the difference between the existing and the new behavioural models and updates the existing diagram on basis if these differences. The following file formats are supported:
   1. MS Visio XML Drawing (*.vdx)
   2. MS Visio XML Stencil (*.vsx)
   3. MS Visio XML Template (*.vtx)
   4. StarUML Project File (*.uml)
3. Exporting a state diagram for a ClearQuest record type into MS Visio or StarUML files. UML2ClearQuest allows building a UML diagram in MS Visio and StarUML formats for a ClearQuest record type. Later this diagram can be used as a source for subsequent changes of the state diagram.

Description of User Interface Forms

Application main window

After the launch of UML2ClearQuest the application main window appears (see Figure 1. Main window), which provides access to all functions of the application.

Figure 1. Main window

Main menu

The figure below (see Figure 2. Application main menu) represents the application main menu.

Figure 2. Application main menu

The File menu option (see Figure 3. The File menu option) duplicates the main buttons of the application interface, such as Open schema and Refresh the schema list.

Figure 3. The File menu option

The Settings menu option (see Figure 4. The Settings menu option) allows a user to select the interface language and set the parameters of the application. Under Parameters option, a user can set the waiting time for getting the list of available record types. At the end of the waiting time the application will stop the process of getting the list.

Figure 4. The Settings menu option

The Help menu option (see Figure 5. The Help menu option) allows viewing information about the version of the application and is used for installing the license.

Figure 5. The Help menu option

Into ClearQuest tab

The Into ClearQuest tab is used for importing the state diagram into the record type. The tab is represented in the figure below (see Figure 6. Tab used for import into ClearQuest).

Figure 6. Tab used for import into ClearQuest

• The Fill in button - allows selecting a file with diagrams. The file format is set in the filter field of the standard Open file dialog.
• It converts the opened file and forms the list of diagrams found.
• The Diagrams list - contains the list of available diagrams. When the diagram is selected, it is displayed in the right part of the window.
• The Check button - upon the button click the diagram is examined for compliance with requirements. The examination result is displayed in the Result field, and if the requirements are violated the message appears where the violated requirements are listed.
• The Result field - displays information about compliance of the diagram with the requirements. When the requirements are fulfilled, in the field, the following text is displayed in green colour: Check is complete successfully. If any incompliance with the requirements is detected, in the field the following text is displayed in red colour: Check is complete unsuccessfully.
• The Record type name field stores the name of the record type that will be created or modified in the ClearQuest schema.
• The Record type DB name field stores the name of the table that will be created in the ClearQuest data base for storing information. This field becomes active only if a new record type is created. If the existing record type is modified, the field is not used.
• The Modify the existing one option - if this option is selected, it means that the existing record type in the schema should be modified.
• The Replace the existing one option - if this option is selected, it means that the existing record type is deleted and the new one is created instead of it.
• The Create new option - if this option is selected, it means that the new record type is created in the schema.
• The Add the "Modify" action check box - if this check box is selected, the action with the specified name that allows modifying records is added to the action list.
• The Add the "Delete" action check box - if this check box is selected, the action with the specified name that allows deleting records is added to the action list;
• The Into File option - if the option is selected, export should be performed into file.
• The In existing scheme option - if this option is selected, the record type will be imported into the existing ClearQuest schema; If this method is selected, the list of schemes becomes active where you can select a schema into which the record type should be exported.
• The Refresh button - requests the connection name, user name and password for connecting to ClearQuest and getting the list of available schemas for the specified connection.
• The Schemas in list - contains the list of available schemas in the specified connection. The export will be performed into the schema selected from this list.
• The Perform button - upon the button click, the import of states and transitions of the selected diagram is performed with parameters specified. If import to file was selected, it is necessary to specify the name and location of the target file. If import to the existing schema was selected, the program will import the record type into ClearQuest and display the result on the screen.

From ClearQuest tab

The From ClearQuest tab (see Figure 13. Tab used for export from ClearQuest) is used for exporting from the state diagram for the record type from ClearQuest.

Figure 13. Tab used for export from ClearQuest

• The Refresh button - requests the connection name, user name and password for connecting to ClearQuest and getting the list of available schemas for the specified connection.
• The Record type name field stores the list of record types available in the selected ClearQuest schema.
• The Export button - upon the button click, the selected record type is exported into the Visio or StarUML file.

Documenting tab

Figure 7 - Documenting tab

• The Refresh button - requests the connection name, user name and password (see Figure 8) for connecting to ClearQuest and getting the list of schemas available for the specified connection.
• The Schemas in list - contains the list of available schemas in the specified connection.
• The Version number list - contains the list of versions of the selected schema. Documenting can be performed for any version of the schema.
• The Data on record types check box - if this check box is selected, documenting the information about record types of the schema is activated. The Section title field - in this field, you can specify the name of the section where the information about record types will be placed. The list below contains record types. From this list, you can select the record types, information on which should be saved.
• The Data on stateless record types check box - if this check box is selected, documenting the information about schema entities is activated. The Section title field - in this field, you can specify the name of the section where the information about entities will be placed. The list below contains entities. From this list, you can select the entities, information on which should be saved.
• The Data on the schemas check box - if this check box is selected, documenting the information about the schema is activated. The Section title field - in this field, you can specify the name of the section where the information about the schema will be placed.
• The General data check box - if this check box is selected, documenting general information about the schema is activated. The text field allows specifying the name of the section where general information about the schema will be placed.
• The Data on relations check box under Data on the schemas - if this check box is selected, documenting the information about relations between record types of the schema is activated. The information about relations is represented as a directional diagram. The text field allows specifying the name of the section where the information about relations will be placed.
• The Data on relations check box under General parameters - if this check box is selected, documenting the information about relations of the record type with another record types is activated. The information about relations is represented as a directional diagram. The text field allows specifying the name of the section where the information about relations will be placed.
• The Complete view option - if this option is selected, the fields of parent records will be displayed on the relationship diagram representing relations of record types with other record types and their fields.
• The Simple view option - if this option is selected, the fields of parent records will not be displayed on the relationship diagram representing relations of record types with other record types and their fields.
• The State diagram check box - if this check box is selected, documenting states of the record type and transitions between these states as a directional diagram is activated. The text field allows specifying the name of the section where the diagram will be placed.
• The Transition matrix check box - if this check box is selected, documenting states of the record type and transitions between these states as a table is activated. The text field allows specifying the name of the section where the table will be placed.
• The Description on actions check box - if this check box is selected, documenting the list of available actions as a table is activated. The text field allows specifying the name of the section where the table will be placed. The structure of table columns is defined by the check boxes Include the help text, Include the access control, Include the initialization, Include the validation, Include the commit, Include the notification that include into the document's table the columns Description, Access control, Initialization, Validation, Commit and Notification correspondingly.
• The Field description check box - if this check box is selected, documenting the list of fields as a table is activated. The text field allows specifying the name of the section where the table will be placed. The structure of table columns is defined by the check boxes Include the type, Include the size, Include the help text, Include the default value, Include the permissions, Include the change of value, Include the validation, Include the choice list that include the columns Type, Size, Description, Default value, Permissions, Change value, Validation and Choice list correspondingly.
• The Add system fields check box - if this check box is selected, the system fields are included into the list of the record type fields.
• The Include the service data check box - if this check box is selected, the service information about the name and version of the schema is included into the document, and tags are added to the Description column of the table of the fields list for updating the help description for fields of record types in the schema.
• The Description of the field behaviour check box - if this check box is selected, the description of behaviour of record fields as a table is added to the document. The text field allows specifying the name of the section where the table will be placed.
• The Create document button - upon the button click, documenting of the schema is performed into the file specified by a user on basis of the set parameters.
• The Fill in the template button - upon the button click, the existing document is filled in, and the information is added into the places marked by the special tags.
• The Update button under Updating in the field description - upon the button click, the help description for record fields of the selected schema is updated, the update is performed on basis of the existing document with the check box Include the service data selected.

Working with the application

Restrictions imposed on Visio and StarUML diagrams

1. Only objects of the UML Activity section are supported:

• Supported objects for Visio: Initial State, Final State, State, Action State and Control Flow.
• Supported objects for StarUML: InitialState, FinalState, ActionState, SubactivityState and Transition.

1. The transition from Initial State or InitialState is mandatory, and there should be only one such transition.
2. There should be at least one transition into Final State or FinalState.
3. All transitions except transitions into Final State or FinalState must have names.
4. Every state (State, Action State, ActionState, SubactivityState) must have at least one incoming transition and one outgoing transition.
5. States should not have transitions into themselves.
6. Transitions with the same names must have the same final state.
7. All transitions should be linked to states.
8. There should be only one transition between the same states.
9. In Visio diagrams, it is necessary to name transitions as Action. If several names are given, the application will take only the first one as the name.
10. In names, only Russian and Latin characters, underscore character "_" and numerals are allowed.
11. The name length should not exceed 25 characters.
12. There should be no states with the same names.

The following figures represent the examples of UML diagrams in Visio (see Figure 14 - UML diagram in Visio) and StarUML (see Figure 15 - UML diagram in StarUML).

Figure 14 - UML diagram in Visio

Figure 15 - UML diagram in StarUML

Export into ClearQuest

1. To form the list of available diagrams, press the Fill in button and select the file that contains the UML diagram. If there are several diagrams, you can select the necessary one from the Diagrams list (see Figure 16. UML diagram opened in the application)

Figure 16. UML diagram opened in the application

1. The next step is to examine the diagram for compliance with the ClearQuest requirements. To examine the diagram, click the Check button. If the diagram complies with all requirements, the text Check is completed successfully in green will be displayed (see Figure 17. Diagram check result)

Figure 17. Diagram check result

1. Then you need to connect to ClearQuest. To establish connection, click the Refresh button. In the opened dialog (see Figure 18. Establishing connection to ClearQuest) specify the name of the connection where the necessary schema is located, login and password.

Figure 18. Establishing connection to ClearQuest

1. Type the name of the record type and select the corresponding record type. If you selected to create a new record type, you should specify the name of the table of the record type in the ClearQuest data base (see Figure 19. Specifying the name of the record type). Then you need to specify import parameters. If you need to add actions of deleting and modifying records, then select the corresponding check boxes and type the names of the added actions.

Figure 19. Specifying the name of the record type

1. To perform import, click the Perform button. The application will perform the import. Import results will be displayed in the new window (see Figure 19)

Figure 20. Import results

Figure 21. Imported record type in ClearQuest Designer

Export from ClearQuest

1. Click the Refresh button. In the opened dialog, specify the parameters necessary for establishing the connection.
2. Select the schema with the record type whose state diagram should be exported (see ). States and transitions between them are displayed with minimum intersections, so that it would be convenient to examine it.

Figure 22. Preview of a state diagram for a record type

1. Click the Export button and specify the type and name of the file, which the diagram should be exported to.

Figure 23. Exported diagram opened in Visio

Creating a document

1. Click the Refresh button. In the opened dialog, specify the parameters necessary for establishing the connection.
2. Select the schema, for which the document should be created (see Figure 24. Selecting the schema for documenting)
3. 

Figure 24. Selecting the schema for documenting

1. Specify the number of the schema version (by default, the last version is specified, see Figure 25. Selecting the version of the schema):

Figure 25. Selecting the version of the schema

1. Select the set of the record types for documenting, set the parameters and click the Create document button (see Figure 26. Setting the documenting parameters)

Figure 26. Setting the documenting parameters

Figure 27. Example of relations with other record types

1. Update help text for fields. First create a document with options Include help text, Include the service data selected. Apply changes necessary for displaying help for record fields to the created document; re-establish the connection on the Documenting tab; click the Update button and select the file with changes.
2. Fill in the document template. In this case, documenting of the schema is performed on basis of the created template (service information for templates is described in section 7.5 Filling in the document template) Establish connection to ClearQuest, click the Fill in the template button, then select the document template for filling in.

Filling in the document template

Tags for specifying information about the schema

• SchemaTemplate indicates that this tag is for including the information about the schema.
• information type specifies the type of the information to be included into the document and can take on one of the following values:
  • info - indicates that the general information about schema is to be included;
  • relations - indicates that the relationship diagram for requests in the schema is to be included.

Tags for specifying information about record types

• RecordTypeTemplate indicates that this tag is for including the information about a record type.
• record type name specifies the name of the record type that is to be described in the document.
• information type specifies the type of the information to be included into the document and can take on one of the following values:
  • relations - indicates that the relationship diagram representing relations of record type fields with the other record types of the schema is to be included;
  • adiagram - indicates that the relationship diagram for a record type is to be included.
• smatrix - indicates that the transition matrix for a record type is to be included.
• actions - indicates that the action list of a record type is to be included.
• fields - indicates that the action list of a record type fields is to be included.
• behavior - indicates that the behavioural table of a record type fields is to be included.

• [RecordTypeTemplate;record type name;relations];
• [RecordTypeTemplate;record type name;adiagram];
• [RecordTypeTemplate;record type name;smatrix];
• [RecordTypeTemplate;record type name;actions];
• [RecordTypeTemplate;record type name;fields];
• [RecordTypeTemplate;record type name;behavior].

License policy

Figure 28. Viewing information about the application and the license

Known issues and troubleshooting

1. The schema is in the Check Out state - for the selected schema, in the Designer, perform Check In or Undo Check Out.
2. The name specified for the record type already exists - specify another name for the record type or delete the record type of the same name from the schema.

Tags: ALM, Application Lifecycle Management, architect, change, change request, clearquest, CM, designer, diagram, functional, ibm, management, rsa, software, solutions, staruml, state, uml, uml2clearquest, Add more tags...,

or Close