minor format change
[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 In addition, here are a list of current variables you can customize:
97
98 - org-taskjuggler-default-global-header
99 - org-taskjuggler-default-global-properties
100 - org-taskjuggler-default-project-duration
101 - org-taskjuggler-default-project-version
102 - ~org-taskjuggler-default-reports~: sets a report file to use. This may be written in
103      text format (as in, the variable set to the full report text string), or (perhaps
104      easier) to a [[http://www.taskjuggler.org/tj3/manual/include.properties.html][=.tji= file containing the report definition]]. 
105 - org-taskjuggler-extension
106 - org-taskjuggler-final-hook
107 - org-taskjuggler-keep-project-as-task
108 - org-taskjuggler-process-command
109 - org-taskjuggler-project-tag
110 - org-taskjuggler-report-tag
111 - org-taskjuggler-reports-directory
112 - org-taskjuggler-resource-tag
113 - ~org-taskjuggler-target-version~: should be set to the output of the command =tj3
114      --version=, e.g. =(setq org-taskjuggler-target-version 3.4)=
115 - org-taskjuggler-valid-report-attributes
116 - org-taskjuggler-valid-resource-attributes
117 - org-taskjuggler-valid-task-attributes
118
119 After customizing variables (at least if changing them in .emacs vs. the
120 =customize-variable= interface, restart Emacs or issue =M-x load-file RET ~/.emacs RET=
121 and we're ready to create our project managment =.org= file!
122
123 * Familiarizing yourself with Taskjuggler
124
125 Before diving in, it would be helpful to familiarize yourself with Taskjuggler if you
126 aren't already.
127
128 - Take a look at their [[http://www.taskjuggler.org/tj3/examples/Tutorial/tutorial.tjp][example file]] to get a sense for what a full Taskjuggler project
129   looks like in tj3 syntax. You may not understand it, but skimming the various commands
130   will give you an understanding for how the project is setup:
131   - Basic project information (start date, duration (=+4m=), date/time syntax, timezone, etc.)
132   - Accounts (not applicable if you aren't tracking finances)
133   - Available resources with wage, vacation, working-hours/day information, etc.
134   - Top level milestones
135   - Tasks, divided up by major project area
136   - A report definition
137
138 In addition to the general format of a Taskjuggler file, understanding of the following is
139 particularly helpful:
140 - Task time definitions: [[http://www.taskjuggler.org/tj3/manual/start.html][start]], [[http://www.taskjuggler.org/tj3/manual/end.html][end]], [[http://www.taskjuggler.org/tj3/manual/depends.html][depends]], [[http://www.taskjuggler.org/tj3/manual/maxstart.html][maxstart]], and [[http://www.taskjuggler.org/tj3/manual/maxend.html][maxend]]
141 - Task durations: [[http://www.taskjuggler.org/tj3/manual/effort.html][effort]], [[http://www.taskjuggler.org/tj3/manual/duration.html][duration]], [[http://www.taskjuggler.org/tj3/manual/length.html][length]]. For example, duration will use consecutive
142   days, length observes definitions of work weeks (so a length of =7d= with a 5-day work
143   week specified translates to =9d= calendar time. Effort requires at least one resource
144   defined and assigned to the task, and will use his/her available work time/day to figure
145   out how long the task will take. 
146
147   
148 * Mapping of Taskjuggler syntax to Org-mode
149
150 If you are familiar with Taskjuggler, it may be helpful to understand how Taskjuggler
151 syntax is mapped to Org-mode. This is done via [[http://orgmode.org/manual/Property-syntax.html#Property-syntax][property drawers]], a simple key-value pair
152 beneath the headline to which the properties apply.
153
154 The bulk of the actual Taskjuggler project consists of tasks, which can be given various
155 attributes. You can view the full list of allowed attributes in the
156 [[http://www.taskjuggler.org/tj3/manual/task.html][task syntax specification]] in the tj3 manual. Thus, a task in Taskjuggler might look
157 something like this:
158
159 #+begin_example
160
161 task entry_door "Install entry door" {
162   depends buy_door
163   effort 4h
164 }  
165
166 #+end_example
167
168 In this example =task= defines the following text as a task for Taskjuggler
169 compilation. The text =entry_door= is the task's ID, which must be unique within the
170 current subtree. The test within quotes is the "plain language" name for the task you
171 would like to appear in your report.
172
173 This task has two attributes: =depends= and =effort=. In this example, installing the
174 door, =entry_door=, depends on another task, =buy_door=, and the estimated effort required
175 is 4 hours.
176
177 In Org-mode, the equivalent task would be created like so:
178
179 #+begin_example
180
181 * Install entry door
182   :PROPERTIES:
183   :task_id:  entry_door
184   :depends:  buy_door
185   :Effort:   4h
186   :END:
187
188 #+end_example
189
190 Some attributes may be set via two methods. For example, the start of a task can be
191 defined by a =SCHEDULED= tag or a =:start:= property; the following are equivalent:
192
193 #+begin_example
194
195 * Install entry door
196   SCHEDULED: <2013-07-15 Mon>
197
198 * Install entry door
199   :PROPERTIES:
200   :start:    2013-07-15
201   :END:
202
203 #+end_example
204
205 Similarly =DEADLINE= timestamps and the =:end:= property function the same way.
206
207 * Example
208
209 Let's begin with a simple example project consisting of a home renovation project. To
210 start our file, we need a top level headline to tell Org-mode that this headline and
211 everything inside it should be considered a taskjuggler project. Thus, we can create a new
212 file, =home-renovation.org= and create a top level headline to contain our tasks:
213
214 #+begin_example
215
216 * Home renovation                                       :taskjuggler_project:
217
218
219 #+end_example
220
221 * References
222 - [[http://www.taskjuggler.org/tj3/manual/toc.html][Taskjuggler (tj3) user manual]]
223 - [[http://orgmode.org/manual/TaskJuggler-export.html][Taskjuggler in the Org-mode manual]]
224 - [[http://orgmode.org/worg/org-tutorials/org-taskjuggler.html][Taskjuggler (v2) guide on Worg]] (though some functionality is out of date for using tj3,
225   most of the specifications still work, and the guide is excellent overall for getting a
226   feel for using Org-mode with Taskjuggler.
227
228
229 * Footnotes
230
231 [fn:1] You may run into compilation issues due to special characters in that file on
232 lines 37 (a copyright symbol), 79, and 83 (two accented characters in resource names). If
233 this happens, just replace those three characters with something else, or delete them,
234 and the file should compile. [[https://github.com/taskjuggler/TaskJuggler/issues/105][An issue has been filed]] inquiring about whether or not this
235 is a system setup issue and, if not, suggesting that the characters be replaced.
236
237 * TODO Fill in the details!                                        :noexport:
238 ** Plan your project
239 You start out as you normally would by breaking down the project into
240 tasks. Let's take the following example where you have a project to
241 create an accounting software:
242
243 #+BEGIN_SRC org
244 ,* Accounting Software
245
246 ,** Specification
247
248 ,** Software Development
249 ,*** Database coupling
250 ,*** Back-End Functions
251 ,*** Graphical User Interface
252
253 ,** Software testing
254 ,*** Alpha Test
255 ,*** Beta Test
256
257 ,** Manual
258
259 ,** Milestones
260 ,*** Project start
261 ,*** Technology Preview
262 ,*** Beta version
263 ,*** Ship Product to Customer
264 #+END_SRC
265
266 ** Estimate the effort
267 Now that you've figured out the tasks it's time to estimate the
268 efforts for each task. By using column view this can be done very
269 efficiently. It also helps to define the =COLUMNS= and default values
270 for the Effort property as shown in the following screen shot:
271
272 #+CAPTION: Estimating effort using column view 
273 #+ATTR_HTML: alt="Estimating effort using column view"
274 [[file:../images/taskjuggler/effort-estimation.png]]
275
276 Your resulting Org mode project file will look somewhat like the
277 following:
278
279 #+BEGIN_SRC org
280 ,#+PROPERTY: Effort_ALL 2d 5d 10d 20d 30d 35d 50d 
281 ,#+COLUMNS: %70ITEM(Task) %Effort
282
283 ,* Accounting Software
284
285 ,** Specification
286    :PROPERTIES:
287    :Effort:   20d
288    :END:
289
290 ,** Software Development
291
292 ,*** Database coupling
293     :PROPERTIES:
294     :Effort:   20d
295     :END:
296
297 ,*** Back-End Functions
298     :PROPERTIES:
299     :Effort:   30d
300     :END:
301
302 ,*** Graphical User Interface
303     :PROPERTIES:
304     :Effort:   35d
305     :END:
306
307 ,** Software testing
308 ,*** Alpha Test
309     :PROPERTIES:
310     :Effort:   5d
311     :END:
312
313 ,*** Beta Test
314     :PROPERTIES:
315     :Effort:   20d
316     :END:
317
318 ,** Manual
319    :PROPERTIES:
320    :Effort:   50d
321    :END:
322
323 ,** Milestones
324 ,*** Project start
325 ,*** Technology Preview
326 ,*** Beta version
327 ,*** Ship Product to Customer
328 #+END_SRC
329
330 ** Generate a Gantt chart
331 Before you now export the project to TaskJuggler you need to tell the
332 exporter in which tree it can find the tasks. You do this by adding
333 the tag ~taskjuggler_project~ to the node "Accounting Software"[fn:2].
334 Do this by moving to the "Accounting Software" headline and typing the
335 following:
336
337 : C-c C-c taskjuggler_project RET
338
339 This allows you to have other nodes for this project such as an
340 introduction or general notes.
341
342 To export the project to TaskJuggler you simply type 
343
344 : M-x org-export-as-taskjuggler-and-open
345
346 This will open your project in TaskJugglerUI as illustrated below
347
348 #+CAPTION: Gantt chart in TaskJugglerUI
349 #+ATTR_HTML: alt="Gantt chart in TaskJugglerUI"
350 [[file:../images/taskjuggler/TaskJugglerUI1.png]]
351
352 Since we have not assigned any resources to work on the project the
353 exporter assumes that you will be the one working on it and has
354 assigned all tasks to you. The tasks have been serialized so that you
355 will not have to many things to do at once, i.e. the resources will be
356 leveled.
357
358 ** Assign resources
359 The next step is to list all the resources working on the project and
360 assign the tasks to them. Create a node for the resources. You can
361 group the resources by creating hierarchies. Tag the resource tree
362 with the tag ~taskjuggler_resource~ so that the exporter knows where to
363 look for resource definitions[fn:3].
364
365 #+BEGIN_SRC org
366 ,* Resources                                         :taskjuggler_resource:
367 ,** Developers
368    :PROPERTIES:
369    :resource_id: dev
370    :END:
371 ,*** Paul Smith
372     :PROPERTIES:
373     :resource_id: paul
374     :END:
375 ,*** Sébastien Bono
376     :PROPERTIES:
377     :resource_id: seb
378     :END:
379 ,*** Klaus Müller
380
381 ,** Others
382 ,*** Peter Murphy
383     :PROPERTIES:
384     :resource_id: doc
385     :END:
386 ,*** Dim Sung
387     :PROPERTIES:
388     :resource_id: test
389     :END:
390 #+END_SRC
391
392 As you'll note I also added some ~resource_id~ properties to some of
393 the resources (or resource groups). I will use these identifiers to
394 allocate the resources to the tasks. The exporter will create unique
395 ids for the resources automatically[fn:4], but if you want to use
396 short forms it's better to define ~resource_id~ properties for your
397 resources. This will also allow you to define default values for the
398 allocation as follows:
399
400 : #+PROPERTY: allocate_ALL dev doc test
401
402 The easiest way to assign resources is again the column view mode.
403 There is no need to allocate a resource to every task, as allocations
404 are inherited in TaskJuggler[fn:5]. You'll note in the screen shot
405 below that some tasks have more than one resource assigned to them.
406 TaskJuggler will calculate the duration of the task based on the
407 effort and the resources working on this task.
408
409 #+CAPTION: Assign resources
410 #+ATTR_HTML: alt="Assign resources"
411 [[file:../images/taskjuggler/assign-resources.png]]
412
413 If we now export the project you'll see that TaskJuggler scheduled
414 some tasks in parallel (as there are several resources now which can
415 work in parallel). See the screen shot below:
416
417 #+CAPTION: Gantt Chart with multiple resources
418 #+ATTR_HTML: alt="Gantt Chart with multiple resources"
419 [[file:../images/taskjuggler/TaskJugglerUI2.png]]
420
421 Obviously we need to define dependencies between the tasks.
422
423 ** Define dependencies
424 There are several ways to define dependencies between tasks. When
425 coming from an Org mode background you probably want to define them
426 using the facilities provided by Org mode, which are either 
427
428   - The =ORDERED= property which allows you to state that the child
429     tasks have to be completed in the order they appear (top most
430     first).
431
432   - The =BLOCKER= property which allows you to state that a task
433     depends on either
434     - a previous sibling ("previous-sibling") or 
435     - any other task by stating the ~task_id~ property of the
436       predecessor
437
438 Again, it is probably easiest to define the dependencies using the
439 column view as shown below in the screen shot:
440
441 #+CAPTION: Defining dependencies using column view 
442 #+ATTR_HTML: alt="Defining dependencies using column view"
443 [[file:../images/taskjuggler/define-dependencies.png]]
444
445 Lastly there is also the ~depends~ property which corresponds to the
446 TaskJuggler terminology. It can be used the same way as the =BLOCKER=
447 property. This is illustrated below where the "Software Development"
448 for example is blocked by the task "Specification", i.e. it has to
449 wait until the specification is done. The task "Software Development"
450 is defined as =ORDERED=, i.e. all the subtasks of it have to be
451 completed in sequence. Another example is the milestone "Ship Product
452 to Customer" which is waiting until the Beta test and the Manual are
453 done.
454
455 #+BEGIN_SRC org
456 ,#+PROPERTY: Effort_ALL 2d 5d 10d 20d 30d 35d 50d 
457 ,#+PROPERTY: allocate_ALL dev doc test
458 ,#+COLUMNS: %30ITEM(Task) %Effort %allocate %BLOCKER %ORDERED
459
460 ,* Accounting Software                                        :taskjuggler_project:
461
462 ,** Specification
463    :PROPERTIES:
464    :Effort:   20d
465    :BLOCKER:  start
466    :allocate: dev
467    :END:
468
469 ,** Software Development
470    :PROPERTIES:
471    :ORDERED:  t
472    :BLOCKER:  previous-sibling
473    :priority: 1000
474    :allocate: dev
475    :END:
476
477 ,*** Database coupling
478     :PROPERTIES:
479     :Effort:   20d
480     :END:
481
482 ,*** Back-End Functions
483     :PROPERTIES:
484     :Effort:   30d
485     :task_id:  back_end
486     :END:
487
488 ,*** Graphical User Interface
489     :PROPERTIES:
490     :Effort:   35d
491     :allocate: paul, seb
492     :END:
493
494 ,** Software testing
495    :PROPERTIES:
496    :ORDERED:  t
497    :BLOCKER:  previous-sibling
498    :allocate: test
499    :END:
500 ,*** Alpha Test
501     :PROPERTIES:
502     :Effort:   5d
503     :task_id:  alpha
504     :END:
505
506 ,*** Beta Test
507     :PROPERTIES:
508     :Effort:   20d
509     :task_id:  beta
510     :allocate: test, paul
511     :END:
512
513 ,** Manual
514    :PROPERTIES:
515    :Effort:   50d
516    :task_id:  manual
517    :BLOCKER:  start
518    :allocate: doc
519    :END:
520
521 ,** Milestones
522 ,*** Project start
523     :PROPERTIES:
524     :task_id:  start
525     :END:
526
527 ,*** Technology Preview
528     :PROPERTIES:
529     :BLOCKER:  back_end
530     :END:
531
532 ,*** Beta version
533     :PROPERTIES:
534     :BLOCKER:  alpha
535     :END:
536
537 ,*** Ship Product to Customer
538     :PROPERTIES:
539     :BLOCKER:  beta manual
540     :END:
541
542
543 ,* Resources                                         :taskjuggler_resource:
544 ,** Developers
545    :PROPERTIES:
546    :resource_id: dev
547    :END:
548 ,*** Paul Smith
549     :PROPERTIES:
550     :resource_id: paul
551     :END:
552 ,*** Sébastien Bono
553     :PROPERTIES:
554     :resource_id: seb
555     :END:
556 ,*** Klaus Müller
557
558 ,** Others
559 ,*** Peter Murphy
560     :PROPERTIES:
561     :resource_id: doc
562     :limits:   { dailymax 6.4h }
563     :END:
564 ,*** Dim Sung
565     :PROPERTIES:
566     :resource_id: test
567     :END:
568 #+END_SRC
569
570 If you export the example above you'll TaskJuggler will schedule the
571 tasks as shown in the screen shot below
572
573 #+CAPTION: Gantt Chart with dependencies
574 #+ATTR_HTML: alt="Gantt Chart with dependencies"
575 [[file:../images/taskjuggler/TaskJugglerUI3.png]]
576
577 Also TaskJuggler will give you a overview how busy youre resources
578 will be and what they are working on. See below for a screen shot:
579
580 #+CAPTION: Resource usage chart
581 #+ATTR_HTML: alt="Resource usage chart"
582 [[file:../images/taskjuggler/resource-graph.png]]
583
584 Finally you can generate [[file:../images/taskjuggler/project-plan.pdf][good-looking project plans]] in PDF by printing
585 from TaskJuggler. This will make any [[http://en.wikipedia.org/wiki/Pointy-haired_Boss][Pointy-haired Boss]] happy.
586
587 ** Export of other properties
588 Generally the exporter writes a node property that is known to
589 TaskJuggler (such as ~shift~, ~booking~, ~efficiency~, ~journalentry~,
590 ~rate~ for resources or ~account~, ~start~, ~note~, ~duration~, ~end~,
591 ~journalentry~, ~milestone~, ~reference~, ~responsible~, ~scheduling~,
592 etc for tasks) as is to the TaskJuggler file.
593
594 Other properties such as completeness or priority are derived from
595 implicit information in the Org mode file. The TODO state for example
596 determines the completeness. A task will be exported with 100%
597 complete (~complete 100~) if it is marked as done. The priority of a
598 task will be determined through its priority cookie.
599
600
601 ** Old footnotes
602 [fn:2] You can customize this tag
603
604 [fn:3] Again, of course this tag can be customized
605
606 [fn:4] by downcasing the headline, replacing non-ascii characters with
607 '_' and picking the first word if it is unique
608
609 [fn:5] In TaskJuggler the allocations are cumulative, the exporter
610 however adds some code so that inherited allocation are ignored when
611 explicitly assigning a resource.
612 * TODO Incorporate/update old material into this file              :noexport:
613
614 This is from ./exporters/taskjuggler.org from Bastien and needs to be added into this
615 document. It comes from the 7.9.3f version of the manual.
616
617 ** Introduction
618
619 [[http://www.taskjuggler.org/][TaskJuggler]] is a project management tool.  It provides an optimizing
620 scheduler that computes your project time lines and resource assignments
621 based on the project outline and the constraints that you have provided.
622
623 The TaskJuggler exporter is a bit different from other exporters, such as
624 the =HTML= and @LaTeX{} exporters for example, in that it does not export
625 all the nodes of a document or strictly follow the order of the nodes in
626 the document.
627
628 Instead the TaskJuggler exporter looks for a tree that defines the tasks
629 and optionally trees that define the resources and reports for this
630 project.  It then creates a TaskJuggler file based on these trees and the
631 attributes defined in all the nodes.
632
633 ** TaskJuggler export commands
634
635 You need to have Org's =contrib/= in your Emacs =load-path= and to
636 =(require 'ox-taskjuggler)= to add the TaskJuggler export.  See also the
637 docstring of =org-export-backends= on how to add new backends by default.
638
639 When ox-taskjuggler.el is loaded, it defines two new handlers within =C-c
640 C-e= (=org-export-dispatch=):
641
642 | Keybinding  |                                    |                                                                                                     |
643 |-------------+------------------------------------+-----------------------------------------------------------------------------------------------------|
644 | C-c C-e j J | org-export-as-taskjuggler          | Export as a TaskJuggler file                                                                        |
645 | 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) |
646
647 ** Tasks
648
649 #+index: org-export-taskjuggler-project-tag
650
651 Create your tasks as you usually do with Org mode.  Assign efforts to each
652 task using properties (it is easiest to do this in the column view).  You
653 should end up with something similar to the example by Peter Jones in
654 http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org.
655 Now mark the top node of your tasks with a tag named
656 =:taskjuggler_project:= (or whatever you customized
657 =org-export-taskjuggler-project-tag= to).  You are now ready to export the
658 project plan with =C-c C-e J= which will export the project plan and
659 open a gantt chart in TaskJugglerUI.
660
661 ** Resources
662
663 #+index: org-export-taskjuggler-resource-tag
664
665 Next you can define resources and assign those to work on specific tasks.
666 You can group your resources hierarchically.  Tag the top node of the
667 resources with =:taskjuggler_resource:= (or whatever you customized
668 =org-export-taskjuggler-resource-tag= to).  You can optionally assign an
669 identifier (named ~resource_id~) to the resources (using the standard Org
670 properties commands, see the [[http://orgmode.org/org.html#Property-syntax][Property syntax]] section of the manual) or you
671 can let the exporter generate identifiers automatically (the exporter picks
672 the first word of the headline as the identifier as long as it is
673 unique---see the documentation of =org-taskjuggler-get-unique-id=).  Using
674 that identifier you can then allocate resources to tasks.  This is again
675 done with the ~allocate~ property on the tasks.  Do this in column view or
676 when on the task type =C-c C-x p allocate RET <resource_id> RET=.
677
678 Once the allocations are done you can again export to TaskJuggler and check
679 in the Resource Allocation Graph which person is working on what task at
680 what time.
681
682 ** Export of properties
683
684 The exporter also takes TODO state information into consideration, i.e., if
685 a task is marked as done it will have the corresponding attribute in
686 TaskJuggler (~complete 100~).  Scheduling information is also taken into
687 account to set start/end dates for tasks.
688
689 The exporter will also export any property on a task resource or resource
690 node which is known to TaskJuggler, such as ~limits~, ~vacation~, ~shift~,
691 ~booking~, ~efficiency~, ~journalentry~, ~rate~ for resources or ~account~,
692 ~start~, ~note~, ~duration~, ~end~, ~journalentry~, ~milestone~,
693 ~reference~, ~responsible~, ~scheduling~, etc.@: for tasks.
694
695 ** Dependencies
696
697 The exporter will handle dependencies that are defined in the tasks either
698 with the ~ORDERED~ attribute (@pxref{TODO dependencies}), with the
699 ~BLOCKER~ attribute (see @file{org-depend.el}) or alternatively with a
700 ~depends~ attribute.  Both the ~BLOCKER~ and the ~depends~ attribute can be
701 either ~previous-sibling~ or a reference to an identifier (named ~task_id~)
702 which is defined for another task in the project.  ~BLOCKER~ and the
703 ~depends~ attribute can define multiple dependencies separated by either
704 space or comma.  You can also specify optional attributes on the dependency
705 by simply appending it.  The following examples should illustrate this:
706
707 #+BEGIN_EXAMPLE:
708 ** Preparation
709    :PROPERTIES:
710    :task_id:  preparation
711    :ORDERED:  t
712    :END:
713 ** Training material
714    :PROPERTIES:
715    :task_id:  training_material
716    :ORDERED:  t
717    :END:
718 *** Markup Guidelines
719     :PROPERTIES:
720     :Effort:   2d
721     :END:
722 *** Workflow Guidelines
723     :PROPERTIES:
724     :Effort:   2d
725     :END:
726 ** Presentation
727   :PROPERTIES:
728   :Effort:   2d
729   :BLOCKER:  training_material @{ gapduration 1d @} preparation
730   :END:
731 #+END_EXAMPLE:
732
733 #+index: org-export-taskjuggler-default-reports
734
735 TaskJuggler can produce many kinds of reports (e.g., gantt chart, resource
736 allocation, etc).  The user defines what kind of reports should be
737 generated for a project in the TaskJuggler file.  By default, the exporter
738 will automatically insert some pre-set reports in the file.  These defaults
739 are defined in =org-export-taskjuggler-default-reports=.  They can be
740 modified using customize along with a number of other options.  For a more
741 complete list, see =M-x customize-group RET org-export-taskjuggler RET=.
742
743 Alternately, the user can tag a tree with
744 =org-export-taskjuggler-report-tag=, and define reports in sub-nodes,
745 similarly to what is done with tasks or resources.  The properties used for
746 report generation are defined in
747 =org-export-taskjuggler-valid-report-attributes=. In addition, a special
748 property named ~report-kind~ is used to define the kind of report one wants
749 to generate (by default, a ~taskreport~).
750
751 For more information and examples see the Org-taskjuggler tutorial at
752 http://orgmode.org/worg/org-tutorials/org-taskjuggler.html.
753