Formal Review Elements
A Review element is a simple yet powerful mechanism for capturing, in real time, discussions concerned with a particular event on one or more elements and/or diagrams. Typically, a Project Manager or other coordinator will create a Review element specifically to discuss one or more objects for a project phase, project stage or other category of review, over a defined period. A number of reviewers then 'join' the review and enter discussion points and responses in the Collaborate window. Note that you can only be joined to one Review element at a time.
The most direct and structured scenario would be for the review coordinator to create the Review element through the Reviews window. The Review element is a composite element that generates a child diagram, and the review coordinator would then add the elements and/or diagrams (as Navigation Cells) to be reviewed to that child diagram. A joined reviewer simply selects objects on the diagram and adds topics or responses on each object to the 'Review' tab of the Collaborate window.
The Review element also acts as a bridge to continue focused discussions in subsequent work sessions.
The review comments pertinent to an element can be displayed in that element on a diagram, in the Review Compartment of the element.
This feature is available in releases of Enterprise Architect from 14.0 onwards.
If you want to simply comment on or discuss an element or diagram without capturing your discussion in a formal review, use the 'Discuss' tab of the Collaborate window. See the Informal Discussions Help topic.
Using Review Elements
Review elements are used to plan and coordinate a formal review of part of your model, defining:
- When the review is to start and end
- What elements or diagrams are to be reviewed (and, as the review progresses, which objects have not yet been reviewed)
- The current status of the review
- Any specific instructions for performing the review
- Who is involved in the review
- Any resources to use during the review
- The priority of the review
The start and end date information is defined in two special EAReview Tagged Values (on the Review element 'Properties' dialog, see the 'General' page and 'EAReview' tab):
- EndDate - the date on which the Review will be complete with no further discussions expected
- StartDate - the date from which users can join the review, and add discussions and responses
Other information can be provided through the Review element's normal element properties including Linked Documents, Notes and associated Note elements, Tagged Values and attributes. Review elements and their contents can be the subject of searches and document generation, all of which add to the information-gathering and grouping purposes of the element. The element also has a child diagram that aids planning, management and coordination of the review, and that provides a quick overview of and access to the elements under review.
Review elements can be used in a number of contexts, including model development, testing, delivery, maintenance and management. They can be added to specific Review diagrams - which have their own 'Review' Toolbox page - or to more general diagrams, using 'Review' icons from the 'Review', 'Artifact', 'Maintenance' or 'Management' toolbox pages.
Review elements are generally set up and managed within Enterprise Architect, but users both of Enterprise Architect and of the WebEA facility can use Review elements to direct their input to discussions on project and model reviews.
Creating a Review element
Typically, to create a Review element:
- Open the Reviews View ('Start > Collaborate > Reviews > All Reviews').
- Right-click on the View background and select the 'New Review' option; the 'Create Review' dialog displays, with the 'Name' field defaulting to the name of the currently-selected Package.
- If necessary, overtype the name with a different Review element name.
- In the 'Status' field click on the drop-down arrow and select the appropriate status.
- In the 'Start' field, click on the drop-down arrow and select the date on which the review starts.
- In the 'End' field, click on the drop-down arrow and select the date on which the review should complete. Click on the .
- In response to the prompt for the owner Package, either accept the current Package or browse for a different Package. Click on the OK button.
- You are automatically joined to the review, in the Collaborate window, and can create some initial discussion points. A Review diagram is automatically created and displayed, containing the Review element.
Alternatively, you could start by creating a Review diagram (a Custom diagram in the 'Extended' category) or a diagram of any other type, and drag onto it the 'Review' icon from the Diagram Toolbox (as indicated in the Using Review Elements section); the icon and element have these appearances:
The element defaults to the Infoview display format, which you can edit or disable. You would then display the element 'Properties' dialog and provide the start and end dates on the 'General' page 'EAReview' tab.
Locating Review elements
In order to join a review, you have to locate the available Review elements and select the appropriate one.
Select the 'Start > Collaborate > Reviews > All Reviews' ribbon option. The Reviews window displays, showing the Review elements that exist in the model, grouped according to the 'Status' value.
Having listed the available reviews, you can join one by right-clicking on it and selecting the 'Join Review' option. This makes the review your Active Review, and the entry displays in bold. (Right-click on the View background and select the 'Refresh' option.)
Further information on the Reviews window is provided in the Manage Reviews section later in this topic.
There are a number of alternative options for locating Review elements. In the header of the 'Review' tab in the Collaborate window, click on the icon and select one of these options:
- 'All Reviews' to open the Reviews window, as just described, to list all Review elements
- 'Review Details' to display the discussion history of your current review, and to show the details of the elements reviewed
- 'Find Current Review' to locate your active Review element in the Project Browser
You can also select four reports from the 'Find in Project' window, Discussions group (select the 'Start > Explore > Search > Model' ribbon option and the 'Discussions' option in the drop-down list in the first field):
- Review - Lists the Review elements that exist in the model
- Recently Modified Reviews - Generates a list of Review elements that have been recently created or modified
- Recently Discussed Reviews - Generates a list of Review elements in which discussions have taken place
- Open Reviews - Generates a list of Review elements with the status 'Open', which can be joined for discussion
To join a review, select the 'Start > Collaborate > Reviews > All Reviews' option, right-click on the required review from the Reviews window and select the 'Join Review' context menu option.
Alternatively, to join a review you could:
- Right-click on the appropriate Review element in a diagram, the Project Browser or the results of a model search, and select the 'Join Review' context menu option
- If a review is shown in the 'Review' tab of the Collaborate window, right-click on it and select the 'Join Review' option; the name of the review element then becomes the button name at the top of the screen, and the review topics for the currently selected model element display in the body of the window
When a user has joined a review, that is their Active review until they leave the review again. The Review element links to the review topics and posts of each joined user until they either log out of the model or select the 'Leave Review' context menu option.
When you log back into the model, and/or want to continue adding to the review, you can join it again using the 'Join Review' menu option.
Contributing to a Review
After you have joined a review, select the 'Start > Collaborate > Reviews > Review' ribbon option. The Collaborate window displays at the 'Review' tab.
Click on the element or the Navigation Cell for the diagram that you want to comment on, in the Review diagram or the 'Details' tab of the Reviews window, to make that object the focus of the Collaborate 'Review' tab.
Alternatively, click on the object to review in the Project Browser or a non-Review diagram and:
- Right-click on the object > Collaborate > Review
To create a topic for review or make a response to a topic, use the guidelines provided in this table.
Create a review topic
At the end of any existing review conversation, the message Create Review Topic displays. Double-click on the message and type your topic as continuous text (no carriage returns). The text automatically wraps at the border of the Collaborate window.
If you do need to break your text into paragraphs, press at the break point.
When you have finished typing, click off the text or press the .
If user security is enabled and you have selected to show avatars, the review icon is replaced by an image representing the user who contributed that item. If the user does not have a personal avatar image, a default 'head and shoulders' silhouette displays as the avatar.
|Set User Avatar|
Add a response
Double-click on the 'Post Reply' message and type your response as continuous text.
When you have finished typing, click off the text or press the .
You can also right-click on a post and select the 'Post Reply' menu option. All new replies are added underneath the review thread they are in response to.
Whilst you are typing a message, the editor automatically checks the spelling and underlines possible spelling errors in red. You can backspace or move the cursor to the errors to correct them. You can also move the cursor anywhere in the message body and add or delete text (press the ).
Once you have posted a message, you can delete the whole message but you cannot edit it.
Copy review topic text
If you want to re-use some or all of the text of a review item, select the text before you save it and press to copy it to the clipboard. You can then paste the text into a new review item or into another document in Enterprise Architect. You can also paste copied text from the clipboard into the review item, by pressing .
Set review topic status
A new review topic has the status of 'Open', with no indicator. To change the status, right-click on the item and select either:
If the review topic already has one of these statuses, you can also select the 'Status | Open' option to return the topic to 'Open' status, indicated by the icon.
Set review topic priority
As part of the review, you might want to identify the priority of a point being raised. It might be very important to act on the point, or it might be agreed that the point discusses a 'nice to have' feature that could be addressed at a later date. To set the priority, right-click on the review topic and select one of the options:
Alternatively, if you decide that an item does not need to be prioritized, select the 'Priority | <none>' option. This leaves the item icon as .
Delete a review topic or reply
Right-click on the review topic or a reply, and select the 'Delete Selected' menu option. A prompt displays to confirm the deletion. Click on the .
If you delete a review topic, all replies associated with that topic will be deleted as well.
Select the 'Start > Collaborate > Reviews > All Reviews' ribbon option.
(Alternatively, click on the 'In Review' button across the top of the 'Review' panel in the Collaborate window and select the 'All Reviews' option.)
This displays an overview of all Review elements in your model, enabling you to quickly see what reviews are taking place and what is happening within any review you want to explore.
If you are already joined to a review, your active Review element is displayed in the list in bold. Otherwise, you can join a review by right-clicking on the Review element name and selecting the 'Join Review' option. Equally, you can leave your active review by right-clicking on it and selecting the 'Leave Review' option.
Right-click on the Review item you have joined, and select the 'Review Details' option to display the Reviews window at the 'Details' tab.
For each Review element there is a 'Set' segment that identifies the elements to be reviewed as added to the Review diagram. Additionally, there is an 'Other' segment that identifies any review activity on the Review element itself, or on any other elements in the model that are added to the review but not included on the diagram.
The columns of the display show a number of properties of each element in the review.
These properties include the start and end dates of the review period, the number of topics posted for the element, the number of those topics open or awaiting review and the number closed, the number of topics and replies posted in the last three days, between three and fifteen days ago, and more than fifteen days ago. You can change the sequence of these columns if you prefer, by dragging the column headings across the heading band.
You can right-click on:
- The column headers to add or remove columns using the 'Field Chooser', and to display the bar to filter the list for review topics having a specific property
- An element name to display the element Review topics and comments on the 'Review' tab of the Collaborate window
- An element name to find the element in the Project Browser (or double-click on the item); this also opens the Collaborate window for the element
- An element name to locate any diagrams that contain the element
- The window and select the 'Refresh' option to refresh the list, to include any review topics that have been posted since you opened the review
The 'Field Chooser' dialog offers additional columns to add to the Review listing.
If you are not joined to a review, you can also create a new Review element by clicking on the 'New Review' option, as explained at the top of this topic.