# The TaskJuggler Manual

Chris
Schläger
Marc
Rührschneck
2001, 2002, 2003, 2004, 2005, 2006
Chris Schläger
Version 2.3.1
2.3.1

This document describes TaskJuggler version 2.3.1

TaskJuggler
Project Management
Gantt Chart
Task
Resources

## About this document

This document describes TaskJuggler version 2.3.1

The TaskJuggler manual consists of two parts. The first part contains general usage information and a tutorial. The tutorial is highly recommended for all first-time TaskJuggler users. It is a very good introduction to many TaskJuggler concepts and features. The second part is the language reference.

## Introduction

### About TaskJuggler

TaskJuggler is a modern and powerful project management tool. Its new approach to project planning and tracking is far superior to the commonly used Gantt chart editing tools. It has already been successfully used in many projects and scales easily to projects with hundreds of resources and thousands of tasks.

TaskJuggler is an Open Source tools for serious project managers. It covers the complete spectrum of project management tasks from the first idea to the completion of the project. It assists you during project scoping, resource assignment, cost and revenue planing, risk and communication management.

TaskJuggler provides an optimizing scheduler that computes your project time lines and resource assignments based on the project outline and the constrains that you have provided. The build-in resource balancer and consistency checker offload you from having to worry about irrelevant details and ring the alarm if the project gets out of hand. Its flexible "as many details as necessary"-approach allows you to still plan your project as you go, making it also ideal for new management strategies such as Extreme Programming and Agile Project Management.

If you are about to build a skyscraper or just want to put together your colleague's shift plan for the next month, TaskJuggler is the right tool for you. If you just want to draw nice looking Gantt charts to impress your boss or your investors, TaskJuggler might not be right for you. It takes some effort to master its power, but it will become a companion you don't want to miss anymore.

### Features and Highlights

- Manages tasks, resources and costs in one package

- Automatic resource leveling, tasks conflict resolutions, and task filtering

- Comprehensive and flexible views and reports so you can find the information you need when you need it

- Build-in templates to get you started (you can also save your own schedules as templates for future use)

- Project tracking and status reporting

- Graphical User Interface to conveniently edit your projects, view and generate Gamtt charts and reports

- Unlimited number of scenarios (baselines) of same project for what-if analysis

- CSV data export for exchange with Office Suites

- Risk analysis

- Project breakdown and management team support

- Flexible working hours and vacation handling

- Support for shift working

- Multiple time zone support

- Tasks may have initial costs, finishing costs

- Resources may have running costs

- Support for profit/loss analysis

- HTML and XML report generation

- Powerful project description syntax with macro support

- Support for central resource allocation database

### TaskJuggler on the Web

The official TaskJuggler web site can be found at http://www.taskjuggler.org.

Since the developers are mostly busy project managers themselves, we have created a forum for users to help each other.

&ChangeLog;

### How to Contribute

#### Why contribute?

TaskJuggler is an Open Source Project. It was developed by volunteers mostly in their spare time. Made available under the GNU General Public license and similar licenses, TaskJuggler can be shared and used free of charge by anybody who respects the license conditions. Does that mean you can use it without worrying about anything? Clearly not! Though users have no legal obligation to contribute, you should feel a moral obligation to support Open Source in whatever way you can. This can range from helping out other users with their first Linux installation to actively contributing to the TaskJuggler Project, not just as a programmer. The following section describes, how you can contribute to any of the components that are part of the TaskJuggler software releases.

#### Preparing a contribution

To get started you need to download the most current development snapshot from the TaskJuggler Download Site. The development snapshot is updated once a day to provide access to the most recent developments. It is important that you use a very recent snapshot as the developers have probably made changes in the same files as you. This increases the chance for change collisions which could mean recreating your contribution from scratch.

Unpack the tarball as described in the installation section. Then rename the taskjuggler directory to something like `taskjuggler-yourname`. Then unpack the tarball again in the same place as before. You should now have a directory that contains two identical directory trees, each with a slightly different name of the top-level directory of each tree.

Next you need to find the files where you want to make your modifications. Please make your changes only in the `taskjuggler-yourname` directory. The other directory must be left unmodified. We need it later on to create a file that just contains your changes. Sometimes files will be generated from other files. Do not change those generated files. Your changes will be overwritten the next time you call the make utility. To identify those files, some familiarity with make and other Linux tools are helpful. Whenever there is a file with the same base name and the extension `.in` in the same directory, then the file is generated from the `.in`-file. You need to modify the `.in`-file, not the one with just the base name. Another indicator is the fact that the file is not part of the tarball. With few exceptions that can be identified by the .in-file rule above, the tarball does not contain any generated files.

