<<

# bz_webservice_demo.pl

- NAME
- SYNOPSIS
- OPTIONS
- DESCRIPTION
  - Initialization
  - Debugging
  - Checking Bugzilla's version
  - Checking Bugzilla's timezone
  - Logging In and Out
    - Using Bugzilla's Environment Authentication
    - Using Bugzilla's CGI Variable Authentication
  - Getting Extension Information
  - Retrieving Bug Information
  - Retrieving Product Information
  - Creating A Bug
  - Getting Legal Field Values
  - Adding a comment to a bug
- NOTES
  - Character Set Encoding
  - Format For Create File
- SEE ALSO

# NAME

bz_webservice_demo.pl - Show how to talk to Bugzilla via XMLRPC

# SYNOPSIS

`bz_webservice_demo.pl [options]`

`bz_webservice_demo.pl --help` for detailed help

# OPTIONS

--help, -h, -?

  Print a short help message and exit.

--uri

  URI to Bugzilla's `xmlrpc.cgi` script, along the lines of `http://your.bugzilla.installation/path/to/bugzilla/xmlrpc.cgi`.

--login

  Bugzilla login name. Specify this together with --password in order to log in.

  Specify this without a value in order to log out.

--password

  Bugzilla password. Specify this together with --login in order to log in.

--restrictlogin

  Gives access to Bugzilla's "Bugzilla_restrictlogin" option. Specify this option while logging in to restrict the login token to be only valid from the IP address which called Don't specify this option to do the same thing as unchecking the box.

  See Bugzilla's restrictlogin parameter for details.

--bug_id

  Pass a bug ID to have `bz_webservice_demo.pl` do some bug-related test calls.

--product_name

  Pass a product name to have `bz_webservice_demo.pl` do some product-related test calls.

--create

  Specify a file that contains settings for the creating of a new bug.

--field

  Pass a field name to get legal values for this field. It must be either a global select field (such as bug_status, resolution, rep_platform, op_sys, priority, bug_severity) or a custom select field.

--comment

  A comment to add to a bug identified by --bug_id. You must also pass a --login and --password to log in to Bugzilla.

--private

  An optional non-zero value to specify --comment as private.

--worktime

  An optional double precision number specifying the work time for --comment.

--extension_info

  If specified on the command line, the script returns the information about the extensions that are installed.

--debug

  Enable tracing at the debug level of XMLRPC requests and responses.

# DESCRIPTION

## Initialization

Using the XMLRPC::Lite class, you set up a proxy, as shown in this script. Bugzilla's XMLRPC URI ends in `xmlrpc.cgi`, so your URI looks along the lines of `http://your.bugzilla.installation/path/to/bugzilla/xmlrpc.cgi`.

## Debugging

Enable tracing at the debug level of XMLRPC requests and responses if requested.

## Checking Bugzilla's version

To make sure the Bugzilla you're connecting to supports the methods you wish to call, you may want to compare the result of `Bugzilla.version` to the minimum required version your application needs.

## Checking Bugzilla's timezone

To make sure that you understand the dates and times that Bugzilla returns to you, you may want to call `Bugzilla.timezone`.

## Logging In and Out

### Using Bugzilla's Environment Authentication

Use a `http://login:password@your.bugzilla.installation/path/to/bugzilla/xmlrpc.cgi` style URI. You don't log out if you're using this kind of authentication.

### Using Bugzilla's CGI Variable Authentication

Use the `User.login` and `User.logout` calls to log in and out, as shown in this script.

The `Bugzilla_restrictlogin` parameter is optional. If omitted, Bugzilla's defaults apply (as specified by its `restrictlogin` parameter).

## Getting Extension Information

Returns all the information any extensions have decided to provide to the webservice.

## Retrieving Bug Information

Call `Bug.get` with the ID of the bug you want to know more of. The call will return a `Bugzilla::Bug` object.

Note: You can also use "Bug.get_bugs" for compatibility with Bugzilla 3.0 API.

## Retrieving Product Information

Call `Product.get` with the name of the product you want to know more of. The call will return a `Bugzilla::Product` object.

## Creating A Bug

Call `Bug.create` with the settings read from the file indicated on the command line. The file must contain a valid anonymous hash to use as argument for the call to `Bug.create`. The call will return a hash with a bug id for the newly created bug.

## Getting Legal Field Values

Call `Bug.legal_values` with the name of the field (including custom select fields). The call will return a reference to an array with the list of legal values for this field.

## Adding a comment to a bug

Call `Bug.add_comment` with the bug id, the comment text, and optionally the number of hours you worked on the bug, and a boolean indicating if the comment is private or not.

# NOTES

## Character Set Encoding

Make sure that your application either uses the same character set encoding as Bugzilla does, or that it converts correspondingly when using the web service API. By default, Bugzilla uses UTF-8 as its character set encoding.

## Format For Create File

The create format file is a piece of Perl code, that should look something like this:

        {
            product     => "TestProduct",
            component   => "TestComponent",
            summary     => "TestBug - created from bz_webservice_demo.pl",
            version     => "unspecified",
            description => "This is a description of the bug... hohoho",
            op_sys      => "All",
            platform    => "All",
            priority    => "P4",
            severity    => "normal"
        };

# SEE ALSO

There are code comments in `bz_webservice_demo.pl` which might be of further help to you.

<<