Bugzilla XML-RPC Javascript API

About

download: bugzillaRPC.js

This is a Javascript API that wraps several of the methods exposed via the Bugzilla XML-RPC interface. In particular, it wraps the functionality of the Bug.create, Bug.get_bugs, Bug.legal_values, User.login, User.logout, and User.offer_account_by_email methods from the API. In addition, it adds a method for advanced searching by term.

The API is a js object, bugzillaRPC, that is contained in a single js file. Unfortunately, it's only for use by code with chrome privileges right now as it uses cross-site XHR which is not currently allowed by the bugzilla.mozilla.org server.

To call a method of the API, simply call bugzillaRPC.methodName. If a method returned a struct in the XML-RPC interface, then it will return a js hash in this library. Similarly for arrays and values. All methods require a callback and an error callback. If there is an error (from the connection or from an illegal argument, etc.) then the error callback will be called with the error message (the faultString from the XML-RPC call if it's a logical error). Otherwise, the callback will be called with the return value.

API

getBug

Retrieves an object with a bug's information given an id

parameters:

• id - the id of the bug
• callback - the callback function to populate with the returned bug info
• errback - callback that is called upon error (connection or logical)

success parameter:

• bug - object defined by Bugzilla XML-RPC's getBugs return value. with properties id, summary, creation_time, last_change_time, and the internals object which has various other properties.

example:

bugzillaRPC.getBug(48875,
                        function(bug) {alert(bug.summary);},
                        function(errMsg) {alert(errMsg)});

getBugs

Retrieves an array of bug objects

parameters:

• ids - an array of bug ids
• callback
• errback

success parameter:

• bugs - An array of objects defined by Bugzilla XML-RPC's getBugs return value. with properties id, summary, creation_time, last_change_time, and the internals object which has various other properties.

example:

bugzillaRPC.getBugs([8117, 2344],
                        function(bugs) {alert(bugs[0].summary);},
                        function(errMsg) {alert(errMsg)});

advancedSearch

Retrieves an array of bug objects based on advanced search parameters.

parameters:

• params - a hash of parameters for the buglist query - same parameters as are passed as GET parameters to buglist.cgi.
• callback
• errback

success parameter:

• bugs - An array of objects defined by Bugzilla XML-RPC's getBugs return value. with properties id, summary, creation_time, last_change_time, and the internals object which has various other properties.

example:

bugzillaRPC.advancedSearch({ short_desc_type: 'allwordssubstr',
                          short_desc: 'window+should+close',
                          component: 'general'},
                        function(bugs) {alert(bugs[0].summary);
                        function(errMsg) {alert(errMsg)});

fastAdvancedSearch

Similar to advancedSearch, but only retrieves the id and summary of each bug. This is about twice as fast as fastAdvancedSearch.

parameters:

• params - a hash of parameters for the buglist query - same parameters as are passed as GET parameters to buglist.cgi.
• callback
• errback

success parameter:

• bugs - An array of objects defined, each with properties id and summary.

example:

bugzillaRPC.advancedSearch({ short_desc_type: 'allwordssubstr',
                          short_desc: 'window+should+close',
                          component: 'general'},
                        function(bugs) {alert(bugs[0].summary);
                        function(errMsg) {alert(errMsg)});

login

Authenticates a Bugzilla user for future API calls.

parameters:

• login - the user's login name
• password - the user's password
• callback
• errback

success parameter:

• id - the id of the logged in user

example:

bugzillaRPC.login('test@company.com', 'mypassword'
                        function(id) {alert('user ' + id + 'logged in');
                        function(errMsg) {alert(errMsg)});

logout

Logs out the currently logged in user.

parameters:

• callback
• errback

success parameter: -

example:

bugzillaRPC.logout(function() {alert('logged out');
                         function(errMsg) {alert(errMsg)});

createBug

creates a bug in the specified product and component.

parameters:

• params - a hash of parameters used to create the bug - specified in the XML-RPC interface function create. The hash must have members product, component, version, op_sys, platform, summary, and description.
• callback
• errback

success parameter:

• id - the id of the newly created bug

example:

bugzillaRPC.createBug({product: 'Test Prod',
                            component: 'Test Comp',
                            version: '1.0',
                            op_sys: 'Linux',
                            platform: 'PC',
                            summary: 'window doesn't close',
                            description: 'it just won't close',
                            },
                         function(id) {alert('Bug' + id + 'created');}
                         function(errMsg) {alert(errMsg);} );

legalValues

Retrieves a list of the valid values of a field.

parameters:

• field - the field to find legal values for
• product - the product (optional)
• callback
• errback

success parameter:

• values - an array of legal values for the field

example:

bugzillaRPC.legalValues('status', 'Firefox'
                        function(values) {alert('can have value' + values[0]);},
                        function(errMsg) {alert(errMsg)});

offerAccount

Sends an email offering a Bugzilla account.

parameters:

• email - the email to send the account offer to
• callback
• errback

success parameter: -

example:

bugzillaRPC.offerAccount('test@company.com',
                        function() {alert('email sent');
                        function(errMsg) {alert(errMsg)});