#### Creating a Patch

When you are done with your changes, it's a good idea to test them. Type

    make

in the `taskjuggler-yourname` directory. If there are no errors, you can check or test the result. If everything builds fine, you can then remove all generated files again by typing

    make distclean

Now you can generate a file that just contains your modifications by typing

    diff -ru taskjuggler-svn taskjuggler-yourname > taskjuggler-yourname.diff

Inspect the generated diff file `taskjuggler-yourname.diff` and make sure it only contains diffs for files that you have changed and the changes are the way you want them to be. If there are generated files included in the diff, please remove those files and regenerate the diff.

The diff utility performs a line-by-line comparisons of the files. Try to only make changes that have an impact on the generated files. Do you change indentation or line wrapping of paragraphs. These kind of changes increase the size of diff files and make it much harder to evaluate the patches. When making changes to the program code, please use our coding style. If your contribution is large enough to justify a copyright claim, please indicate what copyright you claim in the patch. For modifications to existing files, we will assume that your contribution falls under the same license as the modified file. All new files will need to contain a license declaration, preferably GPL.

#### Contributing Translations

Another possible area of contribution are translation of TaskJuggler into languages other than US English. Our development process is in principle prepared for translations, but the first translation will definitely be a bit difficult to do. TaskJuggler has several hundred messages and more than hundred pages of documentation. Any translation is a significant effort and an ongoing commitment. TaskJuggler is still actively developed and this will require the translations to be updated as well. Please understand that we do not want to ship partial or outdated translations to our users, so please ensure you or a group of people are willing to maintain the translations.

#### Some final words to Contributors

We do welcome all contributions but please understand that we reserve the right to reject any contribution that does not follow the above guidelines or otherwise conflicts with the goals of the TaskJuggler team. It is a good idea to contact the team prior to making any larger efforts.

## Installation

### Obtaining TaskJuggler

TaskJuggler may be obtained from the following web site:

http://www.taskjuggler.org

### The TaskJuggler Components

TaskJuggler consists of several modular components that you may or may not need. TaskJuggler also uses some additional tools. We have avoided to re-invent the wheel again wherever possible. We tried to keep the dependency list reasonably small, nevertheless can it be challenging for an inexperienced user to build and install TaskJuggler from source code. Most users are probably better served by using binary packages from their distributor. Almost every mainstream distribution has TaskJuggler included in recent version of their product. If not, you might like to contact them to inform them that they are missing an essential package.

This version of TaskJuggler was built and tested on SuSE Linux 10.0 and 10.1 on various hardware platforms.

#### The Graphical User Interfaces

With version 2.2 came a new graphical front-end. It's an integrated Project management environment.

The front-end is called `TaskJugglerUI`. Don't confuse this with `taskjuggler` which is the commandline version. When you want to start TaskJugglerUI from a shell, you need to type it with the capital letters.

The graphical front-ends make use of the libraries of the K Desktop Environment. We recommend to use at least version 3.4. Earlier version will probably work as well, but we have not tested them.

#### The command line tool taskjuggler

To build and run TaskJuggler, you need:

- Qt — The Qt C++ class library version 3.3 or higher

- GNU Compiler Collection — We are currently using GCC 4.0 to develop TaskJuggler. Since we try to write the code platform independent and ANSI standard compliant it should work with most other compilers as well.

The requirements listed are enough to build and use the command line program that translates project descriptions into HTML or XML reports. If you want to built this documentation or use the tools to process the XML files you need to install the additional dependencies. If any of the following dependencies are not matched, the configure script will issue a warning but will not fail.

#### The TaskJuggler Documentation

- DocBook4 — The DocBook system with additional stylesheets and utilities.

- docbook-utils— The jade wrapper scripts from Eric Bischoff.

- OpenJade — The OpenJade system.

- JadeTeX — If you want to build the Postscript version of the documentation you need the JadeTeX macro package for teTeX.

- XSLT Processor — like xsltproc from the libxslt package.

- Meinproc — the XSLT processor for the KDE Helpcenter. You only need meinproc in case you want to build the GUI. meinproc is part of any KDE distribution.

