Reviews in WebEA
Review elements are a convenient way for groups of users to collaboratively discuss one or more model objects and capture those discussions as a formal review. A Review element is a custom element that captures all discussions that you participate in over a period of time. That period begins when you select to 'join' the review, and ends either when you select to leave the review, or when you log out of the current model. You can also return to the review in a subsequent work session and your continuing discussions are also captured. The Review element would typically have a start and end date set to define the duration of the review.
When a Review element is created, a child diagram is also created, automatically. Both Enterprise Architect and WebEA consider any element added to this diagram as requiring comment during the Review. When the properties of the Review element are loaded in WebEA the 'Objects in Review' section will contain a list of all elements that have already been commented on or have been added to the Review diagram. This list provides a convenient way to quickly navigate to each element in the Review.
When the properties of a Review element are loaded in WebEA, a section of information is presented immediately under the element's notes, providing a summary of the review such as the status, start and end dates, number of elements discussed and yet to be discussed, and a break down of review topics based on priority and status, as illustrated here:
The 'Objects in Review' section immediately follows the Summary section. This displays a list of elements to be discussed during the review. Elements that have not yet been discussed are presented first in the list, followed by elements that have been commented on, showing each review topic (and, when you click on the expansion arrow, its replies), as illustrated here:
The name of the element on which the discussion point is raised acts as a link to open that element's own 'Properties' display. The review discussions are displayed in the 'Reviews' panel. If you have currently joined a review then the 'Reviews' panel is filtered to show only discussions for that review.
If you are not in a review then the 'Reviews' panel might show multiple reviews in which the element has been discussed. In either case the review name acts as a link to the Review element.
You can only participate in a single review at any given time. If necessary you can leave a review and join it again at a later time or date.
There are a number of ways in which to locate existing Review elements to join, or to switch to your active review (the review that you have already joined).
To check on recent Review elements available in the model, click on the 'Search' icon in the WebEA header and select the 'Reviews' option. This conducts a search for recent Review elements and lists them in the 'Search Results' view, with the most recently changed element at the top of the list.
You can click on the name of a Review in the list to load the details of the selected Review element, and then join or leave the Review as appropriate.
The name of your active Review is displayed in the WebEA's Status bar, and you can click on the name (in the Status bar) to load the details of the active Review element.
Join a Review
While the property details of a Review element are loaded, the 'Join Review' button will be enabled.
Clicking on this button will join you to the review and link your discussions to the Review element. The display will automatically be adjusted to the change of state. These changes include:
- The addition of the joined Review element's name to the status bar
- The 'Review' panel filtering elements to the current Review element only
- The 'Discussion' panel's update/add actions being disabled
- The being disabled, and the being enabled
There are some situations where the 'Join Review' button is already disabled for a Review element. If you are using WebEA on a desktop device, use the mouse to hover over the button to display a message explaining why the button is disabled. The reasons for not being able to join a review include:
- You are already joined to a review on a different Review element
- The loaded Review is closed
The Join Review button and Leave Review button are only visible on Review elements when the 'participate_in_review' configuration option is set to true for the current model. See the How to configure WebEA models Help topic for more information.
Add topics to a Review
When you have opened and read through the contents of a Review element, you can add your own review topics or respond to existing points. To do this you click on the name of the element you want to comment on, and display the Properties view for that element. The Properties view includes a 'Review' panel containing any existing review topics and a 'Create Review Topic' prompt.
Note that the panel also contains a reminder that - whilst you are joined to a review - the contents of the panel are filtered to show only the review comments for that review.
Add a Review Topic
To create a review topic on a new point, simply start typing in the blank field. If you want to have separate paragraphs, press the to start each new line.
Note: WebEA does not support editing (or deleting) review comments, therefore you should take care to type messages in clearly the first time, and double check before submitting.
Depending on how the WebEA model is configured, you might connect to it using your personal user ID, or as a single generic User that is shared by multiple people. In the second case, Sparx Systems recommends that each user identifies themselves in each message, either at the beginning or at the end.
When you have finished typing your message, submit it by clicking on this button:
Whilst you are adding comments to a review, at any point you can return to a posted topic and add or change its status and priority. To the right of the review topic text are two icons. The first is the 'Status' icon, and the second is the 'Priority' icon. The appearance of the icons depends on the current setting for status and priority. To set a status or priority, simply click on the appropriate icon and select from the listed options. These are:
Add a reply to a comment
If you want to respond to either a review topic or a reply to that topic, click or tap on the appropriate message. A blank field and button underneath the conversation thread will appear; type in your message and click or tap on this button:
Your reply is added to the end of the thread.
Note: Currently the review threads are only read from the database when the page is loaded, which means if other users make additional comments these won't be displayed until the page is reloaded or refreshed.
Review another element
Click on the name of the Review element in the 'Reviews' panel or in the page footer, to display the Properties view for that review element. Select another element in the review from the list.
Leave the current Review
When you have finished contributing to the review, you can either return to the Review element Properties view and click on the , or log out of the current model.
The Leave Review button will only be enabled when the details of the currently joined Review element are loaded.
Creating a Review
Typically, only a Project Manager will create Review elements in Enterprise Architect, notifying the relevant users of their location so that each user can join and leave the review(s) as necessary.
However, a WebEA user might create a Review element as a direction to the Project Manager to set up. In this case you create the Review element by clicking on the 'New' icon in the Package hierarchy view, selecting 'Review' as the element type. The procedure is as described in the Add Elements and Features in WebEA Help topic.
You require specific access permissions to create a Review element; those permissions are totally separate from the permission to join a review.