| Bugs |
| ==== |
| |
| The REST API for creating, changing, and getting the details of bugs. |
| |
| This part of the Bugzilla REST API allows you to file new bugs in Bugzilla and |
| to get information about existing bugs. |
| |
| .. _rest_single_bug: |
| |
| Get Bug |
| ------- |
| |
| Gets information about particular bugs in the database. |
| |
| **Request** |
| |
| To get information about a particular bug using its ID or alias: |
| |
| .. code-block:: text |
| |
| GET /rest/bug/(id_or_alias) |
| |
| You can also use :ref:`rest_search_bugs` to return more than one bug at a time |
| by specifying bug IDs as the search terms. |
| |
| .. code-block:: text |
| |
| GET /rest/bug?id=12434,43421 |
| |
| ================ ===== ====================================================== |
| name type description |
| ================ ===== ====================================================== |
| **id_or_alias** mixed An integer bug ID or a bug alias string. |
| ================ ===== ====================================================== |
| |
| **Response** |
| |
| .. code-block:: js |
| |
| { |
| "faults": [], |
| "bugs": [ |
| { |
| "assigned_to_detail": { |
| "id": 2, |
| "real_name": "Test User", |
| "name": "user@bugzilla.org", |
| "email": "user@bugzilla.org" |
| }, |
| "flags": [ |
| { |
| "type_id": 11, |
| "modification_date": "2014-09-28T21:03:47Z", |
| "name": "blocker", |
| "status": "?", |
| "id": 2906, |
| "setter": "user@bugzilla.org", |
| "creation_date": "2014-09-28T21:03:47Z" |
| } |
| ], |
| "resolution": "INVALID", |
| "id": 35, |
| "qa_contact": "", |
| "version": "1.0", |
| "status": "RESOLVED", |
| "creator": "user@bugzilla.org", |
| "cf_drop_down": "---", |
| "summary": "test bug", |
| "last_change_time": "2014-09-23T19:12:17Z", |
| "platform": "All", |
| "url": "", |
| "classification": "Unclassified", |
| "cc_detail": [ |
| { |
| "id": 786, |
| "real_name": "Foo Bar", |
| "name": "foo@bar.com", |
| "email": "foo@bar.com" |
| }, |
| ], |
| "priority": "P1", |
| "is_confirmed": true, |
| "creation_time": "2000-07-25T13:50:04Z", |
| "assigned_to": "user@bugzilla.org", |
| "flags": [], |
| "alias": [], |
| "cf_large_text": "", |
| "groups": [], |
| "op_sys": "All", |
| "cf_bug_id": null, |
| "depends_on": [], |
| "is_cc_accessible": true, |
| "is_open": false, |
| "cf_qa_list_4": "---", |
| "keywords": [], |
| "cc": [ |
| "foo@bar.com", |
| ], |
| "see_also": [], |
| "deadline": null, |
| "is_creator_accessible": true, |
| "whiteboard": "", |
| "dupe_of": null, |
| "target_milestone": "---", |
| "cf_mulitple_select": [], |
| "component": "SaltSprinkler", |
| "severity": "critical", |
| "cf_date": null, |
| "product": "FoodReplicator", |
| "creator_detail": { |
| "id": 28, |
| "real_name": "hello", |
| "name": "user@bugzilla.org", |
| "email": "namachi@netscape.com" |
| }, |
| "cf_free_text": "", |
| "blocks": [] |
| } |
| ] |
| } |
| |
| ``bugs`` (array) Each bug object contains information about the bugs with valid |
| ids containing the following items: |
| |
| These fields are returned by default or by specifying ``_default`` in |
| ``include_fields``. |
| |
| ===================== ======== ================================================ |
| name type description |
| ===================== ======== ================================================ |
| actual_time double The total number of hours that this bug has |
| taken so far. If you are not in the time-tracking |
| group, this field will not be included in the |
| return value. |
| alias array The unique aliases of this bug. An empty array |
| will be returned if this bug has no aliases. |
| assigned_to string The login name of the user to whom the bug is |
| assigned. |
| assigned_to_detail object An object containing detailed user information |
| for the assigned_to. To see the keys included |
| in the user detail object, see below. |
| blocks array The IDs of bugs that are "blocked" by this bug. |
| cc array The login names of users on the CC list of this |
| bug. |
| cc_detail array Array of objects containing detailed user |
| information for each of the cc list members. |
| To see the keys included in the user detail |
| object, see below. |
| classification string The name of the current classification the bug |
| is in. |
| component string The name of the current component of this bug. |
| creation_time datetime When the bug was created. |
| creator string The login name of the person who filed this bug |
| (the reporter). |
| creator_detail object An object containing detailed user information |
| for the creator. To see the keys included in the |
| user detail object, see below. |
| deadline string The day that this bug is due to be completed, in |
| the format ``YYYY-MM-DD``. |
| depends_on array The IDs of bugs that this bug "depends on". |
| dupe_of int The bug ID of the bug that this bug is a |
| duplicate of. If this bug isn't a duplicate of |
| any bug, this will be null. |
| estimated_time double The number of hours that it was estimated that |
| this bug would take. If you are not in the |
| time-tracking group, this field will not be |
| included in the return value. |
| flags array An array of objects containing the information |
| about flags currently set for the bug. Each flag |
| objects contains the following items |
| groups array The names of all the groups that this bug is in. |
| id int The unique numeric ID of this bug. |
| is_cc_accessible boolean If true, this bug can be accessed by members of |
| the CC list, even if they are not in the groups |
| the bug is restricted to. |
| is_confirmed boolean ``true`` if the bug has been confirmed. Usually |
| this means that the bug has at some point been |
| moved out of the ``UNCONFIRMED`` status and into |
| another open status. |
| is_open boolean ``true`` if this bug is open, ``false`` if it |
| is closed. |
| is_creator_accessible boolean If ``true``, this bug can be accessed by the |
| creator of the bug, even if they are not a |
| member of the groups the bug is restricted to. |
| keywords array Each keyword that is on this bug. |
| last_change_time datetime When the bug was last changed. |
| op_sys string The name of the operating system that the bug |
| was filed against. |
| platform string The name of the platform (hardware) that the bug |
| was filed against. |
| priority string The priority of the bug. |
| product string The name of the product this bug is in. |
| qa_contact string The login name of the current QA Contact on the |
| bug. |
| qa_contact_detail object An object containing detailed user information |
| for the qa_contact. To see the keys included in |
| the user detail object, see below. |
| remaining_time double The number of hours of work remaining until work |
| on this bug is complete. If you are not in the |
| time-tracking group, this field will not be |
| included in the return value. |
| resolution string The current resolution of the bug, or an empty |
| string if the bug is open. |
| see_also array The URLs in the See Also field on the bug. |
| severity string The current severity of the bug. |
| status string The current status of the bug. |
| summary string The summary of this bug. |
| target_milestone string The milestone that this bug is supposed to be |
| fixed by, or for closed bugs, the milestone that |
| it was fixed for. |
| update_token string The token that you would have to pass to the |
| ``process_bug.cgi`` page in order to update this |
| bug. This changes every time the bug is updated. |
| This field is not returned to logged-out users. |
| url string A URL that demonstrates the problem described in |
| the bug, or is somehow related to the bug report. |
| version string The version the bug was reported against. |
| whiteboard string The value of the "status whiteboard" field on |
| the bug. |
| ===================== ======== ================================================ |
| |
| Custom fields: |
| |
| Every custom field in this installation will also be included in the |
| return value. Most fields are returned as strings. However, some field types have |
| different return values. |
| |
| Normally custom fields are returned by default similar to normal bug fields or |
| you can specify only custom fields by using ``_custom`` in ``include_fields``. |
| |
| Extra fields: |
| |
| These fields are returned only by specifying ``_extra`` or the field name in |
| ``include_fields``. |
| |
| ==== ===== ==================================================================== |
| name type description |
| ==== ===== ==================================================================== |
| tags array Each array item is a tag name. Note that tags are |
| personal to the currently logged in user and are not the same as |
| comment tags. |
| ==== ===== ==================================================================== |
| |
| User object: |
| |
| ========= ====== ============================================================== |
| name type description |
| ========= ====== ============================================================== |
| id int The user ID for this user. |
| real_name string The 'real' name for this user, if any. |
| name string The user's Bugzilla login. |
| email string The user's email address. Currently this is the same value as |
| the name. |
| ========= ====== ============================================================== |
| |
| Flag object: |
| |
| ================= ======== ==================================================== |
| name type description |
| ================= ======== ==================================================== |
| id int The ID of the flag. |
| name string The name of the flag. |
| type_id int The type ID of the flag. |
| creation_date datetime The timestamp when this flag was originally created. |
| modification_date datetime The timestamp when the flag was last modified. |
| status string The current status of the flag. |
| setter string The login name of the user who created or last |
| modified the flag. |
| requestee string The login name of the user this flag has been |
| requested to be granted or denied. Note, this field |
| is only returned if a requestee is set. |
| ================= ======== ==================================================== |
| |
| Custom field object: |
| |
| You can specify to only return custom fields by specifying ``_custom`` or the |
| field name in ``include_fields``. |
| |
| * Bug ID Fields: (int) |
| * Multiple-Selection Fields: (array of strings) |
| * Date/Time Fields: (datetime) |
| |
| .. _rest_history: |
| |
| Bug History |
| ----------- |
| |
| Gets the history of changes for particular bugs in the database. |
| |
| **Request** |
| |
| To get the history for a specific bug ID: |
| |
| .. code-block:: text |
| |
| GET /rest/bug/(id)/history |
| |
| To get the history for a bug since a specific date: |
| |
| .. code-block:: text |
| |
| GET /rest/bug/(id)/history?new_since=YYYY-MM-DD |
| |
| ========= ======== ============================================================ |
| name type description |
| ========= ======== ============================================================ |
| **id** mixed An integer bug ID or alias. |
| new_since datetime A datetime timestamp to only show history since. |
| ========= ======== ============================================================ |
| |
| **Response** |
| |
| .. code-block:: js |
| |
| { |
| "bugs": [ |
| { |
| "alias": [], |
| "history": [ |
| { |
| "when": "2014-09-23T19:12:17Z", |
| "who": "user@bugzilla.org", |
| "changes": [ |
| { |
| "added": "P1", |
| "field_name": "priority", |
| "removed": "P2" |
| }, |
| { |
| "removed": "blocker", |
| "field_name": "severity", |
| "added": "critical" |
| } |
| ] |
| }, |
| { |
| "when": "2014-09-28T21:03:47Z", |
| "who": "user@bugzilla.org", |
| "changes": [ |
| { |
| "added": "blocker?", |
| "removed": "", |
| "field_name": "flagtypes.name" |
| } |
| ] |
| } |
| ], |
| "id": 35 |
| } |
| ] |
| } |
| |
| ``bugs`` (array) Bug objects each containing the following items: |
| |
| ======= ===== ================================================================= |
| name type description |
| ======= ===== ================================================================= |
| id int The numeric ID of the bug. |
| alias array The unique aliases of this bug. An empty array will be returned |
| if this bug has no aliases. |
| history array An array of History objects. |
| ======= ===== ================================================================= |
| |
| History object: |
| |
| ======= ======== ============================================================== |
| name type description |
| ======= ======== ============================================================== |
| when datetime The date the bug activity/change happened. |
| who string The login name of the user who performed the bug change. |
| changes array An array of Change objects which contain all the changes that |
| happened to the bug at this time (as specified by ``when``). |
| ======= ======== ============================================================== |
| |
| Change object: |
| |
| ============= ====== ========================================================== |
| name type description |
| ============= ====== ========================================================== |
| field_name string The name of the bug field that has changed. |
| removed string The previous value of the bug field which has been |
| deleted by the change. |
| added string The new value of the bug field which has been added |
| by the change. |
| attachment_id int The ID of the attachment that was changed. |
| This only appears if the change was to an attachment, |
| otherwise ``attachment_id`` will not be present in this |
| object. |
| ============= ====== ========================================================== |
| |
| .. _rest_search_bugs: |
| |
| Search Bugs |
| ----------- |
| |
| Allows you to search for bugs based on particular criteria. |
| |
| **Request** |
| |
| To search for bugs: |
| |
| .. code-block:: text |
| |
| GET /rest/bug |
| |
| Unless otherwise specified in the description of a parameter, bugs are |
| returned if they match *exactly* the criteria you specify in these |
| parameters. That is, we don't match against substrings--if a bug is in |
| the "Widgets" product and you ask for bugs in the "Widg" product, you |
| won't get anything. |
| |
| Criteria are joined in a logical AND. That is, you will be returned |
| bugs that match *all* of the criteria, not bugs that match *any* of |
| the criteria. |
| |
| Each parameter can be either the type it says, or a list of the types |
| it says. If you pass an array, it means "Give me bugs with *any* of |
| these values." For example, if you wanted bugs that were in either |
| the "Foo" or "Bar" products, you'd pass: |
| |
| .. code-block:: text |
| |
| GET /rest/bug?product=Foo&product=Bar |
| |
| Some Bugzillas may treat your arguments case-sensitively, depending |
| on what database system they are using. Most commonly, though, Bugzilla is |
| not case-sensitive with the arguments passed (because MySQL is the |
| most-common database to use with Bugzilla, and MySQL is not case sensitive). |
| |
| In addition to the fields listed below, you may also use criteria that |
| is similar to what is used in the Advanced Search screen of the Bugzilla |
| UI. This includes fields specified by ``Search by Change History`` and |
| ``Custom Search``. The easiest way to determine what the field names are and what |
| format Bugzilla expects is to first construct your query using the |
| Advanced Search UI, execute it and use the query parameters in they URL |
| as your query for the REST call. |
| |
| ================ ======== ===================================================== |
| name type description |
| ================ ======== ===================================================== |
| alias array The unique aliases of this bug. An empty array will |
| be returned if this bug has no aliases. |
| assigned_to string The login name of a user that a bug is assigned to. |
| component string The name of the Component that the bug is in. Note |
| that if there are multiple Components with the same |
| name, and you search for that name, bugs in *all* |
| those Components will be returned. If you don't want |
| this, be sure to also specify the ``product`` argument. |
| creation_time datetime Searches for bugs that were created at this time or |
| later. May not be an array. |
| creator string The login name of the user who created the bug. You |
| can also pass this argument with the name |
| ``reporter``, for backwards compatibility with |
| older Bugzillas. |
| id int The numeric ID of the bug. |
| last_change_time datetime Searches for bugs that were modified at this time |
| or later. May not be an array. |
| limit int Limit the number of results returned. If the limit |
| is more than zero and higher than the maximum limit |
| set by the administrator, then the maximum limit will |
| be used instead. If you set the limit equal to zero, |
| then all matching results will be returned instead. |
| offset int Used in conjunction with the ``limit`` argument, |
| ``offset`` defines the starting position for the |
| search. For example, given a search that would |
| return 100 bugs, setting ``limit`` to 10 and |
| ``offset`` to 10 would return bugs 11 through 20 |
| from the set of 100. |
| op_sys string The "Operating System" field of a bug. |
| platform string The Platform (sometimes called "Hardware") field of |
| a bug. |
| priority string The Priority field on a bug. |
| product string The name of the Product that the bug is in. |
| resolution string The current resolution--only set if a bug is closed. |
| You can find open bugs by searching for bugs with an |
| empty resolution. |
| severity string The Severity field on a bug. |
| status string The current status of a bug (not including its |
| resolution, if it has one, which is a separate field |
| above). |
| summary string Searches for substrings in the single-line Summary |
| field on bugs. If you specify an array, then bugs |
| whose summaries match *any* of the passed substrings |
| will be returned. Note that unlike searching in the |
| Bugzilla UI, substrings are not split on spaces. So |
| searching for ``foo bar`` will match "This is a foo |
| bar" but not "This foo is a bar". ``['foo', 'bar']``, |
| would, however, match the second item. |
| tags string Searches for a bug with the specified tag. If you |
| specify an array, then any bugs that match *any* of |
| the tags will be returned. Note that tags are |
| personal to the currently logged in user. |
| target_milestone string The Target Milestone field of a bug. Note that even |
| if this Bugzilla does not have the Target Milestone |
| field enabled, you can still search for bugs by |
| Target Milestone. However, it is likely that in that |
| case, most bugs will not have a Target Milestone set |
| (it defaults to "---" when the field isn't enabled). |
| qa_contact string The login name of the bug's QA Contact. Note that |
| even if this Bugzilla does not have the QA Contact |
| field enabled, you can still search for bugs by QA |
| Contact (though it is likely that no bug will have a |
| QA Contact set, if the field is disabled). |
| url string The "URL" field of a bug. |
| version string The Version field of a bug. |
| whiteboard string Search the "Status Whiteboard" field on bugs for a |
| substring. Works the same as the ``summary`` field |
| described above, but searches the Status Whiteboard |
| field. |
| quicksearch string Search for bugs using quicksearch syntax. |
| ================ ======== ===================================================== |
| |
| **Response** |
| |
| The same as :ref:`rest_single_bug`. |
| |
| .. _rest_create_bug: |
| |
| Create Bug |
| ---------- |
| |
| This allows you to create a new bug in Bugzilla. If you specify any |
| invalid fields, an error will be thrown stating which field is invalid. |
| 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 here may likely change in the |
| future. |
| |
| **Request** |
| |
| To create a new bug in Bugzilla. |
| |
| .. code-block:: text |
| |
| POST /rest/bug |
| |
| .. code-block:: js |
| |
| { |
| "product" : "TestProduct", |
| "component" : "TestComponent", |
| "version" : "unspecified", |
| "summary" : "'This is a test bug - please disregard", |
| "alias" : "SomeAlias", |
| "op_sys" : "All", |
| "priority" : "P1", |
| "rep_platform" : "All" |
| } |
| |
| Some params must be set, or an error will be thrown. These params are |
| marked in **bold**. |
| |
| 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. |
| |
| ================== ======= ==================================================== |
| name type description |
| ================== ======= ==================================================== |
| **product** string The name of the product the bug is being filed |
| against. |
| **component** string The name of a component in the product above. |
| **summary** string A brief description of the bug being filed. |
| **version** string 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 array One or more brief aliases 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 string 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. |
| comment_is_private boolean If set to true, the description is private, |
| otherwise it is assumed to be public. |
| groups array An array of group names to put this bug into. You |
| can see valid group names on the Permissions tab of |
| the Preferences screen, or, if you are an |
| administrator, in the Groups control panel. If you |
| don't specify this argument, then the bug will be |
| added into all the groups that are set as being |
| "Default" for this product. (If you want to avoid |
| that, you should specify ``groups`` as an empty |
| array.) |
| qa_contact string 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. |
| resolution string If you are filing a closed bug, then you will have |
| to specify a resolution. You cannot currently |
| specify a resolution of ``DUPLICATE`` for new |
| bugs, though. That must be done with |
| :ref:`rest_update_bug`. |
| target_milestone string A valid target milestone for this product. |
| flags array Flags objects to add to the bug. The object format |
| is described in the Flag object below. |
| ================== ======= ==================================================== |
| |
| Flag object: |
| |
| To create a flag, at least the ``status`` and the ``type_id`` or ``name`` must |
| be provided. An optional requestee can be passed if the flag type is requestable |
| to a specific user. |
| |
| ========= ====== ============================================================== |
| name type description |
| ========= ====== ============================================================== |
| name string The name of the flag type. |
| type_id int The internal flag type ID. |
| status string The flags new status (i.e. "?", "+", "-" or "X" to clear flag). |
| requestee string The login of the requestee if the flag type is requestable |
| to a specific user. |
| ========= ====== ============================================================== |
| |
| 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. |
| |
| **Response** |
| |
| .. code-block:: js |
| |
| { |
| "id" : 12345 |
| } |
| |
| ==== ==== ====================================== |
| name type description |
| ==== ==== ====================================== |
| id int This is the ID of the newly-filed bug. |
| ==== ==== ====================================== |
| |
| .. _rest_update_bug: |
| |
| Update Bug |
| ---------- |
| |
| Allows you to update the fields of a bug. Automatically sends emails |
| out about the changes. |
| |
| **Request** |
| |
| To update the fields of a current bug. |
| |
| .. code-block:: text |
| |
| PUT /rest/bug/(id_or_alias) |
| |
| .. code-block:: js |
| |
| { |
| "ids" : [35], |
| "status" : "IN_PROGRESS", |
| "keywords" : { |
| "add" : ["funny", "stupid"] |
| } |
| } |
| |
| The params to include in the PUT body as well as the returned data format, |
| are the same as below. You can specify the ID or alias of the bug to update |
| either in the URL path and/or in the ``ids`` param. You can use both and they |
| will be combined so you can edit more than one bug at a time. |
| |
| =============== ===== ========================================================= |
| name type description |
| =============== ===== ========================================================= |
| **id_or_alias** mixed An integer bug ID or alias. |
| **ids** array The IDs or aliases of the bugs that you want to modify. |
| =============== ===== ========================================================= |
| |
| All following fields specify the values you want to set on the bugs you are |
| updating. |
| |
| ===================== ======= ================================================= |
| name type description |
| ===================== ======= ================================================= |
| alias object These specify the aliases of a bug that can be |
| used instead of a bug number when acessing this |
| bug. To set these, you should pass a hash as the |
| value. The object may contain the following |
| items: |
| |
| * ``add`` (array) Aliases to add to this field. |
| * ``remove`` (array) Aliases to remove from this |
| field. If the aliases are not already in the |
| field, they will be ignored. |
| * ``set`` (array) An exact set of aliases to set |
| this field to, overriding the current value. |
| If you specify ``set``, then ``add`` and |
| ``remove`` will be ignored. |
| |
| You can only set this if you are modifying a |
| single bug. If there is more than one bug |
| specified in ``ids``, passing in a value for |
| ``alias`` will cause an error to be thrown. |
| |
| For backwards compatibility, you can also |
| specify a single string. This will be treated as |
| if you specified the set key above. |
| assigned_to string The full login name of the user this bug is |
| assigned to. |
| blocks object (Same as ``depends_on`` below) |
| depends_on object These specify the bugs that this bug blocks or |
| depends on, respectively. To set these, you |
| should pass an object as the value. The object |
| may contain the following items: |
| |
| * ``add`` (array) Bug IDs to add to this field. |
| * ``remove`` (array) Bug IDs to remove from this |
| field. If the bug IDs are not already in the |
| field, they will be ignored. |
| * ``set`` (array of) An exact set of bug IDs to |
| set this field to, overriding the current |
| value. If you specify ``set``, then ``add`` |
| and ``remove`` will be ignored. |
| cc object The users on the cc list. To modify this field, |
| pass an object, which may have the following |
| items: |
| |
| * ``add`` (array) User names to add to the CC |
| list. They must be full user names, and an |
| error will be thrown if you pass in an invalid |
| user name. |
| * ``remove`` (array) User names to remove from |
| the CC list. They must be full user names, and |
| an error will be thrown if you pass in an |
| invalid user name. |
| is_cc_accessible boolean Whether or not users in the CC list are allowed |
| to access the bug, even if they aren't in a group |
| that can normally access the bug. |
| comment object A comment on the change. The object may contain |
| the following items: |
| |
| * ``body`` (string) The actual text of the |
| comment. For compatibility with the parameters |
| to :ref:`rest_add_comment`, you can also call |
| this field ``comment``, if you want. |
| * ``is_private`` (boolean) Whether the comment is |
| private or not. If you try to make a comment |
| private and you don't have the permission to, |
| an error will be thrown. |
| comment_is_private object This is how you update the privacy of comments |
| that are already on a bug. This is a object, |
| where the keys are the ``int`` ID of comments |
| (not their count on a bug, like #1, #2, #3, but |
| their globally-unique ID, as returned by |
| :ref:`rest_comments` and the value is a |
| ``boolean`` which specifies whether that comment |
| should become private (``true``) or public |
| (``false``). |
| |
| The comment IDs must be valid for the bug being |
| updated. Thus, it is not practical to use this |
| while updating multiple bugs at once, as a single |
| comment ID will never be valid on multiple bugs. |
| component string The Component the bug is in. |
| deadline date The Deadline field is a date specifying when the |
| bug must be completed by, in the format |
| ``YYYY-MM-DD``. |
| dupe_of int The bug that this bug is a duplicate of. If you |
| want to mark a bug as a duplicate, the safest |
| thing to do is to set this value and *not* set |
| the ``status`` or ``resolutio`` fields. They will |
| automatically be set by Bugzilla to the |
| appropriate values for duplicate bugs. |
| estimated_time double The total estimate of time required to fix the |
| bug, in hours. This is the *total* estimate, not |
| the amount of time remaining to fix it. |
| flags array An array of Flag change objects. The items needed |
| are described below. |
| groups object The groups a bug is in. To modify this field, |
| pass an object, which may have the following |
| items: |
| |
| * ``add`` (array) The names of groups to add. |
| Passing in an invalid group name or a group |
| that you cannot add to this bug will cause an |
| error to be thrown. |
| * ``remove`` (array) The names of groups to |
| remove. Passing in an invalid group name or a |
| group that you cannot remove from this bug |
| will cause an error to be thrown. |
| keywords object Keywords on the bug. To modify this field, pass |
| an object, which may have the following items: |
| |
| * ``add`` (array) The names of keywords to add |
| to the field on the bug. Passing something that |
| isn't a valid keyword name will cause an error |
| to be thrown. |
| * ``remove`` (array) The names of keywords to |
| remove from the field on the bug. Passing |
| something that isn't a valid keyword name will |
| cause an error to be thrown. |
| * ``set`` (array) An exact set of keywords to set |
| the field to, on the bug. Passing something |
| that isn't a valid keyword name will cause an |
| error to be thrown. Specifying ``set`` |
| overrides ``add`` and ``remove``. |
| op_sys string The Operating System ("OS") field on the bug. |
| platform string The Platform or "Hardware" field on the bug. |
| priority string The Priority field on the bug. |
| product string The name of the product that the bug is in. If |
| you change this, you will probably also want to |
| change ``target_milestone``, ``version``, and |
| ``component``, since those have different legal |
| values in every product. |
| |
| If you cannot change the ``target_milestone`` |
| field, it will be reset to the default for the |
| product, when you move a bug to a new product. |
| |
| You may also wish to add or remove groups, as |
| which groups are |
| valid on a bug depends on the product. Groups |
| that are not valid in the new product will be |
| automatically removed, and groups which are |
| mandatory in the new product will be automaticaly |
| added, but no other automatic group changes will |
| be done. |
| |
| .. note:: |
| Users can only move a bug into a product if |
| they would normally have permission to file |
| new bugs in that product. |
| qa_contact string The full login name of the bug's QA Contact. |
| is_creator_accessible boolean Whether or not the bug's reporter is allowed |
| to access the bug, even if they aren't in a group |
| that can normally access the bug. |
| remaining_time double How much work time is remaining to fix the bug, |
| in hours. If you set ``work_time`` but don't |
| explicitly set ``remaining_time``, then the |
| ``work_time`` will be deducted from the bug's |
| ``remaining_time``. |
| reset_assigned_to boolean If true, the ``assigned_to`` field will be |
| reset to the default for the component that the |
| bug is in. (If you have set the component at the |
| same time as using this, then the component used |
| will be the new component, not the old one.) |
| reset_qa_contact boolean If true, the ``qa_contact`` field will be reset |
| to the default for the component that the bug is |
| in. (If you have set the component at the same |
| time as using this, then the component used will |
| be the new component, not the old one.) |
| resolution string The current resolution. May only be set if you |
| are closing a bug or if you are modifying an |
| already-closed bug. Attempting to set the |
| resolution to *any* value (even an empty or null |
| string) on an open bug will cause an error to be |
| thrown. |
| |
| .. note:: |
| If you change the ``status`` field to an open |
| status, the resolution field will automatically |
| be cleared, so you don't have to clear it |
| manually. |
| see_also object The See Also field on a bug, specifying URLs to |
| bugs in other bug trackers. To modify this field, |
| pass an object, which may have the following |
| items: |
| |
| * ``add`` (array) URLs to add to the field. Each |
| URL must be a valid URL to a bug-tracker, or |
| an error will be thrown. |
| * ``remove`` (array) URLs to remove from the |
| field. Invalid URLs will be ignored. |
| severity string The Severity field of a bug. |
| status string The status you want to change the bug to. Note |
| that if a bug is changing from open to closed, |
| you should also specify a ``resolution``. |
| summary string The Summary field of the bug. |
| target_milestone string The bug's Target Milestone. |
| url string The "URL" field of a bug. |
| version string The bug's Version field. |
| whiteboard string The Status Whiteboard field of a bug. |
| work_time double The number of hours worked on this bug as part |
| of this change. |
| If you set ``work_time`` but don't explicitly |
| set ``remaining_time``, then the ``work_time`` |
| will be deducted from the bug's ``remaining_time``. |
| ===================== ======= ================================================= |
| |
| You can also set the value of any custom field by passing its name as |
| a parameter, and the value to set the field to. For multiple-selection |
| fields, the value should be an array of strings. |
| |
| Flag change object: |
| |
| The following values can be specified. At least the ``status`` and one of |
| ``type_id``, ``id``, or ``name`` must be specified. If a ``type_id`` or |
| ``name`` matches a single currently set flag, the flag will be updated unless |
| ``new`` is specified. |
| |
| ========== ======= ============================================================ |
| name type description |
| ========== ======= ============================================================ |
| name string The name of the flag that will be created or updated. |
| type_id int The internal flag type ID that will be created or updated. |
| You will need to specify the ``type_id`` if more than one |
| flag type of the same name exists. |
| **status** string The flags new status (i.e. "?", "+", "-" or "X" to clear a |
| flag). |
| requestee string The login of the requestee if the flag type is requestable |
| to a specific user. |
| id int Use ID to specify the flag to be updated. You will need to |
| specify the ``id`` if more than one flag is set of the same |
| name. |
| new boolean Set to true if you specifically want a new flag to be |
| created. |
| ========== ======= ============================================================ |
| |
| **Response** |
| |
| .. code-block:: js |
| |
| { |
| "bugs" : [ |
| { |
| "alias" : [], |
| "changes" : { |
| "keywords" : { |
| "added" : "funny, stupid", |
| "removed" : "" |
| }, |
| "status" : { |
| "added" : "IN_PROGRESS", |
| "removed" : "CONFIRMED" |
| } |
| }, |
| "id" : 35, |
| "last_change_time" : "2014-09-29T14:25:35Z" |
| } |
| ] |
| } |
| |
| ``bugs`` (array) This points to an array of objects with the following items: |
| |
| ================ ======== ===================================================== |
| name type description |
| ================ ======== ===================================================== |
| id int The ID of the bug that was updated. |
| alias array The aliases of the bug that was updated, if this bug |
| has any alias. |
| last_change_time datetime The exact time that this update was done at, for |
| this bug. If no update was done (that is, no fields |
| had their values changed and no comment was added) |
| then this will instead be the last time the bug was |
| updated. |
| changes object The changes that were actually done on this bug. The |
| keys are the names of the fields that were changed, |
| and the values are an object with two keys: |
| |
| * ``added`` (string) The values that were added to |
| this field, possibly a comma-and-space-separated |
| list if multiple values were added. |
| * ``removed`` (string) The values that were removed |
| from this field, possibly a |
| comma-and-space-separated list if multiple values |
| were removed. |
| ================ ======== ===================================================== |
| |
| Currently, some fields are not tracked in changes: ``comment``, |
| ``comment_is_private``, and ``work_time``. This means that they will not |
| show up in the return value even if they were successfully updated. |
| This may change in a future version of Bugzilla. |
