Installation

The latest build of the Use Case Editor is version 1.0.1308.23, made available for download late in August 2013.

Once you have downloaded the uceditor.zip file, you will need to unzip and install it. UCEditor needs to have the .NET framework version 4.5 installed on your machine. If you try and install it, and you do not have .NET 4.5 on your PC, please make sure your machine has the .NET Framework downloaded and installed from Microsoft first. After unzipping the editor, you will find a single file called setup.exe that needs to be run. There is no digital certificate attached to this file, so your Windows platform will probably complain that you are installing software from an unknown source. Go ahead and install anyway if you wish to use the Use Case Editor. Your system may also require you to run the installation as administrator on more recent editions of Windows. After installing UCEditor, an icon will appear on your desktop and an entry in your Start menu after installation. Windows 8 users will also have a tile added to their start screens.

If you intend to use PDF file viewing, you will also need to have a recent version of Adobe Acrobat Reader installed. The program was built and tested with Acrobat Reader 7, but also works with later versions.

If you intend to save models as Word documents, or to view the Word documents generated by the tool, you will need to have a copy of Office 2003 or later installed on your PC. Note that the Word documents are presently still the .DOC files, rather than the Office 2007 .DOCX files for compatibility reasons.

Using the tool to create a model

• Once the tool is running, try selecting File|Save As … from the menus to select the output filename for the XML file that the model will be saved to. You can name this file with either a .xml extension, or a .xz extension. XZ files are compressed XML files, approximately 10% the size of their equivalent XML files. You might want to do this for really large models. Note: This latest version of the use case editor no longer supports the earlier .xmz file type, as it now uses native ZIP compression of XML files provided by the .NET framework. If you have legacy .xmz files containing models, please open them directly with WinZIP or equivalent, and unzip the model file back to an XML file before opening it with the use case editor.
• A model is a collection of packages. Each package contains a group of related use cases. Hence first you will need to create some packages. Select Edit|Add Package … from the menu, and complete the package name and description in the panel on the right.
• Once you have a package, you can begin to add the actors to the model. Select Edit|Add Actor … to do this, and complete the actor’s name and description.
• Once you have established your set of actors in the model, you can begin to add use cases. Make sure you select a package in the treeview control at the left of the main window, then use Edit|Add Use Case … to add a new use case. In the panel that appears, set up the use case name (goal name) and then provide the brief description in the descriptive panel. You can also set preconditions and postconditions (minimal guarantees and success guarantees) for the use case in this panel if you wish. Postconditions represent observable facts that will have become true after the use case is over. Postconditions come in two categories. Success guarantees are postconditions that apply if the use case goal has been reached. Minimal guarantees are things that will be true once the use case is over, whether the actors goal has been reached or not.
• Click on the ‘+’ next to the selected use case in the tree view, to see the primary path symbol underneath it. Selecting this will take you to the casual/fully dressed tabs for this use case’s primary path. The casual description will be the same as the brief description for the primary path, as will the preconditions that must be true before the use case can run. This same panel is also used for casual descriptions of alternative paths, in which case the text and preconditions will have to be entered in this panel, rather than just mirroring the information about the primary path.
• Click on the Detailed Steps tab to see the fully dressed numbered step list for this path. Use Append to add a new step to the end of the sequence, then fill in its description. Select any step and click Insert if you wish to insert a step mid-sequence before the step you select. Click Delete to delete the selected step.
• To add an alternative path to a use case, make sure the use case is selected in the tree view at the left of the UCEditor main window, then select Edit|Add Path … from the main menu. This will create another path in which you can set the path’s precondition, extension point, description and remerge point. The detailed steps tab is also available for you to fill in.
•  Note that once you have set up the detailed steps for the primary path, and any number of alternative paths, the use case editor will have automatically generated activity diagrams for the whole use case. These are viewable in the activity diagram tab if you select a use case in the tree view control. If the diagram’s layout looks a little ugly, or if you have edited the step details causing a previously good layout to become ugly, you can adjust the diagram. Either select Edit|Reset layout from the main menu to have the editor rearrange the entire diagram for you, or right-click on the diagram and select Auto layout from the pop-up menu. If you still don’t like the layout, you can arrange the diagram to your own taste by selecting the items on the diagram with the mouse and adjusting them manually. See [13] below for more instructions on how to do this.
• Actors are not automatically associated with use cases. If you want to set up the actors involved in a use case, select the use case, then click Edit|Edit Use Case Actors … from the main menu.
• In the dialog that appears, check each participating actor in the list of actors on the left, and pick the single initiating actor from the dropdown at the right. Dismiss the dialog.
• Select File|Save or File|Save As … from the main menu to save your model out as an XML file. Alternatively, save the model with a .xz extension, and the XML file is automatically zipped, taking up around 10% of its normal XML file size, as mentioned before.
• If you wish to view a use case diagram for each package in your model, the current version of the tool will automatically draw a use case diagram for you. Select a package from the tree view control at the left of the main window, then select the use case diagram tab in the right pane.
• To edit use case or activity diagrams, you can click on symbols or connectors. When selected the selected items turn red. Rubber-banding also works to select a group of items. Use cases and actors can be dragged to different locations on the drawing, and the bends in the associations and dependencies can be moved by dragging the square grips. If you right-click on associations, or dependencies, you will see that you can either insert additional bends into lines, or remove existing bends completely. If you don’t like the automatic positioning of the labels on the connectors in the diagram, you can also drag these around independently of the connectors they annotate. As the automatic layout of the diagram will seldom be as aesthetically pleasing as you would wish, it is recommended that you adjust the diagram layout before printing to a PDF file or Word document. Note the edits to your diagrams will be saved as part of the XML model file as well.
• Activity diagrams are laid out automatically for a use case, but you may not like the layout, and might prefer to edit it. This can be done using the same selection and dragging mechanisms used to edit use case diagrams.
• A set of non-functional requirements may be added to the model. Each non-functional requirement has a title, and a textual description. A unique number is assigned to each non-functional requirement for traceability. To add a new non-functional requirement, select Edit|Add NF Requirement from the main menu, or click the toolbar button with the same icon. Similarly, to delete the currently selected non-functional requirement, select Edit|Delete NF Requirement from the main menu.
• Each use case can cross reference any set of non-functional requirements that will have an impact on its implementation/realization. With a use case selected in the tree view at the left of the main window, select the third (Non-functional requirements) tab on the right pane. The currently applicable list of non-functional requirements associated with this use case will be listed.
• To edit the set of applicable non-functional requirements, check the check box at the top of the pane. Now the entire list of non-functional requirements will appear, with check boxes selected for those that apply to the currently selected use case. Simply change the checked items to apply a different combination of non-functional requirements to this use case.
• It is possible to create a requirements level, domain object model, or entity relationship model that describes and structures the information your system needs to hold and manipulate. Information is structured into entities or ‘classes’ which contain attributes. Relations or ‘associations’ can be built between the entities, and labelled with verb phrases describing the association. The relations can be given multiplicities at each end.
• To add a new entity or class, select Edit|Add class from the main menu. Enter the chosen class name, and provide a detailed description of what that class or entity represents in the problem domain.
• If the class you are adding is just a simple primitive type, such as a number type for example, leave the radio button checked that says Type. If it is a class or entity with member attributes of its own, check the Class radio button. This will allow you to add attributes to the class, and to build associations between classes.
• To add an attribute, make sure a class has been selected in the tree view to the left of the main window. Note that it must be a class, not a primitive type to be able to add attributes. Now select Edit|Add attribute from the main menu.
• Fill in the details about your attribute. Note that the type of the attribute can be any other primitive type or class you have previously added to your model. If you need to set a new type for an attribute, add that type by using Edit|Add class as described above.
• To add relations or associations between classes or entities, make sure a class has been selected in the tree view first. Next, select Edit|Add association from the main menu. This will create a new association between the class selected in the treeview, and itself. In the window that appears on the right, change the target of the association to some other class (unless it was intended to be a self-referential association), and set the verb phrase and multiplicity in each direction. Note that your verb phrases should be chosen so that the association reads like a sentence. For example: “Each instance of Person owns 0..* instances of Dog”. Here the verb is ‘owns’. Complete your association description to explain the intended use of the association in your model.
• The tool also integrates a glossary section. Select the glossary node in the tree view and a list of already added glossary items will appear. Click on one of them to amend it. To add new glossary items, from the main menu select Edit | Add glossary entry and fill in the details on the panel that appears. Note that glossary terms are automatically highlighted in many of the text controls that appear in other parts of the modelling tool. You can right-click on any of these, and select the appropriate menu item to jump to the highlighted term’s glossary entry. Likewise you can select a range of characters, or just right-click in a word, and the menu will give you the option to add that term to the glossary. The glossary is formatted and output as the last section of each of the printable documents.

 

