About

Custom fields allow adding arbitrary information fields to reviews. They help to fit Collaborator reviews into your workflow. Currently Collaborator supports custom fields for the following areas: reviews, defects, checklists and participants.

Review custom fields allow to specify and view any arbitrary information for the general section of the review.

Click the image to enlarge it.

Defect custom fields allow to specify and view any arbitrary information for defects.

Checklist custom fields allow to specify and view any arbitrary information for checklist items.

Click the image to enlarge it.

Participant custom fields allow each review participant to specify and view any arbitrary information about the review:

Click the image to enlarge it.

Although these fields show up in different places in the user interface, the administrative interface for configuring these fields is identical. Administrators create and edit custom fields of all these types in the Review Templates > Custom Fields settings. See below for details.

Custom field values are included in the search and in reports.

Requirements

Custom fields are not supported in Collaborator Community. Collaborator Team offers limited support for custom fields, and Collaborator Enterprise fully supports them.
For a complete list of differences between Collaborator editions, see Collaborator Editions.
To create and edit custom fields, you need administrator permissions in Collaborator.

Custom Field Types

Collaborator supports the following types of the custom fields:

String (single-line)

These are text fields displayed as usual text boxes. Can store up to 255 characters. Supports various validation options. Can be used for creating date/time edit boxes and other controls.

String (multi-line)

Fields that support long texts. Displayed as multi-line edit boxes with vertical and horizontal scrollbars (if needed).

The maximum allowed text size depends on the database server, where Collaborator is installed. The lower bound is 8192 characters. It can be more and reach up to several thousands of characters.

Drop-down list

Fields that let users select one item from a pre-defined list of items. Displayed as combo boxes:

These fields support the search-as-you-type functionality: when users are typing, Collaborator shows only those items in the drop-down list that contains the entered text.

Drop-down series

Fields in which you select a value in a sequence of combo boxes:

To create a field of this type:

In the Title property, you specify the names of combo boxes separated by vertical pipe characters (“|”):

Product Area|Component|Version
In the Selectable Items property, you specify items of these combo boxes. Each line in the Selectable Items list contains the values separated by vertical pipe characters (“|”). The number of these values should match the number of values in the Title property:

Reports|Summary|0.0.1

Reports|Summary|0.0.2

Reports|Customer list|Alice var

Reports|Customer list|John var

Login screen|Controls|0.0.1a

Login screen|Controls|BS

When you select an item in the first combo box, Collaborator automatically filters the items of the second combo box keeping only those that match the selection. When you select a value in the second combo box, the third combo boxes will have only items that match the selection, and so on.

When creating reports, the field values you specify in filters should include pipe characters, for example, “Login screen|Controls|0.0.1a”.

Multi-select list

These fields are displayed as list boxes that support multiple choices:

Use Ctrl+click or Shift+click for multi-selection.

Create Custom Field

Log in to Collaborator as an administrator.
Go to ADMIN > Review Templates > Custom Fields. This page displays existing custom fields.
Switch to the tab that matches the type of the field you are going to create.
Find the Create new Custom Field section at the bottom of the tab, select the field type from the Type drop-down list, set other properties and click Save to apply the changes:

Click the image to enlarge it.

Important: The field type you set when creating a custom field cannot be changed later.
Use the Move Up and Move Down buttons to position the new field among other custom fields:
After you changed the parameters, you need to enable the custom fields in a review template (for review, defect and participant custom fields) or in a checklist (for checklist custom fields). See below.

Enable Custom Fields in Review Templates

To use review, defect or participant custom fields in reviews, you need to add them to review templates you use. After doing this, custom fields will be available in new reviews based on these templates.

To add a field to a template:

Go to ADMIN > Review Templates. On the Enabled Review Templates tab, find the desired template and click Edit:

Click the image to enlarge it.
Scroll the template settings screen down to the Review Custom Fields, Participant Custom Fields or Defect Custom Fields section, and then select the desired custom fields to be available in templates:
Click Save to apply the changes, or click Revert to cancel them.

After you modified a template, Collaborator does not update all the reviews based on this template. It keeps existing reviews unchanged, and marks the template as disabled in them. It will apply the changes to new reviews that use the template.

