5.7.198. Bugzilla::Extension::RedHat::WebService::Bugzilla¶

5.7.198.1. NAME¶

Bugzilla::Extension::RedHat::WebService::Bugzilla - Red Hat specific XMLRPC methods

5.7.198.2. DESCRIPTION¶

This module provides methods that are Red Hat customisations.

Method calls are normally in the form of namespace.method(arguments). Where namespace in this case is “RedHat”. So for example RedHat.getBug(bugid, username, password) would return the results of getBug() for bug id $bugid.

5.7.198.3. METHODS¶

product_create_objects¶

Used to create a milestone, release or version object in a product or products

Pass in a single hash named ‘data’. This hash must contain an array of hashes for each product that will have milestones, releases or versions created against it

Below is the keys to be included in the array of hashes.

name

string The name of the product that will be modified. Either the name or ID of the product must be specified

integer The ID of the product that will be modified. Either the name or ID of the product must be specified

versions

array-of-hashes optional An array of hashes describing each milestone to be created. The arguments for the versions hash is detailed below

name

string The name of the version

milestones

array-of-hashes optional An array of hashes describing each milestone to be created. The arguments for the versions hash is detailed below

name

string The name of the milestone

sortkey

integer optional The sort order of the milestone

default

boolean optional True if you wish this to be the new default milestone

releases

array-of-hashes optional An array of hashes describing each release to be created. The arguments for the release hash is detailed below

name

string The name of the release

sortkey

integer optional The sort order of this release

default

boolean optional True if you want this to be the new default

product_update_objects¶

Update a set of product milestones, releases and version

versions

array optional A hash named versions contaning an array of hashes that describes each version to be updated. The arguments for each version hash are detailed below

id

integer The ID of the version to be updated.

name

string optional The new name of the version.

is_active

boolean optional True to enable the version, False to disable.

milestones

array optional An array of hashes describing each milestone to be updated. One hash per milestone. The arguments for each version hash are detailed below

id

integer The ID of the milestone to be updated

name

string optional The new name of the milestone

sortkey

integer optional The sort order of the milestone

default

boolean optional set to true to make this the new default milestone.

is_active

boolean optional True to enable the milestone, False to disable.

releases

array optional An array of hashes describing each release to be updated. One hash per release The arguments for each hash are detailed below

id

integer The ID of the release to be updated

name

string optional The new name of the release

sortkey

integer optional The sort order of this release

default

boolean optional Set to true to make this the default release.

is_active

boolean optional True to enable the release, False to disable.

product_get_objects¶

Returns all the versions, milestones and releases for the specified products

Arguments to this function are a list of product names and/or product ids

Params¶

names

array-of-strings optional An array of strings of the product names.

array-of-integers optional An array of product ids

Returns¶

Returns an array of hashes, one per product describing each version, milestone and component in the product

name

string The product name

integer The product id

versions

A hash named versions that contains an array of hashes describing each version in the product

name

string The version name

id

integer The version ID

is_active

integer 1 if the version is active, 0 if inactive

milestones

A hash named milestones that contains an array of hashes describing each milestone in the product

name

string The milestone name

id

integer The milestone ID

is_active

integer 1 if the milestone is active, 0 if inactive

default

integer 1 if this milestone is the default. Will not be present if this is not the default

releases

name

string The release name

id

integer The release ID

is_active

integer 1 if the release is active, 0 if inactive

default

integer 1 if this release is the default. Will not be present if this is not the default

product_delete_objects¶

Delete a version, milestone or release.

Params¶

versions

array optional An array of version ids that should be deleted.

milestones

array optional An array of milestone ids that should be deleted.

releases

array optional An array of release ids that should be deleted.

search_as¶

Convert a URI query string in to an RPC call.

Params¶

format

string The format required, perl or json.

string The search string to convert.

can_delete_user¶

Report if a user can be deleted and if not, why not.

Params¶

names

array of user names to check.

Returns¶

Returns an array of hashes, one per user reported on. Each hash contains:

name

string The user name

int The user name

bool Can the user be deleted?

not_ok_to_delete

hash A hash of counts of things that can prevent deletion.

ok_to_delete

hash A hash of counts of things that cannot prevent deletion.