Loading previously created models

• Start the UCEditor program
• Select File|Open… from the main menu.
• If you previously had an unsaved model, UCEditor will bring up the file save dialog first for you to save the previous model away.
• Next UCEditor will bring up the file open dialog for you to navigate to the appropriate XML file previously saved by UCEditor.
• The file will be loaded and the model tree constructed in the tree view at the left of the main window. Carry on and edit the model as described earlier.

Printing and viewing model documents

• UCEditor has several types of model output as documentation. This particular version supports PDF file or Word 2003/2007 document output, and is a demonstration of what kind of report generation could be supported. The editor will also save the model as an HTML file with an associated CSS stylesheet file if you wish to upload your model documentation to a Web server.
• To save a model in a document format, select File|Save PDF … , File|Save HTML ... or File|Save Word … from the main menu. You can now choose the target filename and folder for output.
• Provided you have previously saved the document file for the model, you can also then view it using File|View PDF, File|View HTML or File|View Word from the main menu. Obviously the file can also be opened directly using Adobe Reader, Acrobat, a Web browser, or Office 2003/2007.

Full (supported) version features

The full edition of the use case editor comes with a version control engine, so that successive versions of the model can be kept as it is iteratively refined. The version control engine also supports a model comparison report that shows you how your model differs from the latest model stored in version control as you are editing. This means multiple requirements engineers can be gathering requirements as part of the same model, and are able to view and resolve collisions in their models before checking them into version control as the latest model. Here are some rudimentary instructions on how to drive version control.

