View source for QA/Community/QMO Bugzilla/Documentation

= About =
The Bugzilla Dashboard module is useful for setting up queries that will be generated automatically at cron runs.
== Why use it ==
If you want to set up a Bugzilla query to run over a set period of time, at a given frequency, and pick up on specific data to display in a chart, this is the module for you.
== What it can do ==
The module can generate 3 types of charts (for now):
* (Time)line charts - a series of lines spanning over time
* Bar charts
* Pie charts
The last 2 are not time-oriented but can self-update as often as you set them. Say, if you just want to see the # of bugs over last week per severity level and don't care about previous weeks.
== Limitations ==
There are many limitations to the module as yet, many of which can be adjusted as needed. The following are the most important limitations noted so far:
* Large periods of time/large # of bugs.
* Reusing the same queries for multiple charts
Mostly, they relate to large amounts of data needed over a short period of time (the classic problem when gathering data!)

= Tutorial =
The following info should help you with using the Bugzilla Dashboard module.
== Creating a chart ==
=== Basic setup ===
* Chart type (can be changed at any time)
* Title - this will be most useful in identifying the chart
* Description
* Path alias - drupal path alias to access the chart
* Height & Width - used on the individual chart page only.
* Order - you can order the bars or slices of pie by label or count. Since labels are not allowed to be duplicates, they can only be ordered in 2 ways. Counts can be duplicates so they can be ordered 4 ways concurrent with the label.

=== My Dashboard settings: ===
* Select Weight and Pages for the chart
* Own charts must be added (checkbox disabled), shared charts can optionally be added to pages.
* The chart will be included on one or more of the pages you select
* People can view your charts by accessing the same dashboard page.

=== Sharing ===
* Share with selected user roles - each role will be able to view the chart and even edit it (if the role has permissions to do so)
* For other users to also use these shared charts, they can to go to the "Manage Charts" page and add the chart to their charts.

=== Active time interval ===
* The chart will be ignored by cron if the current time is outside this interval.
* (todo) Input "Now" (or maybe 00:...) at either end to keep active
=== Queries (the big thing). For each query ===
* Show total - show the total count at the given URL in a chart or not: MUST be selected if mapping is not selected and the query is enabled (I will merge the two checkboxes).
* Enabled - run this query when chart is run
* Title - the best way to identify this query.
* Description
* '''URL''' (XML type - ctype=rdf - automatically added if not present)
* '''Frequency'''
* Mapping

=== More about mapping ===
Feedback shows this is the hardest feature for people to understand. Admittedly it takes a learning curve to get it, but here are the basics:
* The backend - the XML
** The module will look at an XML document. This XML document has a tree structure. Each bug is contained within a BZ:BUG tag, with its fields: BZ:ID, BZ:BUG_SEVERITY, etc. Bugs are parsed one by one and counted.
** The parser only looks at the ID tag (which is stored so you can see which bugs matched what you wanted), and any additional columns you specify in the "Mapping" textarea. So, if you want to separate these bugs by severity, you put in BZ:BUG_SEVERITY as a column on the first row in the textarea.
* The mapping process
** Basically, it means mapping a sequence of values to a specific label. A many-to-one function. For example, if you want to map bugs to specific Mozilla Teams by Product and Component values: say, Layout belongs to the Gfx Team, JS Engine to the webdev team (I might be wrong on this). To do this, you look at the combination of values for the Product and Component fields and decide where it falls based on that. "Where it falls" is the label you give it, the function value, and Product and Component are the function parameters. That's how mapping works too.
** Formatting: After you used the first row to specify the columns you want to look at for bugs, you can use the 2nd, 3rd (and on) rows to group bugs. The first row that matches over all specified columns will count. For each bug, the parser goes through the mapping and looks at the combination of column values.

Below are examples, some are taken from the [[QA/Community/QMO_Bugzilla#Bugzilla_feedback]] page. These use the "best practices" described below in 'About the "Mapping" textarea'.

1) # of fixed bugs over last week, by component, only for the Firefox product.
Option 1 (preferred):
  BZ:COMPONENT

* Umatched values: Show each as distinct.
* Query gets only fixed bugs for the Firefox product over last week

Option 2 (less efficient):
  BZ:PRODUCT|BZ:RESOLUTION|BZ:COMPONENT
  Firefox|Fixed|JavaScript Engine|JS Engine
  Firefox|Fixed|Add-ons|Add-ons
  ...
  Firefox|Fixed|Layout|Layout

* Umatched values: Don't show.
* Query gets all bugs over last week

2) # of blocker bugs by component over last week
  BZ:COMPONENT
(empty from 2nd row on)

* Umatched values: Show each as distinct
* Query gets only blocker bugs.

3) # of blocker bugs by product AND component over last week
  BZ:PRODUCT|BZ:COMPONENT
(empty from 2nd row on)

* Umatched values: Show each as distinct
* Query gets only blocker bugs.