delete_user¶

Delete some users.

Users will only be deleted if the pass can_delete_user.

Params¶

names

array The user names to delete.

Returns¶

Returns an array of hashes, one per user deleted on.

terminate_sessions¶

Terminate sessions for users.

You must be in the admin group to use this API.

Params¶

sessions

array of hashes with name and ids of sessions to terminate.

{
  'sessions' =>
    [
      {
        'name' =>'fu@example.com',
        'ids'  => [11,56,78]
      },
      {
        'name' => 'bar@example.com',
        'ids'  => [34, 42]
      },
    ]
}

Returns¶

Returns a hash, with the user name as the key, which contains an array of sessions terminated.

{
  'terminated' =>
    {
      'fu@example.com'  => [11,56,78],
      'bar@example.com' => [34, 42],
    }
}

admin_apikeys¶

Ban and revoke APIKEYs for users.

You must be in the admin group to use this API.

Params¶

apikeys

array of hashes with name and ids of APIKEYs to ban or revoke.

{
  'apikeys' =>
    [
      {
        'name'        => 'fu@example.com',
        'banned_ids'  => [11,56],
        'revoked_ids' => [78]
      },
      {
        'name'        => 'bar@example.com',
        'banned_ids'  => [34, 42]
      },
    ]
}

Returns¶

Returns an array of hashes for APIKEYs that have been banned or revoked.

[
  {
    'name'        => 'fu@example.com',
    'banned_ids'  => [11,56],
    'revoked_ids' => [78]
  },
  {
    'name'       => 'bar@example.com',
    'banned_ids' => [34, 42],
  }
]

edit_comment¶

Edit a comment on a bug.

The rules for this are

A security or admin user can edit any comment.
A security or admin user can hide previous comment revisions when editing a comment.
A reporter may edit the description, comment 0, on their bugs.
A user with editbugs privileges on a product may edit the description comment of bugs in that product.

When an edit is made an entry is added to the bugs_activity table indicating who made the change and what comment number was updated. The text of the change is not included in this entry. When a user views the bug history, either on the bug history page or when using the inline history feature, they will be able to see who edited a comment and when, but not the change made.

The texts are stored in a separate table and when entries from this table are viewed the ACLs are applied. If you lack the authorization to see a change then the text will be replaced with the string REDACTED.

The security flag is retroactive, it hides all previous revisions of a comment.

Ths feature is accessed in the UI on the bug edit page by clicking the edit icon in the comment header. If you cannot see this icon on a comment then you do not have permission to edit that comment.

The security flag is set in the UI by selecting the Hide history checkbox on the edit form. If you cannot see this checkbox then you do not have access to lock the comment history.

If you try and edit a comment or set the security flag and you do not have access to do so the API will throw an error and reject the entire request.

Params¶

comment:: int optional The comment ID. This or bug are required.
bug:: int optional The bug ID. This or comment are required.
number:: int optional The comment number on a bug to update. This is only used if bug is supplied. Defaults to zero.
text:: string The text to change the comment to.
security:: boolean optional Hide previous versions of this comment due to security concerns. Note: You need to be in the admin or security groups to set this parameter
minor_update:: boolean optional If set to true, this is considered a minor update and no mail is sent to users who do not want minor update emails.
render:: boolean optional Return the rendered HTML for this comment.

Returns¶

Returns a hash, containing:

activity_count:: int The number of times the comment has been edited.
delta_ts:: bool The new last changed time stamp for the bug.
longdesc:: array A array of 2 things. The first is the comment number on the bug. The second is what happened to the comment. Currently only ‘updated’. This text will appear in the bug history and inline history if enabled.
html:: string If requested the HTML formatted version of the comment. This is what a user will see when loading the updated comment in the web UI.

Examples¶

JSONRPC call¶

By comment id

{
    "jsonrpc": "2.0",
    "method": "RedHat.edit_comment",
    "id": 2,
    "params": [
      {
        "comment": 13178344,
        "render": 1,
        "security": 0,
        "text": "Description of problem:\nThe old comment is just no good!\nBug 11\n",
      }
    ]
}

By bug id & comment number

