|
CodeCollaborator supports custom fields for reviews and defects. A special type of review custom field is also supported: participant custom fields. Participant custom fields apply to a review, but allow each user to specify their own value for the field. Custom fields may be any of four types: Single-line String, Multi-line String, Drop-down List, and Multi-Selection. Although these fields show up in different places in the user interface, the administrative interface for configuring these fields is identical. It shows up in the Review Custom Fields, Participant Custom Fields, and Defect Custom Fields subsections of the administrative interface.
Consequences of Changing Custom Fields
The conscientious administrator will realize that it could be disastrous to change custom field settings while a review is taking place. If someone is filling out custom fields and simultaneously a new one is added, what happens? If a review is going on and a new field is added or a field is removed, what happens? If you view an old review with defects and you have since added, removed, or changed defect custom fields, what happens to the defect data?
CodeCollaborator is smart about handling dynamically changing custom fields even while reviews are in progress or already complete. If fields are added after the fact, reviews and defects will show a dash or "N/A" to indicate that this value wasn't given. Any new creations or edits of existing creations will force the user to fill in values for the new fields. If fields are deleted, existing values are simply ignored. If there are changes to field titles, descriptions, or other non-value items, existing values are unaffected. If the values in drop-down lists change such that a value given previously no longer exists, the previous value will still hold for that field, although if the user then edits the field he will be forced to pick a new valid value.
Fields that are deleted in the administrative interface are removed from the user's interface immediately. The original data is still preserved in the database for reporting but is no longer available to the user in the various client interfaces.
Custom Fields and Reports
The built-in reports do not reference custom fields. There are, however, consequences of custom fields on external reporting systems such as Excel, Access, Crystal Reports, and Business Objects.
The custom field system inside the database is fairly involved and not intuitive. Therefore for your convenience CodeCollaborator maintains several database VIEW objects that cause custom field data to appear as if it was a standard table in the database. The two VIEW objects are reviewcustom and defectcustom. In each case one column refers to the unique ID of the associated object, then CodeCollaborator generates columns for each of the other custom fields and fills in the values for each, using NULL if the value isn't specified.
Warning: It is not uncommon to see NULL values in custom field views. If a review is in a workflow that doesn't support certain fields, they will be NULL. If a review was created before a certain custom field existed, the value will be NULL.
Warning: If you change custom fields CodeCollaborator will immediately change the VIEW definitions in the database. This can break existing queries and reports unless those queries have been designed to be immune to such changes. For example, you should refer to columns by name and not by their order.
Custom Fields and Searching
The search engine is aware of all custom fields and will scan data in custom fields you would expect.
Custom Field Configuration
When you view either the Review Custom Fields, Participant Custom Fields, or Defect Custom Fields subsection, a list of already customized fields will appear at the top of the list:
CodeCollaborator will come with default custom fields, an "Overview" review custom field and "Severity" and "Type" defect custom fields. They will appear collapsed as exemplified by the Severity custom field. Click on the blue triangle to the left of the custom field title, and the section will expand so that you may view/edit the settings. Expanded sections will look like the Type custom field.
Each existing custom field comes in a box with a toolbar of commands to the right of the title:
The Move Up / Move Down commands let you change the order of the fields as it will appear to users. Delete removes the custom field from the system forever, so use with caution.
At the bottom of the custom fields list, there will be a customizable form where you will be able to create a new custom field:
A custom field's data type cannot be changed once it is created; everything else about the field can be modified at any time. Types are one of:
| • |
Single-Line Text. A single line of text, scrolling horizontally if needed for length. Maximum length is 255 characters. Various validation options. |
| • |
Multi-Line Text. Multiple lines of text, scrolling horizontally and vertically as needed. Maximum length is database-dependant, but always at least 8192 characters, and typically more like many millions of characters. |
| • |
Drop-Down List. A drop-down list of pre-defined choices. Exactly one selection is required. |
| • |
Multi-Select List. A drop-down list of pre-defined choices. User may select zero, one, or multiple values. |
The Title of a field is displayed to the user as a prompt, much like "Type" and "Title" are shown in the screenshot above. The Description of a field is shown as help-text below the field, prompting the user as to the intent of the field.
All textual fields allow for a minimum and maximum length. Minimums can be zero if it's OK for the user to leave the field blank.
All textual fields also allow for an optional Java-style regular expression validator. If given, the content of the field must match the regular expression exactly. It is important to note that if you use a Validator, that field will be automatically required. If you do not want the field to be required, you must use a Validator that will allow the field to accept empty values AND set the Minimum Length to 0.
The Drop-Down List type requires a list of options. These are in plain text. To change the order of items, just copy/paste the items in the list. If you change just capitalization, the item is altered in-place; if you change an item more than just in capitalization the system considers the previous item to be deleted and the current item to be added.
Warning: If you think you're renaming a drop-down item, you're not! The system considers "renaming" as deleting the old item and creating a new item. Rearranging items without renaming works as expected, as does changing just capitalization in an item.
This confusing situation will be remedied in a future version.
Why Aren't My Custom Fields Showing Up in My Reviews?
Once you've created a new custom field, you will not see them automatically as options in your reviews. Custom fields will be automatically be configured as "Hidden" under all templates. To show custom fields, you must configure them to "Show" under the Workflow Configuration.
You can also define custom fields to be visible only during certain phases of the review. This can be useful for storing fields only used by scripts or triggers. This is changed via the "Visible Phase" drop-down.
Notes About Participant Custom Fields
Participant custom fields have some unique behaviors. First, they cannot be visible only in the planning phase, as this would not give the participants an opportunity to specify their values for the fields. Second, if a required participant custom field is visible only within the Inspection phase, users may not "Finish" the inspection phase without specifying their values for the fields. Finally, participant custom fields may be edited while the review is in the complete phase without reopening the review. This is to support post-review survey questions.
For examples of reporting on Participant Custom Fields, see:
|