5.7.95. Bugzilla::WebService::FlagType

5.7.95.1. NAME

Bugzilla::WebService::FlagType - API for creating flags.

5.7.95.2. DESCRIPTION

This part of the Bugzilla API allows you to create new flags

5.7.95.3. METHODS

See Bugzilla::WebService for a description of what STABLE, UNSTABLE, and EXPERIMENTAL mean, and for more description about error codes.

Get Flag Types

  • get UNSTABLE
  • Description
Get information about valid flag types that can be set for bugs and attachments.
  • REST

You have several options for retreiving information about flag types. The first part is the request method and the rest is the related path needed.

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>

The returned data format is the same as below.

  • Params

You must pass a product name and an optional component name.

  • product (string) - The name of a valid product.
  • component (string) - An optional valid component name associated with the product.
  • Returns

A hash containing two keys, bug and attachment. Each key value is an array of hashes, containing the following keys:

  • 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 An array of 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.
  • History
  • Added in Bugzilla 5.0.

Create Flag

  • create UNSTABLE
  • Description
Creates a new FlagType
  • REST

POST /rest/flag_type

The params to include in the POST body as well as the returned data format, are the same as below.

  • Params

At a minimum the following two arguments must be supplied:

  • name (string) - The name of the new Flag Type.
  • description (string) - A description for the Flag Type object.
  • Returns

int flag_id

The ID of the new FlagType object is returned.

  • Params
  • name required
string A short name identifying this type.
  • description required
string A comprehensive description of this type.
  • inclusions optional

An array of strings or a hash 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 a hash, the key represents the product name, and the value is the components of the product to be included.

For example:

[ '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.

  • exclusions optional

An array of strings or hashes containing product names. This uses the same fromat as inclusions.

This will exclude the flag from all products and components specified.

  • sortkey optional
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 optional
boolean Flag of this type appear in the UI and can be set. Default is true.
  • is_requestable optional
boolean Users can ask for flags of this type to be set. Default is true.
  • cc_list optional
array An array of strings. 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 optional
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 optional
boolean Multiple flags of this type can be set on the same bug. Default is true.
  • grant_group optional
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 optional
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.
  • view_group optional

string default is no group

The group allowed to see flags of this type (to allow all users to see these flags, select no group)

This is a Red Hat customization.

  • category optional

string the only valid value is release

This is used for reporting purposes only. If you don’t know, leave it blank.

This is a Red Hat customization.

  • 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.
  • History
  • Added in Bugzilla 5.0.

update

EXPERIMENTAL

  • Description
This allows you to update a flag type in Bugzilla.
  • REST

PUT /rest/flag_type/<product_id_or_name>

The params to include in the PUT body as well as the returned data format, are the same as below. The ids and names params will be overridden as it is pulled from the URL path.

  • Params

Note: The following parameters specify which products you are updating. You must set one or both of these parameters.

  • ids
array of ints. Numeric ids of the flag types that you wish to update.
  • names
array of strings. Names of the flag types that you wish to update. If many flag types have the same name, this will change ALL of them.

Note: The following parameters specify the new values you want to set for the products you are updating.

  • name
string A short name identifying this type.
  • description
string A comprehensive description of this type.
  • inclusions optional

An array of strings or a hash 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 a hash, the key represents the product name, and the value is the components of the product to be included.

for example

[ '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.

  • exclusions optional

An array of strings or hashes containing product names. This uses the same fromat 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 An array of strings. 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!
  • Returns

A hash with a single field “flagtypes”. This points to an array of hashes with the following fields:

  • id
int The id of the product that was updated.
  • name
string The name of the product that was updated.
  • changes

hash The changes that were actually done on this product. The keys are the names of the fields that were changed, and the values are a hash with two keys:

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

Note that booleans will be represented with the strings ‘1’ and ‘0’.

Here’s an example of what a return value might look like:

{
  products => [
    {
      id => 123,
      changes => {
        name => {
          removed => 'FooFlagType',
          added   => 'BarFlagType'
        },
        is_requestable => {
          removed => '1',
          added   => '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.
  • History
  • Added in Bugzilla 5.0.

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