215d807a2d159241f7fec7a960803697639c8948
[worg.git] / exporters / taskjuggler / ox-taskjuggler.org
1 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
2 #+STARTUP:    align fold nodlcheck oddeven lognotestate
3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) 
5 #+TITLE:      Exporting Gantt charts with Taskjuggler v3 (tj3)
6 #+AUTHOR:     John Henderson
7 #+EMAIL:      jw DOT hendy AT gmail DOT com
8 #+LANGUAGE:   en
9 #+PRIORITIES: A C B
10 #+CATEGORY:   worg
11
12 [[file:index.org][{Back to Worg's index}]]
13
14
15 * Introduction
16
17 This article discusses the use of [[http://orgmode.org/][Org-mode]] for project planning using [[http://www.taskjuggler.org/][Taskjuggler]],
18 self-described as follows (from the project website):
19
20 #+begin_quote
21 TaskJuggler is a modern and powerful, Free and Open Source Software project management
22 tool. Its new approach to project planning and tracking is more flexible and superior to
23 the commonly used Gantt chart editing tools. 
24 #+end_quote
25
26 A [[http://orgmode.org/worg/org-tutorials/org-taskjuggler.html][tutorial already exists]] for the use of Org-mode and Taskjuggler v2.4.3, the last release of the
27 v2.x.x series. Taskjuggler Version 3 (often referred to as simply "tj3"), was rebuilt using [[http://www.ruby-lang.org/en/][Ruby]], and no
28 longer features the former [[http://qt-project.org/][Qt]]-based GUI for task/timeline management of a project.
29
30 It should also be mentioned that the project is now [[http://www.taskjuggler.org/manual/change_log.html#version_1_0_0][10 years old]], and, as a result, is
31 [[http://taskjuggler.org/tj3/manual/toc.html][fantastically documented]]. 
32
33 The [[http://orgmode.org/manual/TaskJuggler-export.html][Org-mode manual coverage of Taskjuggler]] covers Taskjuggler export to some extent,
34 however the defaults assume the use of version 2.x.x. This tutorial will lay out
35 the changes required to successfully export with tj3.
36
37 * Installation and Setup
38
39 *Preface:* If you have not recently (and successfully) used tj3, it is recommended that you
40 try compiling the example =.tjp= file as described below to rule out any issues with the
41 tj3 installation itself before moving on integrating tj3 with Org mode.
42
43 Please refer to the [[http://taskjuggler.org/tj3/manual/Installation.html#Installation][installation section]] of the Taskjuggler manual for instructions. For
44 the high level overview, you will need to install =ruby= and possibly =ruby-gems=. The
45 easiest method is probably to install =ruby-gems= and simply type, from a
46 terminal/command-line interface (you may need to run this as the =root= user or with =sudo=):
47
48 #+begin_example
49
50 gem install taskjuggler
51
52 #+end_example
53
54 For Linux users, you may have a distro-specific package available if you would rather choose that
55 route. For example, the Arch Linux User Repository ([[https://aur.archlinux.org/][AUR]]) has a [[https://aur.archlinux.org/packages/taskjuggler3/][Taskjuggler 3 package]] available.
56
57 Once installed, you should check functionality by typing:
58
59 #+begin_example 
60
61 tj3 --version
62
63 #+end_example
64
65 If you just can't wait to see what tj3 can do, try compiling their [[http://taskjuggler.org/tj3/examples/Tutorial/tutorial.tjp][sample file]]:
66
67 - Copy/paste into a file called =something.tjp=. Alternatively, 
68
69 #+begin_example
70
71 http://taskjuggler.org/tj3/examples/Tutorial/tutorial.tjp
72
73 #+end_example
74
75 - Save the file and then issue:[fn:1]
76
77 #+begin_example
78
79 $ cd /path/to/something.tjp
80 $ tj3 something.tjp
81
82 #+end_example
83
84 Now check out the generated =Overview.html= in a browser!
85
86 * Using tj3 with Org mode
87
88 To activate the Taskjuggler exporter in Org-mode, add this line to =~/.emacs=:
89
90 #+begin_example
91
92 (require 'ox-taskjuggler)
93
94 #+end_example
95
96 Either restart Emacs or issue =M-x load-file RET ~/.emacs RET= and we're ready to create
97 our project managment =.org= file!
98
99 /This document is a work in progress; more details to come [shortly]!/
100
101 * Footnotes
102
103 [fn:1] You may run into compilation issues due to special characters in that file on
104 lines 37 (a copyright symbol), 79, and 83 (two accented characters in resource names). If
105 this happens, just replace those three characters with something else, or delete them,
106 and the file should compile. [[https://github.com/taskjuggler/TaskJuggler/issues/105][An issue has been filed]] inquiring about whether or not this
107 is a system setup issue and, if not, suggesting that the characters be replaced.
108
109 * TODO Fill in the details!                                        :noexport:
110 ** Plan your project
111 You start out as you normally would by breaking down the project into
112 tasks. Let's take the following example where you have a project to
113 create an accounting software:
114
115 #+BEGIN_SRC org
116 ,* Accounting Software
117
118 ,** Specification
119
120 ,** Software Development
121 ,*** Database coupling
122 ,*** Back-End Functions
123 ,*** Graphical User Interface
124
125 ,** Software testing
126 ,*** Alpha Test
127 ,*** Beta Test
128
129 ,** Manual
130
131 ,** Milestones
132 ,*** Project start
133 ,*** Technology Preview
134 ,*** Beta version
135 ,*** Ship Product to Customer
136 #+END_SRC
137
138 ** Estimate the effort
139 Now that you've figured out the tasks it's time to estimate the
140 efforts for each task. By using column view this can be done very
141 efficiently. It also helps to define the =COLUMNS= and default values
142 for the Effort property as shown in the following screen shot:
143
144 #+CAPTION: Estimating effort using column view 
145 #+ATTR_HTML: alt="Estimating effort using column view"
146 [[file:../images/taskjuggler/effort-estimation.png]]
147
148 Your resulting Org mode project file will look somewhat like the
149 following:
150
151 #+BEGIN_SRC org
152 ,#+PROPERTY: Effort_ALL 2d 5d 10d 20d 30d 35d 50d 
153 ,#+COLUMNS: %70ITEM(Task) %Effort
154
155 ,* Accounting Software
156
157 ,** Specification
158    :PROPERTIES:
159    :Effort:   20d
160    :END:
161
162 ,** Software Development
163
164 ,*** Database coupling
165     :PROPERTIES:
166     :Effort:   20d
167     :END:
168
169 ,*** Back-End Functions
170     :PROPERTIES:
171     :Effort:   30d
172     :END:
173
174 ,*** Graphical User Interface
175     :PROPERTIES:
176     :Effort:   35d
177     :END:
178
179 ,** Software testing
180 ,*** Alpha Test
181     :PROPERTIES:
182     :Effort:   5d
183     :END:
184
185 ,*** Beta Test
186     :PROPERTIES:
187     :Effort:   20d
188     :END:
189
190 ,** Manual
191    :PROPERTIES:
192    :Effort:   50d
193    :END:
194
195 ,** Milestones
196 ,*** Project start
197 ,*** Technology Preview
198 ,*** Beta version
199 ,*** Ship Product to Customer
200 #+END_SRC
201
202 ** Generate a Gantt chart
203 Before you now export the project to TaskJuggler you need to tell the
204 exporter in which tree it can find the tasks. You do this by adding
205 the tag ~taskjuggler_project~ to the node "Accounting Software"[fn:2].
206 Do this by moving to the "Accounting Software" headline and typing the
207 following:
208
209 : C-c C-c taskjuggler_project RET
210
211 This allows you to have other nodes for this project such as an
212 introduction or general notes.
213
214 To export the project to TaskJuggler you simply type 
215
216 : M-x org-export-as-taskjuggler-and-open
217
218 This will open your project in TaskJugglerUI as illustrated below
219
220 #+CAPTION: Gantt chart in TaskJugglerUI
221 #+ATTR_HTML: alt="Gantt chart in TaskJugglerUI"
222 [[file:../images/taskjuggler/TaskJugglerUI1.png]]
223
224 Since we have not assigned any resources to work on the project the
225 exporter assumes that you will be the one working on it and has
226 assigned all tasks to you. The tasks have been serialized so that you
227 will not have to many things to do at once, i.e. the resources will be
228 leveled.
229
230 ** Assign resources
231 The next step is to list all the resources working on the project and
232 assign the tasks to them. Create a node for the resources. You can
233 group the resources by creating hierarchies. Tag the resource tree
234 with the tag ~taskjuggler_resource~ so that the exporter knows where to
235 look for resource definitions[fn:3].
236
237 #+BEGIN_SRC org
238 ,* Resources                                         :taskjuggler_resource:
239 ,** Developers
240    :PROPERTIES:
241    :resource_id: dev
242    :END:
243 ,*** Paul Smith
244     :PROPERTIES:
245     :resource_id: paul
246     :END:
247 ,*** Sébastien Bono
248     :PROPERTIES:
249     :resource_id: seb
250     :END:
251 ,*** Klaus Müller
252
253 ,** Others
254 ,*** Peter Murphy
255     :PROPERTIES:
256     :resource_id: doc
257     :END:
258 ,*** Dim Sung
259     :PROPERTIES:
260     :resource_id: test
261     :END:
262 #+END_SRC
263
264 As you'll note I also added some ~resource_id~ properties to some of
265 the resources (or resource groups). I will use these identifiers to
266 allocate the resources to the tasks. The exporter will create unique
267 ids for the resources automatically[fn:4], but if you want to use
268 short forms it's better to define ~resource_id~ properties for your
269 resources. This will also allow you to define default values for the
270 allocation as follows:
271
272 : #+PROPERTY: allocate_ALL dev doc test
273
274 The easiest way to assign resources is again the column view mode.
275 There is no need to allocate a resource to every task, as allocations
276 are inherited in TaskJuggler[fn:5]. You'll note in the screen shot
277 below that some tasks have more than one resource assigned to them.
278 TaskJuggler will calculate the duration of the task based on the
279 effort and the resources working on this task.
280
281 #+CAPTION: Assign resources
282 #+ATTR_HTML: alt="Assign resources"
283 [[file:../images/taskjuggler/assign-resources.png]]
284
285 If we now export the project you'll see that TaskJuggler scheduled
286 some tasks in parallel (as there are several resources now which can
287 work in parallel). See the screen shot below:
288
289 #+CAPTION: Gantt Chart with multiple resources
290 #+ATTR_HTML: alt="Gantt Chart with multiple resources"
291 [[file:../images/taskjuggler/TaskJugglerUI2.png]]
292
293 Obviously we need to define dependencies between the tasks.
294
295 ** Define dependencies
296 There are several ways to define dependencies between tasks. When
297 coming from an Org mode background you probably want to define them
298 using the facilities provided by Org mode, which are either 
299
300   - The =ORDERED= property which allows you to state that the child
301     tasks have to be completed in the order they appear (top most
302     first).
303
304   - The =BLOCKER= property which allows you to state that a task
305     depends on either
306     - a previous sibling ("previous-sibling") or 
307     - any other task by stating the ~task_id~ property of the
308       predecessor
309
310 Again, it is probably easiest to define the dependencies using the
311 column view as shown below in the screen shot:
312
313 #+CAPTION: Defining dependencies using column view 
314 #+ATTR_HTML: alt="Defining dependencies using column view"
315 [[file:../images/taskjuggler/define-dependencies.png]]
316
317 Lastly there is also the ~depends~ property which corresponds to the
318 TaskJuggler terminology. It can be used the same way as the =BLOCKER=
319 property. This is illustrated below where the "Software Development"
320 for example is blocked by the task "Specification", i.e. it has to
321 wait until the specification is done. The task "Software Development"
322 is defined as =ORDERED=, i.e. all the subtasks of it have to be
323 completed in sequence. Another example is the milestone "Ship Product
324 to Customer" which is waiting until the Beta test and the Manual are
325 done.
326
327 #+BEGIN_SRC org
328 ,#+PROPERTY: Effort_ALL 2d 5d 10d 20d 30d 35d 50d 
329 ,#+PROPERTY: allocate_ALL dev doc test
330 ,#+COLUMNS: %30ITEM(Task) %Effort %allocate %BLOCKER %ORDERED
331
332 ,* Accounting Software                                        :taskjuggler_project:
333
334 ,** Specification
335    :PROPERTIES:
336    :Effort:   20d
337    :BLOCKER:  start
338    :allocate: dev
339    :END:
340
341 ,** Software Development
342    :PROPERTIES:
343    :ORDERED:  t
344    :BLOCKER:  previous-sibling
345    :priority: 1000
346    :allocate: dev
347    :END:
348
349 ,*** Database coupling
350     :PROPERTIES:
351     :Effort:   20d
352     :END:
353
354 ,*** Back-End Functions
355     :PROPERTIES:
356     :Effort:   30d
357     :task_id:  back_end
358     :END:
359
360 ,*** Graphical User Interface
361     :PROPERTIES:
362     :Effort:   35d
363     :allocate: paul, seb
364     :END:
365
366 ,** Software testing
367    :PROPERTIES:
368    :ORDERED:  t
369    :BLOCKER:  previous-sibling
370    :allocate: test
371    :END:
372 ,*** Alpha Test
373     :PROPERTIES:
374     :Effort:   5d
375     :task_id:  alpha
376     :END:
377
378 ,*** Beta Test
379     :PROPERTIES:
380     :Effort:   20d
381     :task_id:  beta
382     :allocate: test, paul
383     :END:
384
385 ,** Manual
386    :PROPERTIES:
387    :Effort:   50d
388    :task_id:  manual
389    :BLOCKER:  start
390    :allocate: doc
391    :END:
392
393 ,** Milestones
394 ,*** Project start
395     :PROPERTIES:
396     :task_id:  start
397     :END:
398
399 ,*** Technology Preview
400     :PROPERTIES:
401     :BLOCKER:  back_end
402     :END:
403
404 ,*** Beta version
405     :PROPERTIES:
406     :BLOCKER:  alpha
407     :END:
408
409 ,*** Ship Product to Customer
410     :PROPERTIES:
411     :BLOCKER:  beta manual
412     :END:
413
414
415 ,* Resources                                         :taskjuggler_resource:
416 ,** Developers
417    :PROPERTIES:
418    :resource_id: dev
419    :END:
420 ,*** Paul Smith
421     :PROPERTIES:
422     :resource_id: paul
423     :END:
424 ,*** Sébastien Bono
425     :PROPERTIES:
426     :resource_id: seb
427     :END:
428 ,*** Klaus Müller
429
430 ,** Others
431 ,*** Peter Murphy
432     :PROPERTIES:
433     :resource_id: doc
434     :limits:   { dailymax 6.4h }
435     :END:
436 ,*** Dim Sung
437     :PROPERTIES:
438     :resource_id: test
439     :END:
440 #+END_SRC
441
442 If you export the example above you'll TaskJuggler will schedule the
443 tasks as shown in the screen shot below
444
445 #+CAPTION: Gantt Chart with dependencies
446 #+ATTR_HTML: alt="Gantt Chart with dependencies"
447 [[file:../images/taskjuggler/TaskJugglerUI3.png]]
448
449 Also TaskJuggler will give you a overview how busy youre resources
450 will be and what they are working on. See below for a screen shot:
451
452 #+CAPTION: Resource usage chart
453 #+ATTR_HTML: alt="Resource usage chart"
454 [[file:../images/taskjuggler/resource-graph.png]]
455
456 Finally you can generate [[file:../images/taskjuggler/project-plan.pdf][good-looking project plans]] in PDF by printing
457 from TaskJuggler. This will make any [[http://en.wikipedia.org/wiki/Pointy-haired_Boss][Pointy-haired Boss]] happy.
458
459 ** Export of other properties
460 Generally the exporter writes a node property that is known to
461 TaskJuggler (such as ~shift~, ~booking~, ~efficiency~, ~journalentry~,
462 ~rate~ for resources or ~account~, ~start~, ~note~, ~duration~, ~end~,
463 ~journalentry~, ~milestone~, ~reference~, ~responsible~, ~scheduling~,
464 etc for tasks) as is to the TaskJuggler file.
465
466 Other properties such as completeness or priority are derived from
467 implicit information in the Org mode file. The TODO state for example
468 determines the completeness. A task will be exported with 100%
469 complete (~complete 100~) if it is marked as done. The priority of a
470 task will be determined through its priority cookie.
471
472
473 ** Old footnotes
474 [fn:2] You can customize this tag
475
476 [fn:3] Again, of course this tag can be customized
477
478 [fn:4] by downcasing the headline, replacing non-ascii characters with
479 '_' and picking the first word if it is unique
480
481 [fn:5] In TaskJuggler the allocations are cumulative, the exporter
482 however adds some code so that inherited allocation are ignored when
483 explicitly assigning a resource.
484 * TODO Incorporate/update old material into this file              :noexport:
485
486 This is from ./exporters/taskjuggler.org from Bastien and needs to be added into this
487 document. It comes from the 7.9.3f version of the manual.
488
489 ** Introduction
490
491 [[http://www.taskjuggler.org/][TaskJuggler]] is a project management tool.  It provides an optimizing
492 scheduler that computes your project time lines and resource assignments
493 based on the project outline and the constraints that you have provided.
494
495 The TaskJuggler exporter is a bit different from other exporters, such as
496 the =HTML= and @LaTeX{} exporters for example, in that it does not export
497 all the nodes of a document or strictly follow the order of the nodes in
498 the document.
499
500 Instead the TaskJuggler exporter looks for a tree that defines the tasks
501 and optionally trees that define the resources and reports for this
502 project.  It then creates a TaskJuggler file based on these trees and the
503 attributes defined in all the nodes.
504
505 ** TaskJuggler export commands
506
507 You need to have Org's =contrib/= in your Emacs =load-path= and to
508 =(require 'ox-taskjuggler)= to add the TaskJuggler export.  See also the
509 docstring of =org-export-backends= on how to add new backends by default.
510
511 When ox-taskjuggler.el is loaded, it defines two new handlers within =C-c
512 C-e= (=org-export-dispatch=):
513
514 | Keybinding  |                                    |                                                                                                     |
515 |-------------+------------------------------------+-----------------------------------------------------------------------------------------------------|
516 | C-c C-e j J | org-export-as-taskjuggler          | Export as a TaskJuggler file                                                                        |
517 | C-c C-e j o | org-export-as-taskjuggler-and-open | Export as a TaskJuggler file and then open the file with TaskJugglerUI (only for TaskJugglerUI 2.x) |
518
519 ** Tasks
520
521 #+index: org-export-taskjuggler-project-tag
522
523 Create your tasks as you usually do with Org mode.  Assign efforts to each
524 task using properties (it is easiest to do this in the column view).  You
525 should end up with something similar to the example by Peter Jones in
526 http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org.
527 Now mark the top node of your tasks with a tag named
528 =:taskjuggler_project:= (or whatever you customized
529 =org-export-taskjuggler-project-tag= to).  You are now ready to export the
530 project plan with =C-c C-e J= which will export the project plan and
531 open a gantt chart in TaskJugglerUI.
532
533 ** Resources
534
535 #+index: org-export-taskjuggler-resource-tag
536
537 Next you can define resources and assign those to work on specific tasks.
538 You can group your resources hierarchically.  Tag the top node of the
539 resources with =:taskjuggler_resource:= (or whatever you customized
540 =org-export-taskjuggler-resource-tag= to).  You can optionally assign an
541 identifier (named ~resource_id~) to the resources (using the standard Org
542 properties commands, see the [[http://orgmode.org/org.html#Property-syntax][Property syntax]] section of the manual) or you
543 can let the exporter generate identifiers automatically (the exporter picks
544 the first word of the headline as the identifier as long as it is
545 unique---see the documentation of =org-taskjuggler-get-unique-id=).  Using
546 that identifier you can then allocate resources to tasks.  This is again
547 done with the ~allocate~ property on the tasks.  Do this in column view or
548 when on the task type =C-c C-x p allocate RET <resource_id> RET=.
549
550 Once the allocations are done you can again export to TaskJuggler and check
551 in the Resource Allocation Graph which person is working on what task at
552 what time.
553
554 ** Export of properties
555
556 The exporter also takes TODO state information into consideration, i.e., if
557 a task is marked as done it will have the corresponding attribute in
558 TaskJuggler (~complete 100~).  Scheduling information is also taken into
559 account to set start/end dates for tasks.
560
561 The exporter will also export any property on a task resource or resource
562 node which is known to TaskJuggler, such as ~limits~, ~vacation~, ~shift~,
563 ~booking~, ~efficiency~, ~journalentry~, ~rate~ for resources or ~account~,
564 ~start~, ~note~, ~duration~, ~end~, ~journalentry~, ~milestone~,
565 ~reference~, ~responsible~, ~scheduling~, etc.@: for tasks.
566
567 ** Dependencies
568
569 The exporter will handle dependencies that are defined in the tasks either
570 with the ~ORDERED~ attribute (@pxref{TODO dependencies}), with the
571 ~BLOCKER~ attribute (see @file{org-depend.el}) or alternatively with a
572 ~depends~ attribute.  Both the ~BLOCKER~ and the ~depends~ attribute can be
573 either ~previous-sibling~ or a reference to an identifier (named ~task_id~)
574 which is defined for another task in the project.  ~BLOCKER~ and the
575 ~depends~ attribute can define multiple dependencies separated by either
576 space or comma.  You can also specify optional attributes on the dependency
577 by simply appending it.  The following examples should illustrate this:
578
579 #+BEGIN_EXAMPLE:
580 ** Preparation
581    :PROPERTIES:
582    :task_id:  preparation
583    :ORDERED:  t
584    :END:
585 ** Training material
586    :PROPERTIES:
587    :task_id:  training_material
588    :ORDERED:  t
589    :END:
590 *** Markup Guidelines
591     :PROPERTIES:
592     :Effort:   2d
593     :END:
594 *** Workflow Guidelines
595     :PROPERTIES:
596     :Effort:   2d
597     :END:
598 ** Presentation
599   :PROPERTIES:
600   :Effort:   2d
601   :BLOCKER:  training_material @{ gapduration 1d @} preparation
602   :END:
603 #+END_EXAMPLE:
604
605 #+index: org-export-taskjuggler-default-reports
606
607 TaskJuggler can produce many kinds of reports (e.g., gantt chart, resource
608 allocation, etc).  The user defines what kind of reports should be
609 generated for a project in the TaskJuggler file.  By default, the exporter
610 will automatically insert some pre-set reports in the file.  These defaults
611 are defined in =org-export-taskjuggler-default-reports=.  They can be
612 modified using customize along with a number of other options.  For a more
613 complete list, see =M-x customize-group RET org-export-taskjuggler RET=.
614
615 Alternately, the user can tag a tree with
616 =org-export-taskjuggler-report-tag=, and define reports in sub-nodes,
617 similarly to what is done with tasks or resources.  The properties used for
618 report generation are defined in
619 =org-export-taskjuggler-valid-report-attributes=. In addition, a special
620 property named ~report-kind~ is used to define the kind of report one wants
621 to generate (by default, a ~taskreport~).
622
623 For more information and examples see the Org-taskjuggler tutorial at
624 http://orgmode.org/worg/org-tutorials/org-taskjuggler.html.
625