
Flag Types
**********

This part of the Bugzilla API allows you to get and create bug and
attachment flags.


Get Flag Type
=============

Get information about valid flag types that can be set for bugs and
attachments.

**Request**

To get information about all flag types for a product:

   GET /rest/flag_type/(product)

To get information about flag_types for a product and component:

   GET /rest/flag_type/(product)/(component)

   {
     "bug": [
       {
         "is_multiplicable": false,
         "is_requesteeble": false,
         "values": [
           "X",
           "?",
           "+",
           "-"
         ],
         "id": 11,
         "type": "bug",
         "is_active": true,
         "description": "Blocks the next release",
         "name": "blocker"
       },
       {
         "is_requesteeble": false,
         "is_multiplicable": false,
         "is_active": true,
         "description": "Regression found?",
         "name": "regression",
         "id": 10,
         "type": "bug",
         "values": [
           "X",
           "?",
           "+",
           "-"
         ]
       },
     ],
     "attachment": [
       {
         "is_requesteeble": true,
         "is_multiplicable": true,
         "name": "review",
         "is_active": true,
         "description": "Review the patch for correctness and applicability to the problem.",
         "type": "attachment",
         "id": 1,
         "values": [
           "X",
           "?",
           "+",
           "-"
         ]
       },
       {
         "name": "approval",
         "description": "Approve the patch for check-in to the tree.",
         "is_active": true,
         "values": [
           "X",
           "?",
           "+",
           "-"
         ],
         "type": "attachment",
         "id": 3,
         "is_multiplicable": false,
         "is_requesteeble": false
       }
     ]
   }

You must pass a product name and an optional component name. If the
product or component names contains a "/" character, up will need to
url encode it.

+-------------+--------+--------------------------------------------------------------+
| name        | type   | description                                                  |
+=============+========+==============================================================+
| **product** | string | The name of a valid product.                                 |
+-------------+--------+--------------------------------------------------------------+
| component   | string | An optional valid component name associated with the         |
+-------------+--------+--------------------------------------------------------------+

**Response**

An object containing two items, "bug" and "attachment". Each value is
an array of objects, containing the following items:

+------------------+---------+--------------------------------------------------------+
| name             | type    | description                                            |
+==================+=========+========================================================+
| id               | int     | An integer ID uniquely identifying this flag type.     |
+------------------+---------+--------------------------------------------------------+
| name             | string  | The name for the flag type.                            |
+------------------+---------+--------------------------------------------------------+
| type             | string  | The target of the flag type which is either "bug" or   |
+------------------+---------+--------------------------------------------------------+
| description      | string  | The description of the flag type.                      |
+------------------+---------+--------------------------------------------------------+
| values           | array   | String values that the user can set on the flag type.  |
+------------------+---------+--------------------------------------------------------+
| is_requesteeble  | boolean | Users can ask specific other users to set flags of     |
+------------------+---------+--------------------------------------------------------+
| is_multiplicable | boolean | Multiple flags of this type can be set for the same    |
+------------------+---------+--------------------------------------------------------+


Create Flag Type
================

Create a new flag type. You must be authenticated and be in the
*editcomponents* group to perform this action.

**Request**

   POST /rest/flag_type

   {
     "name" : "feedback",
     "description" : "This attachment needs feedback",
     "inclusions" : [ "WorldControl "],
     "target_type" : "attachment"
   }

Some params must be set, or an error will be thrown. The required
params are marked in **bold**.

+-----------------------------+---------+---------------------------------------------+
| name                        | type    | description                                 |
+=============================+=========+=============================================+
| **name**                    | string  | The name of the new flag type.              |
+-----------------------------+---------+---------------------------------------------+
| **description**             | string  | A description for the flag type.            |
+-----------------------------+---------+---------------------------------------------+
| target_type                 | string  | The new flag is either for a "bug" or an    |
+-----------------------------+---------+---------------------------------------------+
| inclusions                  | array   | An array of strings or an object containing |
+-----------------------------+---------+---------------------------------------------+
| exclusions                  | array   | An array of strings or an object containing |
+-----------------------------+---------+---------------------------------------------+
| sortkey                     | int     | A number between 1 and 32767 by which this  |
+-----------------------------+---------+---------------------------------------------+
| is_active                   | boolean | Flag of this type appear in the UI and can  |
+-----------------------------+---------+---------------------------------------------+
| is_requestable              | boolean | Users can ask for flags of this type to be  |
+-----------------------------+---------+---------------------------------------------+
| cc_list                     | array   | If the flag type is requestable, who should |
+-----------------------------+---------+---------------------------------------------+
| is_specifically_requestable | boolean | Users can ask specific other users to set   |
+-----------------------------+---------+---------------------------------------------+
| is_multiplicable            | boolean | Multiple flags of this type can be set on   |
+-----------------------------+---------+---------------------------------------------+
| grant_group                 | string  | The group allowed to grant/deny flags of    |
+-----------------------------+---------+---------------------------------------------+
| request_group               | string  | If flags of this type are requestable, the  |
+-----------------------------+---------+---------------------------------------------+