• First make sure you are editing a model that you wish to place under version control. Make sure the filename is correct, because once the file goes under control you won’t be able to change it.
• From the main menu, select File|Version control|Create version store. In the dialog that appears, you can navigate to a folder with no existing version control store, to create a new store. The folder you select will either have the same name as your model file (without the XML or XZ extension), or a sub folder will be created that has the same name.
• To check out the latest version of the model from the store, use File|Version control|Check out from the main menu. A list of versions of the current model will be displayed, with the most recent at the top of the list. Select which model you want to check out, and click the button.
• Alternatively if you have not yet opened a version control store, select File|Version control|Open version store from the main menu. This opens an existing version control store, then takes you to the dialog used to check out a model, as in 3 above.
• To view differences between your model in its current state, and the latest version held in the version control store, select File|Version control|Differences from the main menu. You will notice that the differences are highlighted in pink, with presence or absence of model elements highlighted in grey. If you leave the differences window open, it will continuously update itself to reflect the differences as you edit the model in the main window.
• When you are happy your model is in a format fit to be a publishable version, you can select File|Version control|Check in. Read the warning message at the top of the dialog, and provide a brief description of what changes your version has made before checking your model in as the new latest version. The brief description will be listed alongside each version in the check out window when you attempt to check out models.

Feedback

This program was originally written as a demonstration to show what a use case based requirements capturing tool should be aiming for, namely: conformance to a standard template for writing use case requirements; automatic numbering of steps in detailed use case descriptions, including auto-adjustment of numbering in alternative paths; use case diagrams generated from the use case documentation rather than the other way round; layout editing for the diagrams; and generation of the output requirements model in industry standard document formats. In order that each user may benefit from improvements in its features, we would be very grateful for any suggestions you may have for alterations to the tool, or of bugs that you spot in particular. Latest builds can always be downloaded from here, with the latest version of these instructions and other documents about the tool being available on the www.ropley.com site.