- dvips — This is usually part of your TeX system like te_latex.

#### Contributed Stuff

Several people have contributed useful tools for TaskJuggler users. These tools can be found in the Contrib directory of the source code package. Please refer to the included README files for installation information.

### Compilation and Installation

Before compiling TaskJuggler you need to set the `QTDIR` environment variable to the base directory of your Qt version. This is normally `/usr/lib64/qt3` or `/usr/lib/qt3`.

To compile and install TaskJuggler on your system, type the following in the base directory of the TaskJuggler distribution:

    % ./configure
    % make
    % make install

Since TaskJuggler uses `autoconf`, you should have no trouble compiling it. TaskJuggler has some weak or non-mandatory dependencies. If any of there are not satisfied, a warning is issued. In case a mandatory dependency is not found, an error is displayed and the configuration program stops. If you have problems, please report them to the TaskJuggler user forum at http://www.taskjuggler.org/FUDforum2 in English. Someone there can help you out.

In case you want to build TaskJuggler without the graphical front-ends, you can disable them during them configuration process:

    % ./configure --with-kde-support=no --prefix=/usr/local
    % make
    % make install

## Usage

### Basics

TaskJuggler uses one or more text files to describe a project. The main project should be placed in a file with the `.tjp` extension. This main project may contain several sub-projects. Such sub-projects should be placed in files with the `.tji` extension. These sub-projects are included in the main project during compile time.

When TaskJuggler is used with other tools the project description or the reports may also be in XML format. The recommended extension for such files is `.tjx`.

### General Usage

To use the graphical front-end simply start it from the menu. Depending on your Linux Distribution you will usually find it under Office/Project Management or a similar entry. To start it from a shell type

    % TaskJugglerUI

The commandline version of TaskJuggler works like a compiler. You provide the source files, it computes the contents and creates the output files.

Let's say you have a project file called `AcSo.tjp`. It contains the tasks of your project and their dependencies. To schedule the project and create report files you have to ask TaskJuggler to process it.

    % taskjuggler AcSo.tjp

TaskJuggler will try to schedule all tasks with the specified conditions and generate the reports that were requested with the htmltaskreport, htmlresourcereport or other report properties in the input file.

### The Command Line Options

- --help
- Print all command line options with a short description.
- --version
- Print the version and copyright info.
- -v
- Same as '--version'.
- -s
- Stop TaskJuggler run after syntax check. This option is for testing and debugging purposes only.
- -M
- Output fragment of a Makefile that lists the dependencies of the passed TaskJuggler files.
- --makefile <file>
- Similar to '-M' but write the dependency information into the specified file.
- --maxerrors N
- Specifies the number of errors after which TaskJuggler stops checking the input files. If N is 0 all errors are displayed.
- --nodepcheck
- Do not check for dependency loops. The loop detector uses an algorithm that needs exponentially more time the bigger the dependency network gets. So for large projects it can be desirable to skip the dependency loop detection. This does not affect the task scheduling but can lead to error messages that are difficult to associate with the dependency specification that is wrong.
- --debug N
- Print debug output, N must be between 0 and 4, the higher N the more output is printed. This option is for testing and debugging purposes only.
- --dbmode N
- Limit debug output to certain modules of the code. N is a bit mask. Each set bit activates output of a certain module. Currently the following modules are supported: Project File Reader (1), Project Scheduler (2), Task Scheduler (4), Resource Scheduler (8), Expression Tree Evaluator (16). This option is for testing and debugging purposes only.
- --warnerror
- Warnings are treated as errors.
- --updatedb
- Update the Kotrus database with the new resource usage information.

Calling TaskJuggler with . as input filename will cause reading from stdin. To redirect output to stdout you can specify -- as filename for reports. This feature can for example be used to generate dynamic HTML pages from CGI scripts.

### Reporting Bugs and Sending Feedback

All official releases of TaskJuggler are meant to be stable releases unless explicitly noted differently. But our test suite is still very small and some features are not tested automatically very well. So it's very likely that your current version of TaskJuggler contains some bugs. If you find a bug please follow this procedure:

- Read this manual to make sure that it is actually a bug and not a feature.

- Check the TaskJuggler web page. Possibly the bug was already found and a patch or workaround exists.

- Try to create a test project that is as small as possible but still reproduces the bug.

- Send the test project and a detailed description of the problem to the developer forum at http://www.taskjuggler.org/FUDforum2.

