AZ-Reporter by Oladon; email me at [email protected], or catch me on 
Freenode as Oladon.

I. CONTENTS
-------------------------------------------------------------------------------
I. CONTENTS
II. INTRODUCTION
III. CONFIGURATION
IV. GETTING STARTED
V. OUTPUT & USAGE
VI. BUG REPORTING, FEATURE SUGGESTIONS, PATCHING


II. INTRODUCTION
-------------------------------------------------------------------------------

This repository contains one file, az_reporter.pl, which connects to the 
AgileZen API and pulls down all the data on a project. It then creates some 
hashes with various statistics about the cards and work, aggregating the 
data as it goes.

If this is your first time using it, skip down to "GETTING STARTED"; the 
section titled "CONFIGURATION" is meant as a reference.


III. CONFIGURATION
-------------------------------------------------------------------------------

The variables in the ### User configuration ### section are explained below.

$apikey -- This is the API key you generate from within your AgileZen account.

$projectid -- This is your project's numeric ID. You can extract it from your 
              logged-in URL (i.e. https://agilezen.com/project/<id>)

$url -- This probably won't need changing, unless AgileZen changes it on their 
        end; it's the entire URL the script uses to get the data via the API.

$outputdir -- Any files created/modified by the script will be in this dir.

%ignored_phases -- Any keys with values of 1 will not be included in any of 
                   the script's aggregated data.

%ignored_statuses -- Similar to ignored_phases, but with statuses. Statuses at 
                     time of writing are: planned, started, ready, blocked, 
                     and finished

%ignored_steps -- similar to the previous two. Steps at time of writing are: 
                  backlog, working, ready, blocked, and archive

%reports -- This hash contains all the reports that can be run using this 
            script (right now just three). New reports can be added as elements 
            of this hash, and should include a "code" key which points to the 
            subroutine to use as the aggregation code for the report.

%tag_groups -- You can define as many tag groups as you like; the script will 
               run each group's reports separately. The colors will correspond 
               to the statuses or steps in the graph (if used). The "colors" 
               value in %tag_groups will override that in %reports, if present.


IV. GETTING STARTED
-------------------------------------------------------------------------------

The script will need some configuration before it will work for your project, 
but it's designed to be as easy to set up as possible while still retaining a 
large degree of flexibility.

1. Set up your API Key and project ID
   To start with, you'll need to set up your API key and project ID in the 
$apikey and $projectid variables (respectively). If you don't have an API key, 
you'll need to set one up by following the directions on AgileZen's site. You 
can get your project ID from the URL -- it's the number between "project/" and 
"/board" if you're on the Board view.

2. Set up Output Directory
   Next, set up the $outputdir variable with the directory you'd like the 
script to use for generated output (such as graphs and/or data files [in the 
future]). Make sure the directory exists and the script has permission to write 
to it!

3. Customize Tag Groups
   At this point, you're ready to customize which graphs the script creates. 
The default setup has four "tag groups," which are collections of tags that 
should be grouped for various reports. You should change the tag names (the 
"tag" value in each tag group) to reflect the tags you're using in your 
project. For example, if you wanted to use "suggestion" in addition to 
"request", you would change the %tag_groups definition to:

%tag_groups = ("all" => {"reports" => {"counts" => 1,
                                       "throughput" => 1},
                         "tags" => ["all"]},
               "standard" => {"reports" => {"averages" => 1},
                              "tags" => ["bug", "feature"]},
               "nonstandard" => {"reports" => {"averages" => 1},
                                 "tags" => ["request", "suggestion"]},
               "custom" => {"reports" => {"averages" => 1},
                            "tags" => ["custom"]});

You can remove groups, add them, and modify them as required by your project; 
a tag value of "all" will be interpreted as all tags, not a literal label of 
"all". In the case of the above code, there will be four report groups: one 
will run the "counts" and "throughput" reports on all the cards regardless of 
tag. The second, third, and fourth will run the "averages" report on their 
respective tag groups ("bug" and "feature", "request" and "suggestion", and 
"custom" [three different groups]). Note that there's nothing special about 
having two tags; a group can have as many tags as you need.

4. Set up Ignored Phases/Steps/Statuses
   By default, the reports will ignore cards currently in phases called 
"Backlog" or "Archive" (you should change these if your phases are named 
differently, or remove them if you don't want to exclude any cards), as well as 
cards whose current step is "backlog" or "archive". The step names can only be 
changed by AgileZen -- if they change them, you'll need to change them in the 
code. As of the time of this writing (1/30/2012), step and status names are:

Step        Corresponding Status
-------     --------------------
backlog     planned
working     started
ready       ready
blocked     blocked
archive     finished

You can add any of these to the "ignored" list by setting it as shown in the 
default code. Again, there's no magic number -- but you'll need to have at 
least one card in a non-ignored phase/step/status, or you won't get anything 
useful from the script.

5. Run the code!
   The code doesn't need any arguments -- you can just run it, using either 
"perl az_reporter.pl" or "./az_reporter.pl" (if it's executable, as it should 
be). If you get any errors, read the error carefully and if you can't solve 
the problem, shoot me an email or PM me on IRC.

V. OUTPUT & USAGE
-------------------------------------------------------------------------------

The output of this script will be a number of JavaScript (.js) files equal to 
the number of reports the script is set to run. Each JavaScript file contains 
the code for a single Google Visualizations chart. At this time (1/30/2012), 
a Google Visualizations stacked (and optionally clustered) bar chart is the 
only graph type supported; in the future, support is planned for other graphs 
as well as a "raw data" output format which could be used with other graphing 
software for an even more customizable approach.

In order to display the graphs, you'll need to create an HTML file with the 
JavaScript files included and relevant divs created for each. For example, the 
following code will be a site with five graphs generated by this script:

<html>
  <head>
    <script type="text/javascript" src="http://www.google.com/jsapi"></script>
    <script type="text/javascript" src="/path/to/your/output/directory/averages_standard.js"></script>
    <script type="text/javascript" src="/path/to/your/output/directory/averages_nonstandard.js"></script>
    <script type="text/javascript" src="/path/to/your/output/directory/averages_custom.js"></script>
    <script type="text/javascript" src="/path/to/your/output/directory/counts_all.js"></script>
    <script type="text/javascript" src="/path/to/your/output/directory/throughput_0.js"></script>
  </head>
  <body>
    <div id="averages_standard_visualization"></div>
    <div id="averages_nonstandard_visualization"></div>
    <div id="averages_custom_visualization"></div>
    <div id="counts_all_visualization"></div>
    <div id="throughput_0_visualization"></div>
  </body>
</html>

NOTE: The names of the files and div ids are set by the script and will follow 
the pattern "<report>_<taggroup>". For div ids, that name will be followed by 
"_visualization". If you aren't seeing a graph in your HTML file, double-check 
that the div and script names follow the convention above.


VI. BUG REPORTING, FEATURE SUGGESTIONS, PATCHING
-------------------------------------------------------------------------------

Email: [email protected]
Freenode: Oladon

Feel free to email/message me with any questions, comments, or suggestions; 
patches that extend or fix functionality are also welcome!