An example for "inclusions" and/or "exclusions":

   [
     "FooProduct"
   ]

   {
     "BarProduct" : [ "C1", "C3" ],
     "BazProduct" : [ "C7" ]
   }

This flag will be added to **all** components of "FooProduct",
components C1 and C3 of "BarProduct", and C7 of "BazProduct".

**Response**

   {
     "id": 13
   }

+---------+------+------------------------------------------------+
| name    | type | description                                    |
+=========+======+================================================+
| flag_id | int  | ID of the new FlagType object is returned.     |
+---------+------+------------------------------------------------+


Update Flag Type
================

This allows you to update a flag type in Bugzilla. You must be
authenticated and be in the *editcomponents* group to perform this
action.

**Request**

   PUT /rest/flag_type/(id_or_name)

   {
     "ids" : [13],
     "name" : "feedback-new",
     "is_requestable" : false
   }

You can edit a single flag type by passing the ID or name of the flag
type in the URL. To edit more than one flag type, you can specify
addition IDs or flag type names using the "ids" or "names" parameters
respectively.

One of the below must be specified.

+----------------+-------+------------------------------------------------------------+
| name           | type  | description                                                |
+================+=======+============================================================+
| **id_or_name** | mixed | Integer flag type ID or name.                              |
+----------------+-------+------------------------------------------------------------+
| **ids**        | array | Numeric IDs of the flag types that you wish to update.     |
+----------------+-------+------------------------------------------------------------+
| **names**      | array | Names of the flag types that you wish to update. If many   |
+----------------+-------+------------------------------------------------------------+

The following parameters specify the new values you want to set for
the flag types you are updating.

+-----------------------------+---------+---------------------------------------------+
| name                        | type    | description                                 |
+=============================+=========+=============================================+
| name                        | string  | A short name identifying this type.         |
+-----------------------------+---------+---------------------------------------------+
| description                 | string  | A comprehensive description of this type.   |
+-----------------------------+---------+---------------------------------------------+
| inclusions                  | array   | An array of strings or an object containing |
+-----------------------------+---------+---------------------------------------------+
| exclusions                  | array   | An array of strings or an object containing |
+-----------------------------+---------+---------------------------------------------+
| sortkey                     | int     | A number between 1 and 32767 by which this  |
+-----------------------------+---------+---------------------------------------------+
| is_active                   | boolean | Flag of this type appear in the UI and can  |
+-----------------------------+---------+---------------------------------------------+
| is_requestable              | boolean | Users can ask for flags of this type to be  |
+-----------------------------+---------+---------------------------------------------+
| cc_list                     | array   | If the flag type is requestable, who should |
+-----------------------------+---------+---------------------------------------------+
| is_specifically_requestable | boolean | Users can ask specific other users to set   |
+-----------------------------+---------+---------------------------------------------+
| is_multiplicable            | boolean | Multiple flags of this type can be set on   |
+-----------------------------+---------+---------------------------------------------+
| grant_group                 | string  | The group allowed to grant/deny flags of    |
+-----------------------------+---------+---------------------------------------------+
| request_group               | string  | If flags of this type are requestable, the  |
+-----------------------------+---------+---------------------------------------------+

An example for "inclusions" and/or "exclusions":

   [
     "FooProduct",
   ]

   {
     "BarProduct" : [ "C1", "C3" ],
     "BazProduct" : [ "C7" ]
   }

This flag will be added to **all** components of "FooProduct",
components C1 and C3 of "BarProduct", and C7 of "BazProduct".

**Response**

   {
     "flagtypes": [
       {
         "name": "feedback-new",
         "changes": {
           "is_requestable": {
             "added": "0",
             "removed": "1"
           },
           "name": {
             "removed": "feedback",
             "added": "feedback-new"
           }
         },
         "id": 13
       }
     ]
   }

"flagtypes" (array) Flag change objects containing the following
items:

+---------+--------+------------------------------------------------------------------+
| name    | type   | description                                                      |
+=========+========+==================================================================+
| id      | int    | The ID of the flag type that was updated.                        |
+---------+--------+------------------------------------------------------------------+
| name    | string | The name of the flag type that was updated.                      |
+---------+--------+------------------------------------------------------------------+
| changes | object | The changes that were actually done on this flag type. The keys  |
+---------+--------+------------------------------------------------------------------+

Booleans changes will be represented with the strings '1' and '0'.

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

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