To use custom fields in existing reviews, you need to re-apply the template to these reviews. See Review Templates.

Enable Custom Fields in Checklists

To use checklist custom fields in reviews, you need to add them to the checklists you use. After doing this, custom fields will be available in new reviews that use the desired checklists.

To add a field to a checklist:

Go to ADMIN > Review Templates > Checklists. Find the desired checklist, if the checklist is active, then disable it, and then click Edit:

Click the image to enlarge it.
Scroll the checklist settings screen down to the Checklist Custom Fields section, and then select the desired custom fields to be available in the checklist:
Click Save to apply the changes, or click Revert to cancel them.

Change Order of Custom Fields

In the Custom Fields page, switch to the tab that matches the type of your custom field, and use the Move Up and Move Down buttons of the field to change its position:

There is no need to update review templates after this. The changes will be applied automatically.

Delete Custom Field

In the Custom Fields page, switch to the tab that matches the type of your custom field, and click Delete for the field:

There is no need to update review templates. Collaborator will remove the field from them automatically. Also, it will remove the field from all the reviews that use that field. The field values in these reviews will be lost.

Custom Field Properties

Common

Property Description

Type

The type of the custom field. See above.

Title

The name of the custom field, as it will be displayed to users.

Notes:

To avoid user confusion, select descriptive names. Avoid using the names that are similar to some other existing field names.
For custom fields of the drop-down series type, the Title property contains substrings separates by vertical pipe characters (“|”).
If you host Collaborator on an Oracle server, note that custom field names which differ only by double-quote characters (") may break Oracle reporting views. See also Known Issues.

Description

Text of the tip that is shown below the field name in the UI.

Visible Phase

Specifies review phases, on what the field will be visible for users. To make the field visible from some phase, select that phase from the drop-down list and then select the Apply to All Subphases check box.

Tip: Never Visible means the field will not be displayed on any phase. These fields are useful for storing values provided by scripts and triggers.

For information on using participant custom fields on the Planning, Inspection and Completed phases, see below.

Apply to All Subphases

See above.

Due By Phase

Specifies the review phase on which the field must be populated. The possible values include —

Value	Description
None	The field is not required on any phase and may remain blank.
Planning	The field must be populated on the Planning phase.
Annotating	The field must be filled-in on the Annotating phase. Since that phase is optional, the field may remain blank, if a review has never been in that phase.
Rework	The field must be filled-in on the Rework phase. Since that phase is optional, the field may remain blank if a review has never been in that phase.
Inspection	The field must be populated on the Inspection phase, no matter whether a review goes then to the Rework or to the Completed phase.
Completed	The field must be filled-in on the Inspection phase only if a review goes to the Completed phase. If a review goes to the Rework phase, the field may remain blank.
Any	The field must be populated when a review is moving from any phase to any other phase.

To avoid situations when a required field becomes invisible, make sure that —

Visible Phase is the same phase as Due by Phase,

— or —
Visible Phase is an earlier phase relative to Due by Phase, and
Apply to All Subphases is selected.

If Due by Phase is Completed, Visible Phase must be some earlier phase.

Required custom fields of the participant type are only required for participants that are expected to change the review on some phase: for example, on the Planning phase these are authors, on the Annotating phase – all participants, on the Inspection phase – reviewers, and so on.

Allowed to Modify

Defines who can modify the field value: the participant who is supposed to do this, any participant, moderator and so on. Default is Assigned participant.

Other properties are specific to the field type (see below).

Single-line text

Property	Description
Minimum Length	Minimal allowed length of the text in the field. To let users have empty values in a field, set this property to `0`.
Maximum Length	Maximum number of characters a field can contain. The maximum allowed value here is `255`. The default value is also `255`.
Validator	A Java-style regular expression that will be used to validate the contents of a field. The field value should match the specified regular expression.

Multi-line text

Property	Description
Minimum Length	Minimal allowed length of the text in the field. To let users have empty values in a field, set this property to `0`.
Maximum Length	Maximum allowed number of characters in the field. This value depends on the database server, where Collaborator is installed. In many cases, the lower possible bound is 8192, but it can be higher and can reach thousands of characters.