{
    "jsonrpc": "2.0",
    "method": "RedHat.edit_comment",
    "id": 3,
    "params": [
      {
        "bug": 42,
        "comment": 3,
        "text": "Description of problem:\nExamples are hard\n",
      }
    ]
}

JSONRPC reply¶

By comment id

{
    "id": 2,
    "error": null,
    "result": {
        "activity_count": 2,
        "delta_ts": "2020-03-06 03:38:50",
        "html": "Description of problem:\nThe old comment is just no good!\n<a href=\"https://bugzilla.redhat.com/show_bug.cgi?id=11\">https://bugzilla.redhat.com/show_bug.cgi?id=11</a>\n"
        "longdesc": [0, "updated"],
    }
}

By bug id & comment number

{
    "id": 3,
    "error": null,
    "result": {
        "activity_count": 4,
        "delta_ts": "2020-03-06 03:38:50",
        "longdesc": [3, "updated"],
    }
}

manage_user_access¶

Manage a user’s account access.

WARNING: The actions you take here will temporarily prevent a user from accessing their account, and can permanently disable the user’s account and make ALL the bugs they opened inaccessible. Ensure you have read this documentation carefully and are sure you know what you are doing before using this functionality.

Things to check¶

Before managing a user’s access you might wish to do one or more of the following:

View the account history:: If the user has groups or has notable changes to their privileges it might give an indication of the accounts status.
View bug activity:: This might indicate the account is doing constructive things that may affect which action you select.
View administration activity:: This might indicate the account is doing administration activity that may affect which action you select.

Params¶

names:: array The user names to manage. If a name does not have an account it will be skipped and a message will be added to the response stating this occurred.
action:: string What action to take on the accounts. See “The values for ‘action’ are:” below for the accepted values and what they achieve.
replacement:: string Account to use to replace the user where required. If this name does not have an account then the nobody account will be used and a message will be added to the response stating this occurred.
message:: string Message to send to user, to put in to the disabled text field, and to enter as a bug comment. This is included in mails sent to the affected user. If you don’t supply a message then a default message naming the user who made the change is used.

The values for ‘action’ are:¶

reconfirm¶

This action forces the user to reconfirm their access by using the forgot password process to reset their password. It takes the following actions:

Changes their password to a random unknown value
Terminates all their sessions
Revokes all their api_keys
Mails the user about the change

revoke¶

This action revokes access, it locks the user’s account and forces them to contact the site administrators to have their account re-enabled. It takes the following actions:

Changes their password to a random unknown value
Terminates all their sessions
Revokes all their api_keys
Disables bug mail
Sets disabled text
Mails the user about the change

remove¶

This action terminates the user’s account. It takes the following actions:

Changes their password to a random unknown value
Terminates all their sessions
Bans all their api_keys
Disables bug mail
Sets disabled text
Removes the user from all groups
Removes bless from all groups
Removes the user from all product responsibilities. Replaces them with the replacement if specified.
Replaces the user with the default contact for assignee/qa/docs on all open bugs
Removes user from CC on all open bugs

Note: Bugs are updated using the job queue so happen after the RPC call has been completed.

redact¶

This action terminates the user’s account as per remove above and obfuscates their name and login. It is not reversible and the account cannot be recovered. It takes the following actions:

All actions from remove
Obfuscates user’s name and login

Note: Bugs are updated using the job queue so happen after the RPC call has been completed.

repudiate¶

This action terminates the user’s account as per remove above, it then moves every bug the user has ever created in to the Spam product. It tags all comments the user has ever made with ‘spam’ and it edits all comments with a standard replacement text. It removes all CC’s and users from roles on these bugs and makes them inaccessible to most users. No mail will be sent for these bug changes.

It is not reversible and the account cannot be recovered. It takes the following actions:

All actions from remove
Moves and locks all bugs the user has created.
Marks all comments the user has made as spam.
Removes all outstanding flag requests the user made.
Removes the user from CC on all bugs.
Deletes all attachments the user created.

Note: Bugs are updated using the job queue so happen after the RPC call has been completed.

Returns¶

Returns an array of hashes, one per user acted on, indexed on the account ID.

Examples¶

JSONRPC call¶

