6.1.9. Bug Fields
*****************

The Bugzilla API for getting details about bug fields.


6.1.9.1. Fields
===============

Get information about valid bug fields, including the lists of legal
values for each field.

**Request**

To get information about all fields:

   GET /rest/field/bug

To get information related to a single field:

   GET /rest/field/bug/(id_or_name)

+------------+-------+------------------------------------------------------------+
| name       | type  | description                                                |
|============|=======|============================================================|
| id_or_name | mixed | An integer field ID or string representing the field name. |
+------------+-------+------------------------------------------------------------+

**Response**

   {
     "fields": [
       {
         "display_name": "Priority",
         "name": "priority",
         "type": 2,
         "is_mandatory": false,
         "value_field": null,
         "values": [
           {
             "sortkey": 100,
             "sort_key": 100,
             "visibility_values": [],
             "name": "P1"
           },
           {
             "sort_key": 200,
             "name": "P2",
             "visibility_values": [],
             "sortkey": 200
           },
           {
             "sort_key": 300,
             "visibility_values": [],
             "name": "P3",
             "sortkey": 300
           },
           {
             "sort_key": 400,
             "name": "P4",
             "visibility_values": [],
             "sortkey": 400
           },
           {
             "name": "P5",
             "visibility_values": [],
             "sort_key": 500,
             "sortkey": 500
           }
         ],
         "visibility_values": [],
         "visibility_field": null,
         "is_on_bug_entry": false,
         "is_custom": false,
         "id": 13
       }
     ]
   }

"field" (array) Field objects each containing the following items:

