Using ElaborView to Review and Comment Designs

Requirements

For this tutorial you need:

1. Visual Paradigm Suite 5.1 or higher (You can skip this if you already have VP-UML 8.1 or higher installed)
2. ElaborView Server 1.0 or higher
3. ElaborView 1.0 or higher
4. Two valid Email addresses you can access

Products Installation

This section guides you through the installation of VP Suite, ElaborView Server and ElaborView in brief. If you have already installed any of them, you may skip the related parts.

To install VP Suite and VP-UML:

1. Double click on the VP Suite installer file to execute it. Click Next in the welcome screen.
2. Read through the license agreement. Check I accept the agreement if you accept, and click Next to continue.
3. Specify the installation path of VP Suite. Click Next.
4. Give a name to the start menu entry. Click Next.
5. Click Next in the File Associations page.
6. Select Visual Paradigm for UML (VP-UML) for the product to install. Click Next.
   
7. Click Next in the Configuration page.
8. Specify the file path of license key. If you do not have one, click on Request Evaluation Key to obtain an evaluation key. Click Next. This begins file copying.
   
9. When installation is completed, select Don't start and click Finish.

To install ElaborView Server:

1. Create a folder for storing the server program. Here we create the folder C:\VP-Tutorial. (You may create the folder elsewhere in your machine)
2. Extract the downloaded zip of ElaborView Server program to the created folder. You should obtain a path like this: C:\VP-Tutorial\ElaborViewServer\scripts
   
3. Start the server by running ElaborViewServer\scripts\startup.bat. A console will be opened. Do NOT close it until the end of this tutorial. Otherwise the server will stop running.
4. Open a web browser.
5. Visit http://127.0.0.1:8081/. Note that 8081 is the default port of ElaborView server.
6. You should see the server configuration page. Enter an administration password. Enter your organization name and click Confirm.
7. In the Setup ElaborView Server page, keep the database setting as is (i.e. using Embedded DB with the default database name unchanged). Fill in YOUR OWN mail server setting. Do not enter what you can see in the image below as that is for Visual Paradigm only. Before continue, click on Send test email and check your Email box to make sure the mail setting is correct. It is very, very important to have a valid mail server setting. If not, you will not be able to continue to the next section.
   
   
   

   If you are unclear about the mail server setting, you may look up in your Email client, or try to search on the Internet with keywords like "mail server 0". You may also find the following pages helpful if you are using Gmail or Yahoo. Gmail - http://mail.google.com/support/bin/answer.py?hl=en&answer=13287 Yahoo Mail - http://help.yahoo.com/l/us/yahoo/mail/classic/mailplus/pop/pop-14.html

8. Keep Captcha on. You will know what it is later on in this tutorial. Click Install. This completes the server setup and redirects you to the mail administration page.

To install ElaborView:

1. Double click on the ElaborView installer file (e.g. ElaborView_Windows_1_0_20101215.exe) to execute it. Click Next in the welcome screen.
   
2. Read through the license agreement. Check I accept the agreement if you accept, and click Next to continue.
3. Specify the installation path of ElaborView. Click Next.
4. Give a name to the start menu entry. Click Next.
5. When installation is completed, select Don't start and click Finish.

Project owner - Designing

In this section, we will draw a simple class diagram in VP-UML. The diagram will be sent to ElaborView Server for commenting in the next section.

1. Start VP-UML in a new workspace.
2. Create a class diagram from the Diagram Navigator. Right click on Class Diagram in Diagram Navigator and select New Class Diagram from the popup menu.
   
3. Skip the package header by pressing Enter. Then enter Domain Model for diagram name. Press Enter again to confirm editing.
   
4. Draw a diagram with three classes User, Account and VIP Account, as shown in the image below:
   

Project owner - Sending design to ElaborView Server

The design has been completed. Let's move on to sending the design to someone (e.g. your supervisor) to review and comment.

1. In VP-UML, open the ElaborView Manager by selecting File > ElaborView Manager... from the main menu.
   
2. You need to create an account for yourself. Click on the ... button next to the drop down menu of Connection name.
   