{
    "jsonrpc": "2.0",
    "method": "RedHat.manage_user_access",
    "id": 11,
    "params": [
      {
        "names": ["fu@example.com"],
        "action": "repudiate"
        "message": "No soup for you!",
      }
    ]
}

JSONRPC reply¶

{
    "error": null,
    "result": {
        "users": {
            "42": {
                "account_changes": {
                  "cryptpassword": ["", "hashed_with_SHA-256"],
                  "disable_mail":  [0, 1],
                  "disabledtext":  ["", "No soup for you!"]
                  "groups":        ["", "fedora_contrib,packager",
                  "is_enabled":    [1, 0],
                },
                "counts": {
                    "bugs": 0,
                    "components": 1,
                    "keys_banned": 2,
                    "keys_revoked": 0,
                    "sessions": 1
                    "spam_bugs": 3,
                },
                "messages": [
                  "User has been repudiated"
                ]
            }
        }
    },
    "id": 11
}

group_get_products¶

Get a list of all product ACLs for groups.

You must be in the editcomponents group to use this API.

Params¶

groups

array of group names to fetch.

Returns¶

Returns a hash, with the group name as the key, which contains a hash of products with the group controls.

Examples¶

JSONRPC call¶

{
     "jsonrpc": "2.0",
     "method": "RedHat.group_get_products",
     "id": 11,
     "params": [
       {
         "groups": ["group_1", "group_2"]
       }
     ]
 }

JSONRPC reply¶

"groups": {
  "group_1": {
    "product fu": {
      "controls": {
        "canconfirm": 0,
        "canedit": 0,
        "editbugs": 1,
        "editcomponents": 0,
        "entry": 0,
        "membercontrol": 0,
        "othercontrol": 0
      }
    }
  },
  "group_2": {
    "product foo": {
      "controls": {
        "canconfirm": 1,
        "canedit": 0,
        "editbugs": 1,
        "editcomponents": 0,
        "entry": 0,
        "membercontrol": 0,
        "othercontrol": 0
      }
    }
  }
}

group_copy_products¶

Copy the product ACLs from one group to another group.

You must be in the editcomponents group to use this API.

This method will not remove ACLs, it will only add ACLs missing from the to group.

Params¶

from

string of the group name to copy ACLs from.

string of the group name to copy ACLs to.

Returns¶

Returns an array of hashes, with the product name as the key, which contains a hash of groups control changes.

Examples¶

JSONRPC call¶

{
     "jsonrpc": "2.0",
     "method": "RedHat.group_copy_products",
     "id": 11,
     "params": [
       {
         "from": "group_1",
         "to": "group_2"
       }
     ]
 }

JSONRPC reply¶

{
  "changes": [
    {
      "product 1": {
          "group_controls": {
            "group_2": {
              "editbugs": {
                "added": "1",
                "removed": "0"
              }
            }
          }
      },
      "id": 35
    }
  ]
}

user_search¶

A fast way to search for users.

You must be logged in to use this API.

The number of results is limited to the site’s max user matches parameter.

Params¶

match

An array of strings to search for.

These will be compared in order to login and real name.

Returns¶

Returns an array of hashes, with the user details.

Examples¶

JSONRPC call¶

{
     "jsonrpc": "2.0",
     "method": "RedHat.user_search",
     "id": 11,
     "params": [
       {
         "match": ["dude"],
       }
     ]
 }

JSONRPC reply¶

{
  "users": [
    {
      "id": 11,
      "name": "dude@example.com",
      "real_name": "Dude McDude",
      "email": "dude@example.com",
      "insider": 0
    }
  ]
}

run_report¶

Run a saved report and return the CSV for it.

Params¶

name:: string The name of the saved report.
bot_owner:: string The name of the bot that owns the report. If not supplied it will use the account of the user requesting the run.

You must have management rights to the bot to set this.

Returns¶

Returns a hash containing the CSV output of the report.

Examples¶

JSONRPC call¶

{
    "jsonrpc": "2.0",
    "method": "RedHat.run_report",
    "id": 11,
    "params": [
      {
        "name": "MyImportantReport"
      }
    ]
}

JSONRPC reply¶

  {
      "error": null,
      "result": {
          "report": '"Component": "Bugzilla General""Target Release / Status","ASSIGNED","ON_DEV","ON_QA","VERIFIED"
" ---",0,0,3,1'
          }
      },
      "id": 11
  }

