Exporting Gantt charts with Taskjuggler v3 (tj3)

This article discusses the use of Org-mode for project planning using Taskjuggler, self-described as follows (from the project website):

TaskJuggler is a modern and powerful, Free and Open Source Software project management tool. Its new approach to project planning and tracking is more flexible and superior to the commonly used Gantt chart editing tools.

A tutorial already exists for the use of Org-mode and Taskjuggler v2.4.3, the last release of the v2.x.x series. Taskjuggler Version 3 (often referred to as simply "tj3"), was rebuilt using Ruby, and no longer features the former Qt-based GUI for task/timeline management of a project.

It should also be mentioned that the project is now 10 years old, and, as a result, is fantastically documented.

The manual used to cover Taskjuggler export to some extent, however the defaults assume the use of version 2.x.x. This tutorial will lay out the changes required to successfully export with tj3.

Preface: If you have not recently (and successfully) used tj3, it is recommended that you try compiling the example .tjp file as described below to rule out any issues with the tj3 installation itself before moving on integrating tj3 with Org mode.

Please refer to the installation section of the Taskjuggler manual for instructions. For the high level overview, you will need to install ruby and possibly ruby-gems. The easiest method is probably to install ruby-gems and simply type, from a terminal/command-line interface (you may need to run this as the root user or with sudo):

gem install taskjuggler

For Linux users, you may have a distro-specific package available if you would rather choose that route. For example, the Arch Linux User Repository (AUR) has a Taskjuggler 3 package available.

Once installed, you should check functionality by typing:

tj3 --version

If you just can't wait to see what tj3 can do, try compiling their sample file:

• Copy/paste into a file called something.tjp. Alternatively,

http://taskjuggler.org/tj3/examples/Tutorial/tutorial.tjp

• Save the file and then issue:¹

$ cd /path/to/something.tjp
$ tj3 something.tjp

Now check out the generated Overview.html in a browser!

To activate the Taskjuggler exporter in Org-mode, add this line to ~/.emacs:

(require 'ox-taskjuggler)

In addition, here are a list of current variables you can customize:

• org-taskjuggler-default-global-header
• org-taskjuggler-default-global-properties
• org-taskjuggler-default-project-duration
• org-taskjuggler-default-project-version
• org-taskjuggler-default-reports: sets a report file to use. This may be written in text format (as in, the variable set to the full report text string), or (perhaps easier) to a .tji file containing the report definition.
• org-taskjuggler-extension
• org-taskjuggler-final-hook
• org-taskjuggler-keep-project-as-task
• org-taskjuggler-process-command
• org-taskjuggler-project-tag
• org-taskjuggler-report-tag
• org-taskjuggler-reports-directory
• org-taskjuggler-resource-tag
• org-taskjuggler-target-version: should be set to the output of the command tj3 --version, e.g. (setq org-taskjuggler-target-version 3.4)
• org-taskjuggler-valid-report-attributes
• org-taskjuggler-valid-resource-attributes
• org-taskjuggler-valid-task-attributes

After customizing variables (at least if changing them in .emacs vs. the customize-variable interface, restart Emacs or issue M-x load-file RET ~/.emacs RET and we're ready to create our project managment .org file!

Before diving in, it would be helpful to familiarize yourself with Taskjuggler if you aren't already.

• Take a look at their example file to get a sense for what a full Taskjuggler project looks like in tj3 syntax. You may not understand it, but skimming the various commands will give you an understanding for how the project is setup:
  • Basic project information (start date, duration (+4m), date/time syntax, timezone, etc.)
  • Accounts (not applicable if you aren't tracking finances)
  • Available resources with wage, vacation, working-hours/day information, etc.
  • Top level milestones
  • Tasks, divided up by major project area
  • A report definition

In addition to the general format of a Taskjuggler file, understanding of the following is particularly helpful:

• Task time definitions: start, end, depends, maxstart, and maxend
• Task durations: effort, duration, length. For example, duration will use consecutive days, length observes definitions of work weeks (so a length of 7d with a 5-day work week specified translates to 9d calendar time. Effort requires at least one resource defined and assigned to the task, and will use his/her available work time/day to figure out how long the task will take.

If you are familiar with Taskjuggler, it may be helpful to understand how Taskjuggler syntax is mapped to Org-mode. This is done via property drawers, a simple key-value pair beneath the headline to which the properties apply.

The bulk of the actual Taskjuggler project consists of tasks, which can be given various attributes. You can view the full list of allowed attributes in the task syntax specification in the tj3 manual. Thus, a task in Taskjuggler might look something like this:

task entry_door "Install entry door" {
  depends buy_door
  effort 4h
}

In this example task defines the following text as a task for Taskjuggler compilation. The text entry_door is the task's ID, which must be unique within the current subtree. The test within quotes is the "plain language" name for the task you would like to appear in your report.

This task has two attributes: depends and effort. In this example, installing the door, entry_door, depends on another task, buy_door, and the estimated effort required is 4 hours.

In Org-mode, the equivalent task would be created like so:

* Install entry door
  :PROPERTIES:
  :task_id:  entry_door
  :depends:  buy_door
  :Effort:   4h
  :END:

Some attributes may be set via two methods. For example, the start of a task can be defined by a SCHEDULED tag or a :start: property; the following are equivalent:

* Install entry door
   SCHEDULED: <2013-07-15 Mon>

* Install entry door
  :PROPERTIES:
  :start:    2013-07-15
  :END:

Similarly DEADLINE timestamps and the :end: property function the same way.

Let's begin with a simple example project consisting of a home renovation project. To start our file, we need a top level headline to tell Org-mode that this headline and everything inside it should be considered a taskjuggler project. Thus, we can create a new file, home-renovation.org and create a top level headline to contain our tasks:

* Home renovation                                       :taskjuggler_project:

• Taskjuggler (tj3) user manual
• Taskjuggler (v2) guide on Worg (though some functionality is out of date for using tj3, most of the specifications still work, and the guide is excellent overall for getting a feel for using Org-mode with Taskjuggler.