Document Commenting in Managed Projects_AD
This document is no longer available beyond version 21. Information can now be found here: Project Commenting for version 24
Parent page: Managed Projects and Releasing a Design
Altium Designer in conjunction with your managed content server supports Managed Projects, which enables a dispersed design team to collaboratively work on projects that are centrally stored and managed through that server. Related to this, the design interface also supports the commenting of design documents. Comments – user-added notes – can be applied to a point, object, or area on a schematic or PCB document and may be replied to by other users.
Placed comments are available in real-time to collaborating users – those that have shared access to the document – and are saved to the server independently of the project, without altering its constituent documents in any way. The commenting feature is managed through the Comments panel (View » Panels » Comments), which provides the means to place, select, edit, resolve and remove comments. Within the document editor, the comments are effectively 'pinned' to document locations, and are accessed via an associated pop-up window.
Adding a Comment
Note that Comments can be added and managed in both Altium Designer and in the related server, via its web interface design view. The functionality of the two commenting systems is essentially the same, and since both the project and commenting data are stored in the server, the systems work together in real time.
► See Commenting in the Web Viewer for detailed information on the commenting system in an Altium 365 Workspace.
Prerequisites
Before using the commenting feature, ensure that you are signed in to your managed content server (such as a Workspace), and have opened a Managed Project and one of its schematic or PCB documents. Use the File » Open Project command to choose a server-based project from those that have been shared with you. The Comments panel will provide textual hints for these prerequisites:
Placement
Comments are placed in the editor space from the command button available in the Comments panel or by clicking near the top right of the design space and may be assigned to an object, a specific point, or an area on the active document. The command invokes the comment placement mode, where the cursor changes to a crosshair that detects and highlights objects for selection:
- Click a highlighted object to attach (pin) a comment to that object.
- Click in an un-highlighted area to attach a comment to that specific point on the document.
- Click away from an object and drag the cursor to create a rectangular highlighted area, and then click again to confirm its final shape to attach a comment to the specified area. ► See example.
The placement action then opens a comment entry dialog that offers a field for entering the comment text, and also additional options for adding a freehand drawing to the comment () and including a reference to a specific user or group (). Click to confirm the comment creation, which will associate the comment with a numbered pin marker on the document and also add a comment summary entry to the Comments panel.
Mentions and Assignments
Along with text in the comment entry dialog, a 'mention' reference can be added for any other user or role registered with the connected Workspace by entering the @ character or clicking the dialog's button. Select a name/email from the dropdown list to add the user (team member) reference to the comment, and also as an Assign To entry. Uncheck the latter option if you do not wish the comment to be regarded as specifically assigned to that user or group. A Role group (say, 'Engineers'), and therefore its constituent users, may also be added as a mention and/or assignment.
If a mentioned user does not have access to the current project you will be invited to share it with that user. User Access Rights are granted through the Share dialog, and the user will receive an email notifying them of the shared access.
► See more information about sharing a design.
Positioning
A comment's location in the editor space is moved by dragging its associated 'pin' to a new position – during or after its placement. When selected, the comment pin includes a connecting line to its associated object or area.
Note that a comment also may be positioned during its initial placement by clicking and dragging when in placement mode. ► See example.
Drawing
When placing or editing a comment, select the option to add freehand drawing with the resulting pen cursor. Click and drag to create lines, and then right-click to finish and associate the drawing with the currently selected comment.
PCB Comments
Comments also can be placed on a board layout in the PCB editor space using the same placement approach to that in the schematic editor. When a comment entry is selected in the Comments panel, the system will open (and load if necessary) the associated design document. ► See example.
Working with Comments
Comments placed in a design document are registered in both the Comments panel (as a sequence of numbered entries) and in the corresponding document editor (as numbered pin graphics). Each panel entry represents a comment thread and provides summary information that includes who placed the comment and when, the initial comment text, any applied mentions/assignments, and the number of thread replies.
A comment thread is opened by selecting its entry in the Comments panel, or by clicking on its associated pin in the editor space. This highlights the comment in the document editor and opens the comment entry dialog, which includes the initiating comment and any user replies. If a selected comment is associated with another design document, the system will open (and load if necessary) that document.
Comments Dialog
Interaction with a placed comment is through the pop-up comment dialog, which shows all entries in the selected comment thread and includes options to preview, reply, edit, resolve and delete an entry. The dialog is opened when initially placing a comment, or when a placed comment is selected in the Comments panel or in the document editor. Press Esc or click in the editor space to close the comment dialog.
Preview
Select the Show original design screenshot option in the initial comment to see a graphical capture of the editor area when the comment was placed.
Reply
Enter text and optionally a user mention (@), in the reply field to add a new entry to the comment thread. Click to confirm the entry.
Edit and Delete
An existing comment may be edited by the author of that comment using the Edit option available from the comment's menu. Click the button to confirm the comment edit.
Use the Delete option to remove the currently selected comment. Note that the entire thread will be removed if the initial comment (as opposed to a Reply) is deleted.
Resolve
Click the dialog's button to toggle the comment state between Resolved and Unresolved (the default). A resolved comment (closed as complete) is inactive and non-editable, and both its entry in the Comments panel and its pin marker on the document are grayed out.
Comments panel options
Use the buttons at the top of the Comments panel to set the availability of comments in the panel and editor space, and to specify if mentioned users are notified.
The panel's button toggles the visibility of comment marker pins on the document. Comment entries still may be selected as usual in the Comments panel listing.
Use the options drop-down menu () to configure comment visibility filtering and notifications, and the associated button to toggle between the filtered and unfiltered view:
- All – all comments placed on the design will be listed in the panel.
- My – show only those comments that mention my user name and/or are assigned to my user name.
- From – show comments placed by the selected user only.
- Unresolved – comments that have been resolved are not included in the panel (or document editor).
- Current Document – list only comments that have been placed on the currently active document, as opposed to all project documents.
- Notifications – receive email alerts for all comment activity in this design (All), for only those comments where you are mentioned or assigned to (My), or do not receive email alerts at all (None). ► Email content example.
Comments Display Preferences
The display and appearance of comments in the design space are configured in the Document Comments region on the Data Management – Servers page of the Preferences dialog. Controls are provided independently for comments displayed on the schematic and PCB. To turn off the display of comments in the document editor – relying on just the Comments panel – disable the respective Show Comment Threads option.
Other controls in the region relate to the look and feel of the comment and its reference line.