-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME
182 lines (144 loc) · 8.45 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
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!