Comment Tracker
Basic Document Comment Workflow
The Document Comment Tracker submodule is a robust platform for collaborative document revision. A basic example of hypothetical Document Comment workflow is as follows:
- When a new document is uploaded into a Workgroup, an admin or chair can enable comments on the document.
- Workgroup members can then review the document, and make comments related to specific sections.
- Comment administrators can process these comments and determine if they should be accepted, rejected, etc.
- If the comment is accepted, the document changes suggested in the comment can be made, and the comment can be released.
Please review this guide for details on the Document Comment Tracker submodule and the process describe above.
Enable Document Comments on the Site
In order for workgroups to use Document Comment Tracking, a site administrator must first enable sub Module.
You can visit https://your.site.com/siteSettings/subscription/customize or navigate to Admin → Site Settings Panel → Customize Subscription
First, in the "FEATURES AVAILABLE" section, under "Modules", make sure that "Documents Module" is checked. Then under "Documents Features", check "Document Comment Tracker Submodule".
You will notice an additional option under this section, labeled "Strictly enforce comment status process". If enforcement is enabled, when a user 'processes' a comment, if the user is not a site admin, it will only allow them to increment the status by one. That is, if there are three status, "started", "in progress", "completed", and a comment is currently on "started", comment processors can only change the status to "in progress", and not "completed".
NOTE Under Admin → Site Settings Panel → Advanced Settings (https://your.site.com/siteSettings/settings/index)
The "Document Settings" section on the bottom of the page has an "Enable Document Comments" checkbox. Checking or unchecking this option will not change Causeway behavior.
Enable Document Comments on a Document
If the Document Comment Tracker submodule is enabled, you can now begin to use comments on a per-document basis.
As a site or workgroup administrator, or a workgroup chair, when browsing documents, click on your target document so that you are taken to the "Document Details" page, then click on the Comments Settings link in the left menu. This is where you can enable and configure comments for a given document.
Basic options
Comments Open - Set this option to "Yes" if you would like users to be able to create new comments on the document. "No" will prevent them from creating new comments, but they can still view any previously added comments.
Allow Anonymous Comments - If true, and if the comment author checks "Post Anonymously" on the new comment page, this will list "Anonymous" as the author when displaying comment details. The actual author, however, is still stored in the Causeway database.
Information to Gather - If enabled, each option here represents a separate text box on the new comment page. If your organization would like to keep things simple, perhaps only the first "Comment Description" item should be checked. Otherwise, if you would like the author to specify the "Existing text" they are referring to, and the "Proposed text" they are suggesting to adopt, you can check those options as well
Document Introduction - Allows you to provide some background, context, or instructions regarding the document that users will be adding comments on.
Delineators
Delineators allow you to apply an organizational structure to your document. In this way, when comments are made, comment authors can easily identify which area of the document they are referring to; for example Chapter 3, Section 2.
When beginning the Delineator definition process for a Document, you are first asked to select the method from which to "Create delineators based on". The first method is to create Delineators from an "Existing Template". This means that if you have already defined delineators on a previous document, you can easily set up those same delineators on the current document.
If you have not previously defined any delineators on any documents, you will have to select the second method, "From scratch". This will reveal a form where you can define the first Delineator. You can also click "Add Additional Delineator" to reveal the form for the second Delineator, the third, and so on. Typically, delineators are added from a higher to lower order, although this is not required. For example, Delineator 1 can represent the broadest part of a document, e.g. its "Part" or "Unit", Delineator 2 can represent a more specific document part, e.g. its "Chapter", and Delineator 3 can represent its most specific part, the "Page".
When adding or editing a delineator, setting the "Required" field to "Yes" will require comment authors to specify a value for this particular delineator. Otherwise, the delineator field on the comment will still be displayed, but will be optional.
For many documents, various document components are labeled in standardized ways. For example, Appendices may be labeled using sequential alphabetic characters, e.g. A, B, C, etc.. The "Delineator Options Type" field lets you select the most appropriate labeling for your delineator. There are 8 delineator option types that can broadly be divided into three categories: Lists, Freeform, and Freeform lists.
Lists - allow comment authors to select their delineator via a drop down selection list. Many times, these lists are in sequential order. For example, when defining the delineators for a document, you can select "Roman Numeral (Uppercase) List" from the delineator option type list. This will prompt you to enter the "Number of Options" for the delineator. If you enter in 5 (for example) in this field, and click the "Set Defaults" button, a "List Options" link will appear. Clicking this link will reveal the 5 options, with default values of I, II, III, IV, and V.
Freeform - allow comment authors to specify the delineator not by selecting from a list, but by manually typing in the value. There are two options here; "Freeform Text" lets the author type in any alphanumeric characters (up to a length of 25 characters). "Freeform number" is similar, except that only whole and decimal numbers can be used (again, up to a length of 25 characters).
Freeform List - are essentially the same as Lists. They allow the document administrator to restrict the delineator options that comment authors select from. However, whereas the previous lists discussed will be pre-populated for document administrators by clicking the "Set Defaults" button, for Freeform Lists this is not the case, and document administrators must manually specify each list option.
NOTE When first configuring a Document's comment settings, you can add and remove Delineators without any issues. However, if a comment already exists where the comment author has specified a value for a given delineator, you will no longer be able to remove that delineator, or change the Delineator Option Type (e.g. from Numeric List to Freeform Text). Although you are not prevented from updating/removing specific Delineator Options, it is not recommended unless you know what you are doing, as this may result in the loss of information related to which delineator options comment authors have already selected. Data loss would occur if the comment author selected e.g. "1" for the chapter, but the document administrator renamed that delineator option from "1" to "2".
Administrative tracking info
Administrative tracking info allows document administrators to attach extra administrative information to a comment if desired. For example, document administrators could assign a unique Errata number, or other tracking identifiers.
When configuring comments on a document, the Administrative tracking information section is very similar to the Delineator section. Document administrators can define the administrative tracking info from Scratch, or they can use templates from previous documents, if those documents have Admin tracking info definitions already defined.
Any admin tracking info entries that are defined will be displayed on the Process Comment page and available for Comment Processors to input value into. A given comment's currently selected Admin tracking info will also be displayed in a read-only manner on the Comment Details page.
Admin tracking info and Delineators are very similar. Apart from their name, and where they are displayed (Comment Processing page, rather than the Comment Authoring page, respectively), all the definition options such as "Required" and Option Types are the same.
NOTE Another similarity to Delineator settings is that Admin Tracking Info can only be deleted as long as there are no comments where a comment assignee or admin/chair has already entered in values for the Admin Tracking Info you would like to delete.
Assignments: Permission to edit & process a comment
By default, Site Administrators can edit and process any comment, and Workgroup Administrators and Chairs can edit and process any comments within their workgroups. Assignments allow the Document Administrator to delegate comment editing and processing to normal workgroup members.
There are two ways of adding assignments to a comment.
- When defining the Delineators, if the first Delineator uses a List Delineator Option Type, to the right of each List Option you will see an "Assign" link. Clicking this will reveal a new text box in which you can begin to type the name or email address of your intended assignee. Simply click on the person if they show up in the search results box, and they will now be added to the Assignee list. If the comment author has selected a particular delineator option, any user who was assigned to the selected option will now be able to edit and process the comment.
- The second way to allow normal workgroup members to edit and process comments is using the processing page itself. A workgroup chair/admin can click the comment process link, and on the subsequent processing window they will see an "Assignee" section. This works like the user search described in method 1 above. Simply begin typing the name or email of the member, and select them once you see them in the search results box. Click the Save button, and the new assignee can now edit and process the comment, regardless of what delineator option is selected.
When adding assignees to a comment using these methods, you may only select from people within the currently active workgroup. This is similar to the functionality described in the NOTE from the "Related Comments" section. For example, imagine that the document was originally created on the Group A workgroup, but then shared with Group B using the "Commenting accessibility" functionality described in the next section. Let's say the site admin is on the Group B dashboard, and navigates to the comment processing page through Group B's links. If the site admin were to search for people to add as Assignees on the processing page, only people from Group B's member list would show up. However, if the site admin arrived at the processing page by starting from Group A's dashboard, they would likewise only see users from Group A's member list.
NOTE Delineator assignments are only available on the first delineator. While the "Administrative Tracking Information" section also displays "Assign" links next to List Options, these assignments are not actually functional. * Only users within the document's primary workgroup can be assigned, i.e. even if you share the document with another workgroup, only the primary workgroup's members can be assigned.
Commenting accessibility
By default, only members of the workgroup that the target document belongs to can create comments. At the bottom of the Comment Settings page, there is a section labeled "Establish who will be able to comment on the document". This section allows you to share with other workgroups access to the document itself, as well as the ability to view or add comments on the document, or even to administer (i.e. edit, process) comments.
The section presents a table where each workgroup for your organization is listed. Next to each workgroup name, there are two permission sets: one for Document Sharing, and one for Comments.
In order to give outside workgroups access to comments, these workgroups must first be able to access the document itself. In the Document Sharing columns of the table you can specify whether the target workgroup can "Read" (required at a miniumum to be able to view/add comments), "Write", or "Admin"ister documents. The "Admin" permission gives all target workgroup members full administrative rights (including deleting the document) which also lets them administer (edit and process) comments. This Document Sharing portion of the table is essentially the same as the Document Shares feature of Causeway. Any changes you make there will be reflected here, and vice versa.
The "Comments" columns of the table allow you to specify if members of the target workgroup should be able to view or create, or neither. "View" permissions will allow target workgroup members to view all comments on the document, whereas "Write" will also give them the ability to create new comments.
Creating/editing a comment
Comments can be added on a document as long as
- the Documents module, and Document Comment Tracker subModule are enabled,
- the "Comments Open" option on the "Comment Settings" page is set to "Yes", and
- the comment author belongs to the document's workgroup, or to a workgroup that has been given Comment "Write" access on the document.
If these three criteria apply, then when a user is viewing a document, they will see an "Add comment" link in the left menu. Clicking this link will present the Document Comment page, where they can provide the details of their new comment. The page is broken down into four sections:
Document Information
Comment Title - Describing the comment in a relatively short and concise fashion allows others to gather its basic meaning at a glance. Limited to 255 characters.
Delineators - These allow the comment author to specify which portion of the document their comment pertains to. For example, the comment may ask the author to select from a list of 5 "Chapters", or to type in a "Page number". Either of these fields may be required, depending on how the document administrator configured comments settings on the target document.
Comment Information Fields - While these fields are optional, they are recommended in order to provide the most context for the comment. Comment Description - General information and context related to the specified section of the document Existing Text - The current text of the portion of the document the comment author believes should be changed. Proposed Text - The comment author's suggested replacement text for the portion of the document they believe should be changed.
Supporting Documentation
This section allows comment authors to view existing, or add new supporting documentation in the form of uploaded files. Clicking the "(+) Add File" link will display a form to upload a new document. Note, this document is not part of a workgroup's normal document.
NOTE after uploading a supporting document, you will not be able to successfully "View" (clicking the magnifying class next to the item) unless the comment has been initially saved.
Related Comments
Associating a target comment with other comments is another way of providing context that may be helpful when reviewing the comment. To do this, simply click the "(+) Add Related Comment" link. The form that appears will display a table of all the comments that you have access to from the given workgroup. This could include comments from the current document, as well as comments related to other documents in the current workgroup. Simply check all the boxes next to the comments you would like to associate, and click the "Add" button.
NOTE Not all document administrators will necessarily see the same list of available comments to associate here. For example, let's say that Comment #1 is associated with the "Schema Definition" document, which belongs to the Group A workgroup. Let's also say that the document administrator from Group A gives Group B Comment write access so that B's members can add comments. When a member from Group A creates Comment #1 and clicks to add a related comment, they will see a list of all comments from all documents that belong to Group A, including the comments on the "Schema Definition" document. However, if a member from Group B creates their own comment, #2, and clicks to add a related comment, they will see any comments already added to the "Schema Definition" document, and all comments from other documents that belong to Group B. That is, they will not see comments that belong to Group A (besides that of "Schema Definition", which they were explicitly given access to). If the Group B member adds a related comment from one of these Group B documents that appears on their list, all members from Group B will be able to see the related comment on the list. However, because Group A members do not have access to Group B documents (in this example), Group A members will not see the related comments on their list.
Additional Information
Issue Priority - Allows the comment author to describe the priority of their issue. Typically, this is in terms of Low, Medium, and High priority, although these can be customized to meet your organizations needs.
Proccessing a comment
Comment processing allows document administrators or assigned persons to determine what course of action should be taken for an individual comment.
To view which comments require processing, from your worgroup's dashboard, if you click on the "Documents" link you will be taken to the workgroup's document page. In the left menu on this page you will see a "Comments" section with links for "All Comments", "My Comments", and "Actions Needed". This last link will present a list of all comments related to any documents in the workgroup, if the comments have a status that requires further admin processing. Alternatively, from the workgroup's main documents page, you can click on an individual document. The individual document page will similarly have a "Comments" section in its left menu, with a link for comments with "Actions Needed" and in parentheses it will also display how many comments on this document require further admin processing.
When you click on one of these "Actions Needed" links, the subsequent page will display a list of comments. Clicking on an individual comment will take you to that comment's "View" page. Here, if you have the correct access, you will see a link in the upper right of the page that says "Process". Clicking this link will display the "Process Comment" page.
Comment Status
A comment's process status reflects where it is at in the comment approval workflow. By default, Causeway only includes one initial status, "Not yet reviewed". However, your Causeway representative can help you create a custom workflow. Here is an example set of Comment Stauses. When describing these statues, we will use the term Comment Admins to represent Workgroup admins/chairs or designated comment assignees.
- Not yet reviewed - Technically, this is not a status; it is just the default option if nothing else has been selected.
- Pending Workgroup Approval - This acknowledges that the comment has been initially reviewed, but that comment admins still need to approve or deny the comment.
- Pending Release - This indicates that the document revisions suggested in the comment have been accepted by comment admins, but that the source document has not yet been changed to reflect the comment suggestions.
- Release - This indicates that the comment has been updated with the approved suggestions. No further processing is necessary.
- Rejected - This indicates that the comment has been rejected. No further processing is necessary.
The first three options (including "Not yet reviewed") require further action. This means that if a comment is assigned one of these statuses, they will show up in the list of comments with "Actions Needed" described above.
Additionally, because these set of status options represent a fairly linear workflow, the site administrator may wish to enable the "Strictly enforce comment status process" feature. This will make it so that a comment's status can only change from one level to the next, e.g. from "Pending Workgroup Approval" to "Pending Release". Only the site administrator can select any status they wish.
However, if your organization has a different workflow, there is some degree of customization that is possible. Reach out to your Causeway representative, and they can work with you on customizing the document comment wofkflow to your organization's needs.
Assignee
This section will display any current assignees, and will allow you to remove them, or add new assignees. As described in the "Assignments: Permission to edit & process a comment" section of this documentation, assignees added here will be able to edit and process the current comment.
Resolution
Notes regarding the resolution of the comment.
Administrative Tracking Information
Any required or optional Admin tracking info that was defined in the document's "Comment Settings" will be displayed here for the comment admin to fill out.
Additional Information
Any additional notes that the comment admin would like to add.
Previous Notes
Whenever a change is made to the processing of the comment, it will be noted in this Previous Notes section, along with the time stamp of the change, and the user/company who made the change.