Custom Fields

Code Collaborator supports custom fields for reviews and defects. 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 and Defect Custom Fields subsections of the administrative interface.

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?

Code Collaborator 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.

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 Code Collaborator 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 Code Collaborator 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 Code Collaborator 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.

The search engine is aware of all custom fields and will scan data in custom fields you would expect.

When you view either the Review Custom Field subsection or the Defect Custom Field subsection, a list of already customized fields will appear at the top of the list:

Code Collaborator will come with default custom fields, an "Overview" review custom field and "Severity" and "Type" 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.

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.

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.