Topics
Prev Next

Formal Review Elements

A Review element is a simple yet powerful mechanism for capturing, in real time, element discussions concerned with a particular event. Typically, a Project Manager or other coordinator will create a Review element specifically to discuss one or more elements 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 Discussions window.

The most direct and structured scenario would be for the review coordinator to create the Review element through the Reviews & Discussions view. The Review element is a composite element that generates a child diagram, and the review coordinator would then add the element or elements to be reviewed to that child diagram. A reviewer simply selects elements on the diagram and adds topics or responses on each element to the 'Review' tab of the Discussions window. Note that you can only be joined to one Review element at a time.

The Review element also acts as a bridge to continue focused discussions in subsequent work sessions.

This feature is available in releases of Enterprise Architect from 13.5 onwards.

If you want to simply comment on or discuss an element without capturing your discussion in a formal review, use the 'Discussion' tab of the Discussions window. See the Informal Element 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 are to be reviewed (and, as the review progresses, which elements 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

Some of this information is defined in three 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
  • Status - the availability of the Review element:
         -  Pending - (the default) the review session is still being set up; discussion points
            can be added as a focus of the review, but reviewers are not intended to join yet
         -  Open - the review is ongoing; reviewers can join the review and respond to the
            discussion points
         -  Closed - the review session is finished and discussions should not be added; the
            review coordinator might still add summaries and actions

Other information can be provided through the Review element's normal element properties such as 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:

  1. Open the Reviews & Discussions view at the 'Reviews' tab ('Start > Today > Reviews > Manage Reviews').
  2. Click on the Create Review button; the 'Enter review element name' prompt displays, defaulting to the name of the currently-selected Package.
  3. If necessary, overtype the name with a different Review element name and click on the OK button.
  4. In response to the prompt for the owner Package, either accept the current Package or browse for a different Package.
  5. You are automatically joined to the review and can create some initial discussion points. You can also edit the properties of the element itself and define start and end dates and the review status.

Alternatively, you could create 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.

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 > Today > Reviews > Manage Reviews' ribbon option. The Reviews & Discussions view displays, at the 'Reviews' tab, showing the Review elements that exist in the model. If the Review element already has a child diagram and/or review topics and responses, an expansion arrow displays next to the element name.

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 and becomes the only review in the list.

Further information on the 'Reviews' tab of the Review and Discussions view 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 Discussions window, click on the icon and select one of these options:

  • 'Manage Reviews' to open the Discussion Review window at the 'Reviews' tab, as just described
  • 'Find Open Reviews' to run a report to list all Review elements with the EAReview 'Status' Tagged Value set to 'Open'
  • 'Find Active 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 ('Start > Explore > Search > Search in Model > Discussions'):

  • 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

Performing Reviews

To join a Review, select the 'Start > Today > Reviews > Manage Reviews' option, select a review from the 'Reviews' tab of the Reviews & Discussions window and select the 'Join Review' context menu option. You can now add your own review topics and replies (or Posts) to the review.

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 Discussions 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

Select the 'Start > Today > Reviews > Review' ribbon option. The Discussions window displays at the 'Review' tab.

Double-click on the element that you want to comment on, in the diagram or the Reviews & Discussions view, to make that element the focus of the 'Review' tab.

To create a topic for review or make a response to a topic, use the guidelines provided in this table.

Operation

Action

See also

Create a review topic

At the end of the 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 Discussions window.

If you do need to break your text into paragraphs, press Ctrl+Enter at the break point.

When you have finished typing, click off the text or press the Enter key.

  • An open expansion arrow and a icon display at the start of your text, and the Review status, your user name, the time or date of posting and (if set) the priority of the item display beneath your text
  • The messages Post Reply and Create Review Topic display below the topic

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 Enter key.

  • A icon, the time of posting and your user ID display above your text
  • The message Post Reply displays beneath your text

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.

Edit postings

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 Delete key).

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 the text of a review item, select the text and press Ctrl+C to copy it to the clipboard, either before you save it or after you have posted it. 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 Ctrl+V.

Set Review Topic Status

The system text against a new review topic indicates that the topic has the status of 'Open'. To change the status, right-click on the item and select either:

  • 'Status | Awaiting Review' to indicate that some form of confirmation or approval is required for the point raised in the review topic, or
  • 'Status | Closed' to indicate that users should not add any further comments to the thread

If the review topic already has one of these statuses, you can also select the 'Open' option to return the topic to 'Open' status.

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:

  • 'Priority | High'
  • 'Priority | Medium', or
  • 'Priority | Low'

Alternatively, if you decide that an item does not need to be prioritized, select the 'Priority | <none>' option. This leaves the item description as '[? priority]'.

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 Yes button.

If you delete a review topic, all replies associated with that topic will be deleted as well.

Manage Reviews

Select the 'Start > Today > Reviews > Manage Reviews' ribbon option.

(Alternatively, click on the 'In Review' button across the top of the 'Review' panel in the Discussions window and select the 'Manage 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, only the corresponding Review element is displayed in the list, in bold, as your active review. 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.

For each Review element there is a 'diagram' segment that identifies the Review element's child diagram and the elements to be reviewed that are on that 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 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 (Actions) and the number of those Actions 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 Filter bar to filter the list for review topics having a specific property
  • The view background and select to hide or display a Preview pane on the right or at the bottom of the window; click on an element name to show in this pane the full text and details of each review topic, the number of responses and the text of each response
  • The view background and select to filter the display for Reviews with a review period occurring today, or in the last 7, 30, or 90 days, or all reviews in the project
  • An element name to find the element in the Project Browser (or double-click on the item); this also opens the Discussions window for the element, at the 'Review' tab
  • 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 these additional columns to add to the Review listing:

  • Start (date of the review period)
  • End (date of the review period)
  • Review Status (of the Review element)
  • Author (of each element)
  • Type (of element included in the review)

If you are not joined to a review, you can also create a new Review element by clicking on the Create Review button, as explained at the top of this topic.

Learn more