Custom Fields

Applies to Collaborator 11.5, last modified on December 21, 2021

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.

Review custom fields

Click the image to enlarge it.

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

Defect custom fields

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

Checklist custom fields

Click the image to enlarge it.

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

Participant custom fields

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.

Custom fields of the String (Single-line) type

String (multi-line)

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

Custom fields of the String (Multi-line) type

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:

Custom fields of the Drop-down List type

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:

Custom fields of the Drop-down Series type

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:

Custom fields of the Multi-select List type

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

Create Custom Field

  1. Log in to Collaborator as an administrator.

  2. Go to ADMIN > Review Templates > Custom Fields. This page displays existing custom fields.

  3. Switch to the tab that matches the type of the field you are going to create.

  4. 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:

    Create a new custom field

    Click the image to enlarge it.

    Important: The field type you set when creating a custom field cannot be changed later.

  5. Use the Move Up and Move Down buttons to position the new field among other custom fields:

    The Move Up and Move Down buttons
  6. 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:

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

    Edit a review template

    Click the image to enlarge it.

  2. 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:

    Select custom fields in a template
  3. 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:

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

    Edit a checklist

    Click the image to enlarge it.

  2. 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:

  3. 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:

The Move Up and Move Down buttons

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:

Delete a custom 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

Available for the participant custom fields only. 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).

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.

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.

Property Description
Selectable Items

The list of items to be displayed in the drop-down list.

Display Ordering

The order of items in the list: ascending, descending, or none (which means the items will be displayed in the order of appearance in the Selectable Items list).

Default Value

The value that the field will have by default. Should match one of the items in the Selectable Items list.

Property Description
Selectable Items

The list of items of the of the drop-down lists.

Each item in the list includes substrings separated by vertical pipe characters (“|”). The substrings correspond to items of different combo boxes in the “drop-down series” field. For example:

DesktopClient|New controls|ver. A

DesktopClient|New controls|ver. B

WebClient|Controls|0.3a

WebClient|Controls|0.4

WebClient|Wizards|Create

Items in the list must have the same number of substrings, and this number should match the number of substring in the Title property.

Display Ordering

The order of items in the list: ascending, descending, or none (which means the items will be displayed in the order of their appearance in Selectable Items).

Property Description
Selectable Items

The list of items to be displayed in the list.

Display Ordering

The order of items in the list: ascending, descending, or none (which means the items will be displayed in the order of appearance in the Selectable Items list).

Notes

Predefined custom fields

Some custom fields are available out-of-the-box:

  • Overview (review custom field)
  • Severity (defect custom field)
  • Type (defect custom field)

Collaborator does not impose any limitations on these fields. You can edit their properties as if they were created by you.

Custom fields with date and time values

Collaborator does not offer special fields for date and time values. To store these values, you can use custom fields of the String (single-line) type and use the following regular expressions to validate user input:

  • For dates, you can use a regular expression like this:

    (?:19|20)\d\d-(?:0[1-9]|1[012])-(?:0[1-9]|[12][0-9]|3[01])

    It lets users enter a data in the 20th or 21st century, and yes, it accepts 31 days each month.

  • For time values, you can use the following regular expression:

    (?:[01][0-9]|2[0-3]):[0-5][0-9]

    It validates time values against a 24-hour format.

You can combine these two regular expressions to accept both date and time in the same field.

Set the field description to inform users about the expected format, so that users they do not have to parse regular expressions to know what to enter.

Changing custom field values

Custom fields are used in reviews. Changing field properties might cause reviews to contain invalid data. To prevent this, Collaborator follows these rules:

  • Collaborator does not include new custom fields in reviews automatically. First, you need to add them to review templates. This operation disables the existing review template and creates a new template in place of it. So, the changes will be visible in new reviews that are based on the updated template.

    If you want the changes to be applied to existing reviews, you will have to reapply the new template to them. Existing values of custom fields will be retained upon changing review template if the custom field exists in both templates. The new fields will contain default values, or will show a dash or N/A to indicate that the value was not given.

  • If you change properties of a field that is already present in a template, then —

    • If the change you made does not affect field values (for example, you renamed a field or changed its description), then users will see the changes next time they open the review in the review screen.

    • If the changes made existing values invalid (for instance, you decreased the maximum length, changed the validating regular expression or removed some items from a drop-down list), the existing field values will remain unchanged. However, users will have to specify new valid values when they are editing a review.

  • Custom fields that you delete in ADMIN settings will be removed from the UI automatically. Now update of review templates is needed.

Custom fields in external reporting systems

To make custom fields available for external reporting systems like Excel, Access, Crystal Reports, or Business Objects, Collaborator offers two view objects: reviewcustom and defectcustom.

The reviewcustom view does not includes custom fields of the Multi-select list type.

If a review does not use some custom fields (these fields are disabled in the corresponding review template), then these fields have the NULL value in reports for these reviews.

We recommend to refer to custom fields in reports by their names rather than by their order.

Why are my custom fields absent from reviews?

New custom fields are not added to reviews automatically. You need to add them to review templates you are using.

Note that this will disable the review template and will create a new template in place of it. Your new custom fields will be visible in new reviews based on the updated template, and will not be visible in existing reviews. If you want to see the new field in an existing review, you will have to reapply the new template to that review.

Using participant custom fields

  • Participant custom fields cannot be visible only in the Planning phase. Otherwise, participants will not be able to specify field values.

  • If a required participant custom field is visible only on the Inspection phase, users cannot “finish” this phase without specifying their values for the fields.

  • Users are allowed to edit participant custom fields when the review is in the Completed phase without reopening the review. This gives them a possibility to answer post-review survey questions.

  • Follow these links to get examples of reporting on participant custom fields:

See Also

Review Templates

Highlight search results