<<

# Bugzilla::Webservice::Bug

- NAME
- DESCRIPTION
- METHODS
  - Utility Functions
  - Bug Information
  - Bug Creation and Modification

# NAME

Bugzilla::Webservice::Bug - The API for creating, changing, and getting the details of bugs.

# DESCRIPTION

This part of the Bugzilla API allows you to file a new bug in Bugzilla, or get information about bugs that have already been filed.

# METHODS

See Bugzilla::WebService for a description of how parameters are passed, and what STABLE, UNSTABLE, and EXPERIMENTAL mean.

## Utility Functions

`legal_values`

  EXPERIMENTAL

  Description

    Tells you what values are allowed for a particular field.

  Params
    `field` - The name of the field you want information about. This should be the same as the name you would use in "create", below.
    `product_id` - If you're picking a product-specific field, you have to specify the id of the product you want the values for.
  Returns

    `values` - An array of strings: the legal values for this field. The values will be sorted as they normally would be in Bugzilla.

  Errors
    106 (Invalid Product)

      You were required to specify a product, and either you didn't, or you specified an invalid product (or a product that you can't access).

    108 (Invalid Field Name)

      You specified a field that doesn't exist or isn't a drop-down field.

## Bug Information

`get`

  EXPERIMENTAL

  Description

    Gets information about particular bugs in the database.

    Note: Can also be called as "get_bugs" for compatibilty with Bugzilla 3.0 API.

  Params
    `ids`

      An array of numbers and strings.

      If an element in the array is entirely numeric, it represents a bug_id from the Bugzilla database to fetch. If it contains any non-numeric characters, it is considered to be a bug alias instead, and the bug with that alias will be loaded.

      Note that it's possible for aliases to be disabled in Bugzilla, in which case you will be told that you have specified an invalid bug_id if you try to specify an alias. (It will be error 100.)

  Returns

    A hash containing a single element, `bugs`. This is an array of hashes. Each hash contains the following items:

    id

      `int` The numeric bug_id of this bug.

    alias

      `string` The alias of this bug. If there is no alias or aliases are disabled in this Bugzilla, this will be an empty string.

    summary

      `string` The summary of this bug.

    creation_time

      `dateTime` When the bug was created.

    last_change_time

      `dateTime` When the bug was last changed.

    internals UNSTABLE

      A hash. The internals of a Bugzilla::Bug object. This is extremely unstable, and you should only rely on this if you absolutely have to. The structure of the hash may even change between point releases of Bugzilla.

  Errors
    100 (Invalid Bug Alias)

      If you specified an alias and either: (a) the Bugzilla you're querying doesn't support aliases or (b) there is no bug with that alias.

    101 (Invalid Bug ID)

      The bug_id you specified doesn't exist in the database.

    102 (Access Denied)

      You do not have access to the bug_id you specified.

## Bug Creation and Modification

`create` EXPERIMENTAL
  Description

    This allows you to create a new bug in Bugzilla. If you specify any invalid fields, they will be ignored. If you specify any fields you are not allowed to set, they will just be set to their defaults or ignored.

    You cannot currently set all the items here that you can set on enter_bug.cgi.

    The WebService interface may allow you to set things other than those listed here, but realize that anything undocumented is UNSTABLE and will very likely change in the future.

  Params

    Some params must be set, or an error will be thrown. These params are marked Required.

    Some parameters can have defaults set in Bugzilla, by the administrator. If these parameters have defaults set, you can omit them. These parameters are marked Defaulted.

    Clients that want to be able to interact uniformly with multiple Bugzillas should always set both the params marked Required and those marked Defaulted, because some Bugzillas may not have defaults set for Defaulted parameters, and then this method will throw an error if you don't specify them.

    The descriptions of the parameters below are what they mean when Bugzilla is being used to track software bugs. They may have other meanings in some installations.

    `product` (string) Required - The name of the product the bug is being filed against.
    `component` (string) Required - The name of a component in the product above.
    `summary` (string) Required - A brief description of the bug being filed.
    `version` (string) Required - A version of the product above; the version the bug was found in.
    `description` (string) Defaulted - The initial description for this bug. Some Bugzilla installations require this to not be blank.
    `op_sys` (string) Defaulted - The operating system the bug was discovered on.
    `platform` (string) Defaulted - What type of hardware the bug was experienced on.
    `priority` (string) Defaulted - What order the bug will be fixed in by the developer, compared to the developer's other bugs.
    `severity` (string) Defaulted - How severe the bug is.
    `alias` (string) - A brief alias for the bug that can be used instead of a bug number when accessing this bug. Must be unique in all of this Bugzilla.
    `assigned_to` (username) - A user to assign this bug to, if you don't want it to be assigned to the component owner.
    `cc` (array) - An array of usernames to CC on this bug.
    `qa_contact` (username) - If this installation has QA Contacts enabled, you can set the QA Contact here if you don't want to use the component's default QA Contact.
    `status` (string) - The status that this bug should start out as. Note that only certain statuses can be set on bug creation.
    `target_milestone` (string) - A valid target milestone for this product.

    In addition to the above parameters, if your installation has any custom fields, you can set them just by passing in the name of the field and its value as a string.

  Returns

    A hash with one element, `id`. This is the id of the newly-filed bug.

  Errors
    51 (Invalid Object)

      The component you specified is not valid for this Product.

    103 (Invalid Alias)

      The alias you specified is invalid for some reason. See the error message for more details.

    104 (Invalid Field)

      One of the drop-down fields has an invalid value, or a value entered in a text field is too long. The error message will have more detail.

    105 (Invalid Component)

      You didn't specify a component.

    106 (Invalid Product)

      Either you didn't specify a product, this product doesn't exist, or you don't have permission to enter bugs in this product.

    107 (Invalid Summary)

      You didn't specify a summary for the bug.

    504 (Invalid User)

      Either the QA Contact, Assignee, or CC lists have some invalid user in them. The error message will have more details.

  History
    Before 3.0.4, parameters marked as Defaulted were actually Required, due to a bug in Bugzilla.
`add_comment`

  EXPERIMENTAL

  Description

    This allows you to add a comment to a bug in Bugzilla.

  Params
    `id` (int) Required - The id or alias of the bug to append a comment to.
    `comment` (string) Required - The comment to append to the bug. If this is empty or all whitespace, an error will be thrown saying that you did not set the `comment` parameter.
    `private` (boolean) - If set to true, the comment is private, otherwise it is assumed to be public.
    `work_time` (double) - Adds this many hours to the "Hours Worked" on the bug. If you are not in the time tracking group, this value will be ignored.
  Errors
    100 (Invalid Bug Alias)

      If you specified an alias and either: (a) the Bugzilla you're querying doesn't support aliases or (b) there is no bug with that alias.

    101 (Invalid Bug ID)

      The id you specified doesn't exist in the database.

    108 (Bug Edit Denied)

      You did not have the necessary rights to edit the bug.

  History
    Added in Bugzilla 3.2.

<<