The TaskJuggler User Manual

Project Management beyond Gantt Chart Drawing


<< List_Attributes << Table Of Contents >> Day_To_Day_Juggling >>


6 The TaskJuggler Software

After the installation of a software package the first question that most users have is "How do I run it?". Many users expect to find an icon on their desktop or an entry in the start menu hierarchy. Don't bother looking for them, you won't find any for TaskJuggler. As we have mentioned before, TaskJuggler is a command line program. All the components are started from a shell by typing in the command name.

This chapter describes the most important TaskJuggler commands and how to use them. If you haven't used command line programs before, don't worry - you will quickly get used to it.

6.1 tj3

tj3 is the main program that you will probably use the most. It reads in your project files and schedules them. In case there are no errors, it will also generate all the reports that you have defined in your project files. It requires at least one parameter, the name of your main project file. In case your main project file is called tutorial.tjp you can process it by typing

tj3 tutorial.tjp

You will see an output similar to the one below.

 > tj3 tutorial.tjp
 TaskJuggler v3.0.0 - A Project Management Software
 
 Copyright (c) 2006, 2007, 2008, 2009, 2010, 2011 by Chris Schlaeger
 
 This program is free software; you can redistribute it and/or modify it under
 the terms of version 2 of the GNU General Public License as published by the
 Free Software Foundation.
 
 Reading file tutorial.tjp                                    [      Done      ]
 Preparing scenario Plan                                      [      Done      ]
 Scheduling scenario Plan                                     [      Done      ]
 Checking scenario Plan                                       [      Done      ]
 Preparing scenario Delayed                                   [      Done      ]
 Scheduling scenario Delayed                                  [      Done      ]
 Checking scenario Delayed                                    [      Done      ]
 Report Overview                                              [      Done      ]
 Report Status                                                [      Done      ]
 Report Development                                           [      Done      ]
 Report Deliveries                                            [      Done      ]
 Report ContactList                                           [      Done      ]
 Report ResourceGraph                                         [      Done      ]

tj3 supports a number of runtime options that control the behavior. Please use the --help option to get more details.

tj3 --help

6.2 tj3man

tj3man provides you with a quick access to the syntax reference. If you run it without further parameters it will print a list of all syntax keywords. In some cases, keywords can be used in different contexts with different meanings. These keywords are listed multiple times with the context identifier appended separated by a dot. E. g. the shift keyword can be used in the global context, in the resource, task and timesheet context. It will be listed as

shift
shift.resource
shift.task
shift.timesheet

To get more information about a specific keyword you need to provide it as parameter to tj3man.

tj3man shift.task

The same information that is available in your shell is also available in your web browser.

tj3man --html <keyword>

The latter defaults to using the Mozilla Firefox web browser. Please see

tj3man --help

how to use a different browser. If you omit the keyword, you will get this user manual (browser).

6.3 tj3d

tj3d is the TaskJuggler daemon. It is a program that runs in the background, disconnected from your shell to provide certain services. It can generate reports on demand and processes incoming time sheets or status reports.

Depending on the size of your project the scheduling time can take several minutes or more. Since all operations need to be done on the data of a scheduled project, it makes sense to have this data readily available. This is the job of the TaskJuggler server or daemon in Linux lingo. The program is called tj3d. When started, it automatically disconnects from the terminal and runs in the background. All interactions with the server are done via the TCP/IP protocol. For security reasons, only connections from the same machine (localhost) are accepted. To get access, all clients must provide an authentication key. A TaskJuggler server can serve any number of projects. Once a project has been loaded successfully, clients can retrieve the data in form of reports. Projects are identified by their project ID. If a newly added project has the same ID as an already loaded project, the new project will replace the old project once it was scheduled successfully. Before you start the server, you need to provide a configuration file with some basic settings.

All taskjuggler components can use the same TaskJuggler configuration file. The format is a simple plain text format that follows the YAML specification. The file should be called .taskjugglerrc or taskjuggler.rc. The settings are structured by sections. Section names always start with an underscore.

_global:
  authKey: topsecret
  _log:
    logLevel: 3
    outputLevel: 3

This file sets the authentication key for all TaskJuggler components. You must replace topsecret with your own random character sequence.

For the purpose of this documentation we assume you have a local user called taskjuggler and your project data in /home/taskjuggler/project/prj. Your TaskJuggler configuration should then be put into /home/taskjuggler/project/prj/.taskjugglerrc.

The log section controls the content of the log file. Since the daemon does not have a terminal attached to it, all messages are stored in a file called tj3d.log. For debugging purposes, you can use the -d option to prevent the daemon from disconnecting from the terminal. In this case the outputLevel configuration option controls the amount of details to be printed out.

The configuration file will be searched for in the current directory, the current user's home directory or /etc. You can also explicitly tell the server where to find the configuration file with the -c option. See

tj3d --help

for details.

So far, the daemon has not received any kind of security review. We strongly advise you to only use the daemon in a trusted environment with only trusted users!

6.4 tj3client

To control the TaskJuggler server, you need to use the TaskJuggler client. You can use the client to add or remove projects from the server, inquire the status of loaded projects. It can also be used to show the available reports for each project and to generate report or check time or status sheets.

The client must provide the correct authentication key to the server. You need to ensure that it can find the proper configuration file with the authentication key.

tj3client --help

will provide a full list of supported commands. To load a project simply type

tj3client add yourproject.tjp

In case there were no errors

tj3client status

should now list your project.

tj3client list-reports <project_id>

shows a list of available reports for the project with the provided ID. To generate a report, you can type

tj3client report <project_id> <report_id>

A server that is running can be terminated with the following command.

tj3client terminate

6.5 tj3webd

This is a web server to serve the HTML reports of a project to any web browser. The HTML reports are generated on the fly when accessed. tj3webd requires that tj3d is already running on the same machine.

By default, the web server is listening on port 8080. This can be changed in the _global section of the config file.

_global:
  authKey: topsecret
  webServerPort: 8080

To access the HTML reports, point your web browser to http://localhost:8080/taskjuggler. This assumes that the server is running on your local machine. You will then see a list of all loaded projects. Click on the project name to get a list of all reports for this project.

WARNING: Please be aware that the web server when you have started it can be accessed by anybody on your local machine and by anybody that can reach your machine over the network! It will serve all reports of all projects that are hosted by the TaskJuggler daemon.



<< List_Attributes << Table Of Contents >> Day_To_Day_Juggling >>


Copyright (c) 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 by Chris Schlaeger <cs@taskjuggler.org>.TaskJuggler is a trademark of Chris Schlaeger.