+-------------------+---------+-------------------------------------------------------+
| name              | type    | description                                           |
|===================|=========|=======================================================|
| id                | int     | An integer ID uniquely identifying this field in this |
|                   |         | installation only.                                    |
+-------------------+---------+-------------------------------------------------------+
| type              | int     | The number of the fieldtype. The following values are |
|                   |         | defined:  * "0" Field type unknown  * "1" Single-line |
|                   |         | string field  * "2" Single value field  * "3"         |
|                   |         | Multiple value field  * "4" Multi-line text value  *  |
|                   |         | "5" Date field with time  * "6" Bug ID field  * "7"   |
|                   |         | See Also field  * "8" Keywords field  * "9" Date      |
|                   |         | field  * "10" Integer field                           |
+-------------------+---------+-------------------------------------------------------+
| is_custom         | boolean | "true" when this is a custom field, "false"           |
|                   |         | otherwise.                                            |
+-------------------+---------+-------------------------------------------------------+
| name              | string  | The internal name of this field. This is a unique     |
|                   |         | identifier for this field. If this is not a custom    |
|                   |         | field, then this name will be the same across all     |
|                   |         | Bugzilla installations.                               |
+-------------------+---------+-------------------------------------------------------+
| display_name      | string  | The name of the field, as it is shown in the user     |
|                   |         | interface.                                            |
+-------------------+---------+-------------------------------------------------------+
| is_mandatory      | boolean | "true" if the field must have a value when filing new |
|                   |         | bugs. Also, mandatory fields cannot have their value  |
|                   |         | cleared when updating bugs.                           |
+-------------------+---------+-------------------------------------------------------+
| is_on_bug_entry   | boolean | For custom fields, this is "true" if the field is     |
|                   |         | shown when you enter a new bug. For standard fields,  |
|                   |         | this is currently always "false", even if the field   |
|                   |         | shows up when entering a bug. (To know whether or not |
|                   |         | a standard field is valid on bug entry, see Create    |
|                   |         | Bug.                                                  |
+-------------------+---------+-------------------------------------------------------+
| visibility_field  | string  | The name of a field that controls the visibility of   |
|                   |         | this field in the user interface. This field only     |
|                   |         | appears in the user interface when the named field is |
|                   |         | equal to one of the values is "visibility_values".    |
|                   |         | Can be null.                                          |
+-------------------+---------+-------------------------------------------------------+
| visibility_values | array   | This field is only shown when "visibility_field"      |
|                   |         | matches one of these string values. When              |
|                   |         | "visibility_field" is null, then this is an empty     |
|                   |         | array.                                                |
+-------------------+---------+-------------------------------------------------------+
| value_field       | string  | The name of the field that controls whether or not    |
|                   |         | particular values of the field are shown in the user  |
|                   |         | interface. Can be null.                               |
+-------------------+---------+-------------------------------------------------------+
| values            | array   | Objects representing the legal values for select-type |
|                   |         | (drop-down and multiple-selection) fields. This is    |
|                   |         | also populated for the "component", "version",        |
|                   |         | "target_milestone", and "keywords" fields, but not    |
|                   |         | for the "product" field (you must use                 |
|                   |         | "get_accessible_products" for that). For fields that  |
|                   |         | aren't select-type fields, this will simply be an     |
|                   |         | empty array. Each object contains the items described |
|                   |         | in the Value object below.                            |
+-------------------+---------+-------------------------------------------------------+

Value object:

+-------------------+---------+-------------------------------------------------------+
| name              | type    | description                                           |
|===================|=========|=======================================================|
| name              | string  | The actual value--this is what you would specify for  |
|                   |         | this field in "create", etc.                          |
+-------------------+---------+-------------------------------------------------------+
| sort_key          | int     | Values, when displayed in a list, are sorted first by |
|                   |         | this integer and then secondly by their name.         |
+-------------------+---------+-------------------------------------------------------+
| visibility_values | array   | If "value_field" is defined for this field, then this |
|                   |         | value is only shown if the "value_field" is set to    |
|                   |         | one of the values listed in this array. Note that for |
|                   |         | per-product fields, "value_field" is set to "product" |
|                   |         | and "visibility_values" will reflect which product(s) |
|                   |         | this value appears in.                                |
+-------------------+---------+-------------------------------------------------------+
| is_active         | boolean | This value is defined only for certain product-       |
|                   |         | specific fields such as version, target_milestone or  |
|                   |         | component. When true, the value is active; otherwise  |
|                   |         | the value is not active.                              |
+-------------------+---------+-------------------------------------------------------+
| description       | string  | The description of the value. This item is only       |
|                   |         | included for the "keywords" field.                    |
+-------------------+---------+-------------------------------------------------------+
| is_open           | boolean | For "bug_status" values, determines whether this      |
|                   |         | status specifies that the bug is "open" ("true") or   |
|                   |         | "closed" ("false"). This item is only included for    |
|                   |         | the "bug_status" field.                               |
+-------------------+---------+-------------------------------------------------------+
| can_change_to     | array   | For "bug_status" values, this is an array of objects  |
|                   |         | that determine which statuses you can transition to   |
|                   |         | from this status. (This item is only included for the |
|                   |         | "bug_status" field.)  Each object contains the        |
|                   |         | following items:  * name: (string) The name of the    |
|                   |         | new status  * comment_required: (boolean) "true" if a |
|                   |         | comment is required when you change a bug into this   |
|                   |         | status using this transition.                         |
+-------------------+---------+-------------------------------------------------------+


6.1.9.2. Legal Values
=====================

**DEPRECATED** Use ''Fields'' instead.

Tells you what values are allowed for a particular field.

**Request**

To get information on the values for a field based on field name:

   GET /rest/field/bug/(field)/values

To get information based on field name and a specific product:

   GET /rest/field/bug/(field)/(product_id)/values

+------------+--------+---------------------------------------------------------------+
| name       | type   | description                                                   |
|============|========|===============================================================|
| field      | string | The name of the field you want information about. This should |
|            |        | be the same as the name you would use in Create Bug, below.   |
+------------+--------+---------------------------------------------------------------+
| product_id | int    | If you're picking a product-specific field, you have to       |
|            |        | specify the ID of the product you want the values for.        |
+------------+--------+---------------------------------------------------------------+

**Resppnse**

   {
     "values": [
       "P1",
       "P2",
       "P3",
       "P4",
       "P5"
     ]
   }

+------------+--------+---------------------------------------------------------------+
| name       | type   | description                                                   |
|============|========|===============================================================|
| values     | array  | The legal values for this field. The values will be sorted as |
|            |        | they normally would be in Bugzilla.                           |
+------------+--------+---------------------------------------------------------------+

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

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