diff options
Diffstat (limited to 'docs/en/rst/api/core/v1/field.rst')
| -rw-r--r-- | docs/en/rst/api/core/v1/field.rst | 240 |
1 files changed, 240 insertions, 0 deletions
diff --git a/docs/en/rst/api/core/v1/field.rst b/docs/en/rst/api/core/v1/field.rst new file mode 100644 index 000000000..d97aa3050 --- /dev/null +++ b/docs/en/rst/api/core/v1/field.rst @@ -0,0 +1,240 @@ +Bug Fields +========== + +The Bugzilla API for getting details about bug fields. + +.. _rest_fields: + +Fields +------ + +Get information about valid bug fields, including the lists of legal values +for each field. + +**Request** + +To get information about all fields: + +.. code-block:: text + + GET /rest/field/bug + +To get information related to a single field: + +.. code-block:: text + + 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** + +.. code-block:: js + + { + "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 + :ref:`rest_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. +================= ======= ===================================================== + +.. _rest_legal_values: + +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: + +.. code-block:: text + + GET /rest/field/bug/(field)/values + +To get information based on field name and a specific product: + +.. code-block:: text + + 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 + :ref:`rest_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** + +.. code-block:: js + + { + "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. +========== ====== ============================================================= |