3. In the Login dialog box, click on Add Connection.
4. Enter 127.0.0.1 as hostname. This is where the ElaborView Server got installed. Since the server is running on this computer in this tutorial, we shall enter 127.0.0.1, the local host IP. Enter 8081 as port.
   
5. Click on Request Account.... Click Yes when you are prompted to save connection.
6. Enter your own Email address, the display name and captcha. Click Request.
   
7. Check your Email box. You should receive an activation Email sent by ElaborView. If you do not find such Email, check your junk folder to make sure it was not filtered by the mail program. Click on the activation link appears in the Email to continue.
   
8. On the web page prompted, enter and password and click Activate. You may close the page once activated.
   
9. Go back to VP-UML. Enter the password you just entered in the Password field and click Connect.
   
10. The people who are going to review your design are called reviewers. You, as a project owner, have to invite the reviewers to review your design. Click on Create Reviewer....
    
11. Enter the Email address of the reviewer, the display name and enter captcha. Click OK. In order to complete this tutorial, make sure you can receive Email with the address you supplied here. (in this tutorial you will also act as the reviewer)
    
12. Reviewer should decide to accept or reject the invitation. Check the reviewer's Email box. You should receive an Email. Click on the accept link in the Email.
    
13. On the web page prompted, enter and password and click Activate. You may close the page once activated.
    
14. In ElaborView Manager, click on the Refresh button to let ElaborView manager recognize the acceptance of reviewer.
    
15. Now, you can send the class diagram to ElaborView Server. Click on Send to ElaborView Server....
    
16. In the Send to ElaborView Server dialog box, enter My Project for project name, keep Peter selected as reviewer and select the diagram Domain Model to send to server. Click Export.
    
    Now, an ElaborView project has been created in server. Reviewer can start commenting with ElaborView.

Reviewer - Commenting

Having sent the designs to ElaborView server, reviewer can start commenting. In this section, you will act as the reviewer to comment on the design done in VP-UML.

1. Start ElaborView from the bin folder of ElaborView installation directory.
   
2. In ElaborView, click on Server and select Login to... from the menu.
   
3. In Login dialog box, click on Add Connection.
4. Enter 127.0.0.1 for host name and 8081 as port. Enter the reviewer's email address and password as supplied by project owner in previous section.
   
5. Click Connect. When you are prompted to download update, click Yes. You should see the ElaborView project downloaded and appearing in ElaborView.
   
6. Double click on My Project to open it.
   
7. Double click on diagram Domain Model to open it.
   
8. The left hand side lists the tools for commenting. Let's say the class VIPAccount should not exist. You want to ask the designer to remove it. Select the Pencil tool.
   
9. Press and drag over VIPAccount class to form a slash.
   
10. Select red.
    
    The screen should look like this:
    
11. You find that the class User and Account can be combined into a single class. Let's draw a circle to surround them. Select the Oval tool.
    
12. Drag on diagram to surround the classes User and Account.
    
13. Select blue.
14. Just having an oval is not enough for representing the need of combining them. Let's add a note. Click on the border of oval. This creates a note. Enter Combined them to be note content.
    
15. You have finished reviewing and commenting. Let's submit the comment back to server. Click on Submit Diagram... at bottom. Click on Submit when you are prompted to enter comment.

Project owner - Studying reivewer feedback

Now, project owner can get the feedback from server, to study the comments made by reviewer.

1. Go back to VP-UML.
2. Open the ElaborView Manager (if it is closed).
3. In the Server tab, click on Get ElaborView Submission.... When you are prompted to download submission, click Yes.
   
4. Select the submission entry in table. Click on Open.
   
5. You can see in class diagram the comments reviewer made. Click on the oval and freehand to study them one by one.
   
6. Correct the design base on reviewer's comment. First, delete the class VIPAccount.
   
7. Right click on the slash on diagram and select Mark as Read. This removes it from diagram.
   
8. Rename the class Account to UserAccount and delete the User class.
   
9. Right click on the oval and select Mark as Read from the popup menu.
   
10. All the comments are studied and processed. You can set the ElaborView project as completed. Open ElaborView Manager.
11. Click on Complete(Updated) on the ElaborView project listed in Export section. When you are prompted for confirmation, click Yes.
    
    This causes the status change from Updated to Completed. This is the end of this tutorial.