&FirstProject; &UsageGuide; &SyntaxReference; &PropertyReference;

## The Example: Accounting Software

&Example;

## Migrating from TaskJuggler 1.x to 2.x

### Achieving compatibility

Are you also frustrated by tools that can't read the data of their earlier incarnations? After all those files contain your valuable data and the first impression that the wonderful new version makes is it's failure to read your old files. With TaskJuggler we like to spare you such situations as much as possible. But TaskJuggler 1.x was written to solve the problems that we encountered. By releasing it to the general public we learned that TaskJuggler is also very useful to many other people. Some contacted us to tell us that it would be even more useful to them, if TaskJuggler could have this or that new feature. In many cases we added these new features but we learned more and more that some parts of the original TaskJuggler design were not flexible enough to support some new features. For TaskJuggler 2.x we decided to change TaskJuggler to a more flexible design even if this meant that some syntax constructs would no longer be supported.

As TaskJuggler uses plain text file as its main data format, you will always to able to read in your old files. But in some cases, you need to change certain syntax constructs to the new syntax. When TaskJuggler processes a file with deprecated syntax it will generate an error message. This usually contains a hint, how the statement should look like in new syntax. The following sections discuss the conceptual changes and what statements need to be changed.

#### Syntax changes

TaskJugger 1.x could only handle two scenarios with the fixed name `plan` and `actual`. TaskJuggler 2.0 can now handle any number of scenarios. Scenario specific task attributes have to be prefixed with the scenario ID followed by a colon. The attributes starting with 'plan' or 'actual' have been deprecated.

HTML reports are now a lot more flexible. New CSS elements have being used and the table elements are customizable now. Old stylesheets will no longer work, since the attribute names have changed. A HTML report contains CSS attribute class specification if you provide a custom stylesheet definition with rawstylesheet.

The scenario name is no longer displayed by default if more than one scenario is included in a report. A column `scenario` must be explicitly added if the scenario name should be reported for each line. The attributes 'showactual' and 'hideplan' have been deprecated. The scenarios attribute now controls which scenarios should be shown.

The format of numbers and currency values can now be specified with numberformat and currencyformat. The old keyword currencydigits has been deprecated.

workinghours and currency are no longer global properties. They are now optional attributes of the project property.

Container tasks in export reports no longer have fixed start and end date if they have their sub tasks exported as well.

The functions for Logical Expressions are now using capital letters to improve their readability. The all lowercase versions are still supported, but the recommended versions are now the ones with intermixed uppercase letters. `isTaskOfProject` was added as new query function.

Support for new XML format has been added. The old format is still supported. TJ can read both old and new format XML files but will use the new XML format for output.

#### Scheduler changes

Length and duration tasks with resource allocations are no longer trimmed to the first and last resource allocation. This can lead to different schedules.

'length' based task now use the global working hours and global vacation settings as a criteria of what is a working day. The tasks now always end during working hours and not at midnight.

The maximum allocation of a resource for a task is no longer limited by default. maxeffort now defaults to 0 (unlimited) instead of 1.0 (8 hours per day). To have the same behaviour as in TaskJuggler 1.x version you need to specify `maxeffort 1.0` before any resource definition. This change was made since many users were confused when after increasing the daily working hours resources were still only allocated 8 hours per day.

## Questions and Answers

### General Questions

Q: Why does taskjuggler use Qt when it's not an X11 application?

A: Qt is a very powerful library that is much more than just a widget library. TaskJuggler uses Qt for all kinds of internal data types like lists and arrays. It also uses the Unicode functions, the SQL database interface and the XML support of Qt.

### Compiling and installation

Q: Can TaskJuggler be compiled and used on Windows?

A: Probably yes, but we have never tried it. It should compile but may require some minor tweaks of the source. You should have good knowledge of C++ and Qt when you try this. Please let us know if you were successful.

### Usage

Nothing here yet.

## Copyright

TaskJuggler Copyright 2001, 2002, 2003, 2004, 2005 Chris Schläger <cs@suse.de>

This program is free software. You can redistribute it and modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

## Trademarks

Linux is a registered trademark of Linus Torvalds.

KDE and the K Desktop environment are a registered trademark of KDE e. V.

TaskJuggler is a trademark of Chris Schläer.

UNIX is a registered trademark and The Open Group is a trademark of The Open Group in the US and other countries.