update_report¶

Update a saved report. You must either own a report or have management rights to the bot that owns a report to use this API call.

Params¶

name:: string The name of the saved report.
bot_owner:: string The name of the bot that owns the report or whom you wish to give ownership to. You must have management rights to the bot to set this.
groups:: array The names of the groups that have view permissions. This allows the members of the named groups to run the report, it does not change what data the report can access. The list provided is set verbatim. If existing groups are missing from the list provided then they will be removed from the report.

Returns¶

Nothing.

Examples¶

JSONRPC call¶

{
    "jsonrpc": "2.0",
    "method": "RedHat.update_report",
    "id": 11,
    "params": [
      {
        "name": "MyImportantReport",
        "groups": ["private", "the_secret_group"],
        "bot_owner": "my_bot@bot.bugzilla.redhat.com"
      }
    ]
}

delete_report¶

Delete a saved report.

Params¶

name:: string The name of the saved report.
bot_owner:: string The name of the bot that owns the report. If not supplied it will use the account of the user requesting the run.

You must have management rights to the bot to set this.

Returns¶

Nothing.

Examples¶

JSONRPC call¶

{
    "jsonrpc": "2.0",
    "method": "RedHat.delete_report",
    "id": 11,
    "params": [
      {
        "name": "MyImportantReport"
      }
    ]
}

delete_jobs¶

Delete jobs from the job queue.

You must be in the admin group to use this API.

Params¶

ids:: array-of-integers The ids of the Jobs to delete.

Returns¶

A hash containing the number of jobs deleted.

Examples¶

JSONRPC call¶

{
    "jsonrpc": "2.0",
    "method": "RedHat.delete_jobs",
    "id": 11,
    "params": [
      {
        "ids": [11, 12, 42]
      }
    ]
}

JSONRPC reply¶

{
    "error": null,
    "result": {
        "deleted_count": 3
    },
    "id": 11
}

view_jobs¶

Delete jobs from the job queue.

You must be in the admin group to use this API.

Params¶

ids:: array-of-integers The ids of the Jobs to delete.

Returns¶

A hash containing the number of jobs deleted.

Examples¶

JSONRPC call¶

{
    "jsonrpc": "2.0",
    "method": "RedHat.view_jobs",
    "id": 11,
    "params": [
      {
        "ids": [42]
      }
    ]
}

JSONRPC reply¶

{
    "error": null,
    "result": {
        "jobs": [{
          "type": "Bugzilla::Extension::RuleEngine::Job",
          "arg": {
              "bug_ids": [101],
              "delta_ts": "2021-10-20 04:38:17",
              "action": "update"
          },
          "jobid": 42
        }]
    },
    "id": 11
}

reschedule_jobs¶

Reset the run_after time for jobs.

You must be in the admin group to use this API.

Params¶

ids:: array-of-integers The ids of the Jobs to reset.

Returns¶

A hash containing the new run_after time and the count of jobs reset.

Examples¶

JSONRPC call¶

{
    "jsonrpc": "2.0",
    "method": "RedHat.reschedule_jobs",
    "id": 11,
    "params": [
      {
        "ids": [11, 12, 42]
      }
    ]
}

JSONRPC reply¶

{
    "error": null,
    "result": {
        "run_after": "???",
        "updated_count": 1
    },
    "id": 11
}

tag_user_comments_as_spam¶

Create a ‘despam_comments’ job to tag all comments a user has made as spam and edit the comment text to say so.

Creates one job per user name supplied.

Users must be inactive and not be a member of any groups. To run this for current users use the repudiate action of manage_user_access.

Params¶

names:: array-of-strings The logins of the users who’s comments are to be marked as spam.

Returns¶

Nothing.

Examples¶

JSONRPC call¶

{
    "jsonrpc": "2.0",
    "method": "RedHat.tag_user_comments_as_spam",
    "id": 1,
    "params": [
      {
        "names": ["fred@example.com", "barry@example.org"]
      }
    ]
}

5.7.198.4. SEE ALSO¶

Bugzilla Bugzilla::WebService Bugzilla::Extension::RedHat

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