4) # of bugs over grouped BZ:PRODUCT|BZ:COMPONENT combinations
  BZ:PRODUCT|BZ:COMPONENT
  Core|Layout*|Gfx team
  Firefox|CSS Styles|Gfx team
  Firefox|JavaScript Engine|JS bugs
  ... (any other combination of the two)| (any label).

The two Core+Layout* and Firefox+CSS Styles will add up for the Gfx team label, so you can group multiple values to the same value.
* Umatched values: Don't show.
* Query gets all bugs over last week

For the above (and in general when using mapping):
* Show total: NO (uncheck box)
* The query URL used will contain the bugs filed within the last week (-7d) and its frequency will be weekly. (0000-00-07 00:00:00)  

==== Fields ====
* Map tag values = enable/disable mapping
* Unmatched values - select what to do with unmatched values
* Mapping
==== About the "Mapping" textarea ====
* Map values of multiple columns to one label (many to one)
* Can reuse the same label for different values (on different rows)
* Uses php's [http://us.php.net/preg_match preg_match()] function on each value. That means regular expressions. Read about php regular expressions [http://www.regular-expressions.info/php.html here].
* Mapping is done from top to bottom: first row that is a complete match gets counted, no subsequent matching is counted. (So if you put in an example that matches everything up first, the rows following it will practically be ignored)
* Any columns included in the first row will be parsed, so minimizing the number of columns reduces parse time.
* How to order rows: order from most frequent matches (top) to least frequent (bottom). Then the matcher has to go through less rows.
* How to order columns: order from least frequent matches (left) to most frequent matches (like matches of everyting (.*)) (right). Then the matcher knows that row isn't a match sooner and moves on to the next one.

== Importing/Exporting ==
=== Importing charts ===
The format is a serialized array of charts. The array structure looks like this:

$charts - array, where
  $charts[$i] - chart #i object with fields title, description, type, etc
  $charts[$i]['q'][$j] - query #j for each chart (#i), with fields url, mapping, etc
  $charts[$i]['q'][$j]['r'][$k] - result #k for each query #j for each chart #i, with fields bugs, count, label, etc

Importing should not be allowed for most users, as it is a massive dump of charts into a database. Also, there is no input validation - as long as the unserialize() process passes, anything can be inserted into the database.

Read about serialize() and unserialize() here:
* http://us2.php.net/serialize
* http://us2.php.net/unserialize

= Sharing pages =
* Your pages are located under qmo_bugzilla/user/[user-id]/[pagenum] (would it be better at [username]/[pagenum]?)
* Other users have their pages at a different [user-id].
* When viewing other users' pages, you are only able to see the charts on those pages that have been shared with you. Also, you are unable to change the # of rows, columns, or weights of the charts. You may be able to edit shared charts.
* Therefore, each user has full control of his/her pages.

= Managing charts =
* Advanced search for easily finding a chart
* Mass editing of charts by changing their type, removing their path alias, adding or removing them to your charts, etc.

= How it all works =
Once you create a chart, the next most important step is it being run (either by you, or at cron - if cron is set up). The run process picks up all the queries for each chart and looks at the URLs. It uses php and curl to get the XML data from the URL and parses it according to the other options you set in the chart info. The results are saved in a table in the database.

For Timeplot (line) charts: multiple runs create multiple sets of results. They need two external files to fetch the data from: one for the counts, and one for the events (the blue thin vertical lines that you can click on).
For Bar/Pie charts: every run drops previous results for each query. There is an option in the administration of the module to prevent this, but it's very wasteful in storage to keep old data around. The only reason you would want to keep it is if you plan to allow people to change chart types at anytime. Anyway, the option is there.

On viewing the chart: data is fetched from the local results table (or the two files in a Timeplot chart's case), and so every view requires little activity, database activity in particular (almost none for Timeplot charts).

= QA Team Feedback =
{| class="fullwidth-table"
| style="background:#efefef" | '''Name'''
| style="background:#efefef" | '''Ideas, Suggestions, Possible bugs'''
|- 
| <name>
| <feedback>
|- 
| juanb
| Lack of a "login" button elicits confusion (me); a little unintuitive: if we ask even a savvy person to check it out, he/she won't figure out what we are doing here.
|-
| mw22
| Like juanb, lack of a "login" button confuses me a bit. Also, it would be nice to have a date widget for the input of dates (I think there are already some bugs that have patches about a date widget, perhaps you could use those). The whole "mapping" thing, I don't understand at all. Explanation of that feature would really help. Also, it would be nice the top showed "Account of mw22" instead of "My account". I tried to run a query at http://qmo2.wittyletter.com/qmo_bugzilla/chart/7/run but I get an "Access denied".
|-
|bc
|Delete chart doesn't work. I am confused about mapping. I was trying to create a line chart of open js bugs with a line for each status (unconfirmed, new, assigned, reopened) but I just don't get it. 
|}
Some particular areas of interest:
* UI/Ease of use
* Very important features that aren't there but should be
* If it is all just too complicated, suggestions on simplifying it
* Bugs