### 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.

- 0: No output
- 1: Only fatal errors
- 2: Fatal and normal errors
- 3: Like 2, but additionally with information messages
- 4: Like 3, but additionally with debug messages

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.