6.1.10. Flag Types

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

6.1.10.1. 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 product.

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 attachment.
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 this type.
is_multiplicable boolean Multiple flags of this type can be set for the same bug or attachment.

Errors

  • 106 (Product Access Denied) Either the product does not exist or you don't have access to it.
  • 51 (Invalid Component) The component provided does not exist in the product.

6.1.10.2. 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 attachment.
inclusions array An array of strings or an object containing product names, and optionally component names. If you provide a string, the flag type will be shown on all bugs in that product. If you provide an object, the key represents the product name, and the value is the components of the product to be included.
exclusions array An array of strings or an object containing product names. This uses the same format as inclusions. This will exclude the flag from all products and components specified.
sortkey int A number between 1 and 32767 by which this type will be sorted when displayed to users in a list; ignore if you don't care what order the types appear in or if you want them to appear in alphabetical order.
is_active boolean Flag of this type appear in the UI and can be set. Default is true.
is_requestable boolean Users can ask for flags of this type to be set. Default is true.
cc_list array If the flag type is requestable, who should receive e-mail notification of requests. This is an array of e-mail addresses whichdo not need to be Bugzilla logins.
is_specifically_requestable boolean Users can ask specific other users to set flags of this type as opposed to just asking the wind. Default is true.
is_multiplicable boolean Multiple flags of this type can be set on the same bug. Default is true.
grant_group string The group allowed to grant/deny flags of this type (to allow all users to grant/deny these flags, select no group). Default is no group.
request_group string If flags of this type are requestable, the group allowed to request them (to allow all users to request these flags, select no group). Note that the request group alone has no effect if the grant group is not defined! Default is no group.

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.

Errors

  • 51 (Group Does Not Exist) The group name you entered does not exist, or you do not have access to it.
  • 105 (Unknown component) The component does not exist for this product.
  • 106 (Product Access Denied) Either the product does not exist or you don't have editcomponents privileges to it.
  • 501 (Illegal Email Address) One of the e-mail address in the CC list is invalid. An e-mail in the CC list does NOT need to be a valid Bugzilla user.
  • 1101 (Flag Type Name invalid) You must specify a non-blank name for this flag type. It must no contain spaces or commas, and must be 50 characters or less.
  • 1102 (Flag type must have description) You must specify a description for this flag type.
  • 1103 (Flag type CC list is invalid The CC list must be 200 characters or less.
  • 1104 (Flag Type Sort Key Not Valid) The sort key is not a valid number.
  • 1105 (Flag Type Not Editable) This flag type is not available for the products you can administer. Therefore you can not edit attributes of the flag type, other than the inclusion and exclusion list.

6.1.10.3. 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 flag types have the same name, this will change all of them.

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 product names, and optionally component names. If you provide a string, the flag type will be shown on all bugs in that product. If you provide an object, the key represents the product name, and the value is the components of the product to be included.
exclusions array An array of strings or an object containing product names. This uses the same format as inclusions. This will exclude the flag from all products and components specified.
sortkey int A number between 1 and 32767 by which this type will be sorted when displayed to users in a list; ignore if you don't care what order the types appear in or if you want them to appear in alphabetical order.
is_active boolean Flag of this type appear in the UI and can be set.
is_requestable boolean Users can ask for flags of this type to be set.
cc_list array If the flag type is requestable, who should receive e-mail notification of requests. This is an array of e-mail addresses which do not need to be Bugzilla logins.
is_specifically_requestable boolean Users can ask specific other users to set flags of this type as opposed to just asking the wind.
is_multiplicable boolean Multiple flags of this type can be set on the same bug.
grant_group string The group allowed to grant/deny flags of this type (to allow all users to grant/deny these flags, select no group).
request_group string If flags of this type are requestable, the group allowed to request them (to allow all users to request these flags, select no group). Note that the request group alone has no effect if the grant group is not defined!

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 are the names of the fields that were changed, and the values are an object with two items:

  • added: (string) The value that this field was changed to.
  • removed: (string) The value that was previously set in this field.

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

Errors

  • 51 (Group Does Not Exist) The group name you entered does not exist, or you do not have access to it.
  • 105 (Unknown component) The component does not exist for this product.
  • 106 (Product Access Denied) Either the product does not exist or you don't have editcomponents privileges to it.
  • 501 (Illegal Email Address) One of the e-mail address in the CC list is invalid. An e-mail in the CC list does NOT need to be a valid Bugzilla user.
  • 1101 (Flag Type Name invalid) You must specify a non-blank name for this flag type. It must no contain spaces or commas, and must be 50 characters or less.
  • 1102 (Flag type must have description) You must specify a description for this flag type.
  • 1103 (Flag type CC list is invalid The CC list must be 200 characters or less.
  • 1104 (Flag Type Sort Key Not Valid) The sort key is not a valid number.
  • 1105 (Flag Type Not Editable) This flag type is not available for the products you can administer. Therefore you can not edit attributes of the flag type, other than the inclusion and exclusion list.