4.6. Custom Fields
******************

Custom Fields are fields defined by the administrator, in addition to
those which come with Bugzilla by default. Custom Fields are treated
like any other field—they can be set in bugs and used for search
queries.

Administrators should keep in mind that adding too many fields can
make the user interface more complicated and harder to use. Custom
Fields should be added only when necessary and with careful
consideration.

Note:

  Before adding a Custom Field, make sure that Bugzilla cannot already
  do the desired behavior. Many Bugzilla options are not enabled by
  default, and many times Administrators find that simply enabling
  certain options that already exist is sufficient.

Administrators can manage Custom Fields using the "Custom Fields" link
on the Administration page. The Custom Fields administration page
displays a list of Custom Fields, if any exist, and a link to "Add a
new custom field".


4.6.1. Adding Custom Fields
===========================

To add a new Custom Field, click the "Add a new custom field" link.
This page displays several options for the new field, described below.

The following attributes must be set for each new custom field:

* *Name:* The name of the field in the database, used internally. This
  name MUST begin with "cf_" to prevent confusion with standard
  fields. If this string is omitted, it will be automatically added to
  the name entered.

* *Description:* A brief string used as the label for this Custom
  Field. That is the string that users will see, and it should be
  short and explicit.

* *Type:* The type of field to create. There are several types
  available:

  Bug ID:
     A field where you can enter the ID of another bug from the same
     Bugzilla installation. To point to a bug in a remote
     installation, use the See Also field instead.

  Large Text Box:
     A multiple line box for entering free text.

  Free Text:
     A single line box for entering free text.

  Multiple-Selection Box:
     A list box where multiple options can be selected. After creating
     this field, it must be edited to add the selection options. See
     Viewing/Editing Legal Values for information about editing legal
     values.

  Drop Down:
     A list box where only one option can be selected. After creating
     this field, it must be edited to add the selection options. See
     Viewing/Editing Legal Values for information about editing legal
     values.

  Date/Time:
     A date field. This field appears with a calendar widget for
     choosing the date.

* *Sortkey:* Integer that determines in which order Custom Fields are
  displayed in the User Interface, especially when viewing a bug.
  Fields with lower values are displayed first.

* *Reverse Relationship Description:* When the custom field is of type
  "Bug ID", you can enter text here which will be used as label in the
  referenced bug to list bugs which point to it. This gives you the
  ability to have a mutual relationship between two bugs.

* *Can be set on bug creation:* Boolean that determines whether this
  field can be set on bug creation. If not selected, then a bug must
  be created before this field can be set. See Filing a Bug for
  information about filing bugs.

* *Displayed in bugmail for new bugs:* Boolean that determines whether
  the value set on this field should appear in bugmail when the bug is
  filed. This attribute has no effect if the field cannot be set on
  bug creation.

* *Is obsolete:* Boolean that determines whether this field should be
  displayed at all. Obsolete Custom Fields are hidden.

* *Is mandatory:* Boolean that determines whether this field must be
  set. For single and multi-select fields, this means that a (non-
  default) value must be selected; for text and date fields, some text
  must be entered.

* *Field only appears when:* A custom field can be made visible when
  some criteria is met. For instance, when the bug belongs to one or
  more products, or when the bug is of some given severity. If left
  empty, then the custom field will always be visible, in all bugs.

* *Field that controls the values that appear in this field:* When the
  custom field is of type "Drop Down" or "Multiple-Selection Box", you
  can restrict the availability of the values of the custom field
  based on the value of another field. This criteria is independent of
  the criteria used in the "Field only appears when" setting. For
  instance, you may decide that some given value "valueY" is only
  available when the bug status is RESOLVED while the value "valueX"
  should always be listed. Once you have selected the field that
  should control the availability of the values of this custom field,
  you can edit values of this custom field to set the criteria; see
  Viewing/Editing Legal Values.


4.6.2. Editing Custom Fields
============================

As soon as a Custom Field is created, its name and type cannot be
changed. If this field is a drop-down menu, its legal values can be
set as described in Viewing/Editing Legal Values. All other attributes
can be edited as described above.


4.6.3. Deleting Custom Fields
=============================

Only custom fields that are marked as obsolete, and that have never
been used, can be deleted completely (else the integrity of the bug
history would be compromised). For custom fields marked as obsolete, a
"Delete" link will appear in the "Action" column. If the custom field
has been used in the past, the deletion will be rejected. Marking the
field as obsolete, however, is sufficient to hide it from the user
interface entirely.

======================================================================

This documentation undoubtedly has bugs; if you find some, please file
them here.
