== Day To Day Juggling ==

=== Working with multiple scenarios ===

To analyze the impact that a small variation can have on a project,
TaskJuggler supports an unlimited amount of scenarios. Each
additional scenario is a slight derivation of the it's parent. The
task tree structure needs to be the same for all scenarios, but most
attributes can vary from one scenario to another. Several report
types support comparative listing of multiple [[scenarios]].

By default, TaskJuggler knows about one scenario, called
''''plan''''. The name of this scenario can be changed just like you
can add more scenarios in the [[project]] section of your project
files.

<[example file="Scenario" tag="header"]>

This header section defines 3 different scenarios. ''''plan'''' is
the top-level scenario. It has two derived scenarios, ''''actual''''
and ''''test''''. These two scenarios are identical to the
''''plan'''' scenario except for those attributes that are changed
for these scenarios. Normally, all scenarios are scheduled on each
''''tj3'''' run. To temporarily disable the scheduling of a scenario,
you can use the [[disabled]] attribute.

<[example file="Scenario" tag="task"]>

If you prefix an attribute with the scenario ID followed immediately
by a colon, you can specify a value for a particular attribute. Keep
in mind that setting an attribute also sets the same value for ''all
derived scenarios'' of this scenario as well! If you would specify
''''actual:start'''' first and then ''''plan:start'''', the latter
would overwrite the first value again since actual is a derived
scenario of plan.

The syntax reference lists for each attribute whether it is scenario
specific or not.

=== Tracking the Project ===

Once the initial plan has been made and the project has started, TaskJuggler
can be turned from a planning tool into a tracking tool. You don't have to
change a lot to do this. After all, as the initial plan is almost always just a
first guess, you need to continue planning your project as new details become
evident. So what you really want is a way to gradually freeze the plan as work
has been completed, while still having full flexibility with all future work.

While it is generally accepted to invest some amount of time in project
planning, it is very common that once the project has been started, project
managers tend to avoid a proper tracking of the project. Our bet is that the
vast majority of project plans are only made to get management or investor
approval. After the approval phase, many project managers only work with their
project plan again when the project is running really late. On the other hand
there are projects that are done using strict project management techniques
that require detailed status tracking. Both extremes probably have their fans
and TaskJuggler offers good support for both extremes as well as various
techniques in between.

=== Recording Progress ===

As mentioned previously, your initial project plan is only a first estimate of
how the project will progress. During the course of the project you will have
to make changes to the plan as new information needs to be taken into account
and you probably want to track the progress of the project in a formalized
form. TaskJuggler will support you during this phase of the project as well,
but it needs your help. You have to provide the additional information in the
project file. In return you get current status reports and an updated project
plan based on the current status of the project.

==== Using completion values ====

The most simple form of capturing the current status of the project is to use
the complete attribute.

 task impl "Implementation" {
   depends !spec
   effort 4w
   allocate dev1, dev2
   complete 50
 }

This tells TaskJuggler that 50% of the task's effort has been completed by the
[[now|current date]]. Tasks that have no completion specification will
be assumed to be on track. TaskJuggler calculates the expected
completion degree based on the current date. Completion specifications
only need to be supplied for tasks that are either ahead of schedule
or behind schedule. Please be aware that the completion degree does
not affect the scheduling and resource allocation. It is only for
reporting purposes. It also does not tell TaskJuggler which resource
actually worked on the tasks, nor does it update the total or
remaining effort.

==== Using bookings ====

When TaskJuggler schedules your plan, it can tell you who should work
when on what. Now, that's the plan. But reality might be different.
To tell TaskJuggler what really happened, you can use
[[booking.task|booking statements]]. When the past is exactly
described by providing booking statements, you can enable
[[projection|projection mode]].

Entering all the bookings for each resource and task may sound like a
daunting task at first. If you do it manually, it certainly is.
Fortunately, TaskJuggler can generate them for you by using
[[export|export reports]]. Before we discuss this in more detail, we
need to make sure that the plan is up-to-date.

=== Tracking status and actuals ===

Creating a good project plan is one thing. Executing it is a whole
new story. Usually, the first plan is never fully correct and the
only way to make sure that you are making progress according to plan
is to regularly get status updates from all resources.

Status updates should be provided by all project contributors on a
regular basis, usually once a week. These updates should tell project
managers who really worked how much on what tasks and how much work
the contributors believe is really left now. There are two categories
of tasks in a project that need to be treated slightly differently.

A task can either be effort based or duration based. In the former
case, the contributors must tell how much effort is left. For
duration based task, this doesn't make much sense. For these task,
the expected end date should be reported.

In addition to those numbers, managers in the reporting chain usually
want to have a textual status that describes what happened and what
kind of issues were encountered. Usually, these textual status
reports are combined with alert levels like green, yellow and red.
Green means everything is progressing according to plan, yellow means
there is some schedule risk and red means serious trouble. Usually
first line managers like to get all the details while people further
up in the reporting chain only like to see summaries varying level of
details.

All of this creates additional overhead but is usually inevitable to
ensure that you complete the project within time and budget. As a
comprehensive project management solution, TaskJuggler provides full
support for all those tracking and reporting steps. It comes with a
powerful email and web based communication system that simplifies the
tracking process for individual contributors as well as managers.

As a side note we would like to mention that the recording of the work
time of employees is regulated by labor law in certain countries. You
might also require approval from a Worker's Council before you can
deploy time recording tools.

We also would like to point out that introducing status reporting and
time sheets is usually a big change for every staff. Don't
underestimate the psychological impact and the training requirements.
We also recommend to test the described process with a small group of
employees first to get familiar with the process and to adapt it to
your needs. Don't rush a deployment! You usually only have one chance
to roll-out such a process.

==== The reporting and tracking cycle ====

In this description, we assume that you are using a weekly reporting
cycle. TaskJuggler does support arbitrary cycles, but we highly
recommend the described weekly cycle.

# '''Time sheets''': Every project contributor needs to fill out a
[[timesheet|time sheet]] once a week. To simplify this task as much
as possible, a template will be send out by email. The template
already lists all tasks that were planned for this week to work on
with the respective effort values and end dates. It also provides
sections for textual status reports. The contributor needs to review
and complete the time sheet and has to send it back via email.
TaskJuggler validates the submission and returns an email with either
an error message or a nicely formatted version of the time sheet.

# All time sheets must be submitted by a certain deadline, e. g.
midnight on Sunday. TaskJuggler will then compile a summary report
and sent it out to a list of interested parties. It will also detect
missing time sheets and will send out a reminder to those
contributors that have not submitted their report.

# On Monday the project managers need to review the time sheets and
update the plan accordingly. TaskJuggler can compile a list changes
compared to the plan. This makes it easy to update the plan according
to the actual progress that was made. The close the actuals match the
plan the less work this is. The project managers now generate
bookings for the last week and add them to the database with previous
bookings. Doing so, will prevent changes to the plan to affect the
past. Only the future will be modified.

# Once the plan has been updated, managers will receive their status
sheet templates per email. Each manager will get the information for
the tasks that they are [[responsible]] for. To consolidate the
information for the next manager in the reporting chain they can
moderate the reports in three ways. Consolidated manager reports are
called dashboard reports.

## A status report for a task can be removed from the dashboard.

## A status report for a task can be corrected or updated.

## All reports for sub tasks of a task can be summarized by creating
a new status for that task. This will remove all reports for sub
tasks of that particular tasks from the dashboard.

# Managers than need to send back the edited status report via email.
Like with time sheets, TaskJuggler will check them and return either
an error message or a plain text version of the dashboard report of
the manager.

In addition to the plain text versions of the time sheet summaries
and the dashboards, TaskJuggler provides support for publishing them
as HTML pages from a web server.

=== Implementing the status tracking system ===

==== Prerequesites ====

The .tjp and .tji files of your project plan should be managed by a
revision control system. TaskJuggler does not require a particular
software, but for this manual we illustrate the implementation with
[http://subversion.apache.org Subversion]. It should be obvious how
to do this with other software though.

All communication of time sheets and status sheets is done via email.
TaskJuggler has built-in support for sending emails. To receive
emails and to feed them to the correct program, TaskJuggler needs
support from a mail transfer agent (MTA) and a mail processor. In
this documentation we describe the setup with
[http://www.postfix.org/ postfix] as MTA and
[http://www.procmail.org/ procmail] as mail processor. These are
standard parts of any Linux distribution and should be easy to setup.
It's certainly possible to use other MTAs and mail processors, but
this is not the scope of this manual.

Finally, you need a web server to publish your reports. This can
really be any web server. The generated reports are static HTML pages
that can simply be put into a directory that the web server is
serving.

For the email based communication you need to provide email addresses
for all project contributors. This is done in the project plan in the
resource definition by using the [[email]] attribute.

 resource joe "Joe Avergage" {
   email "joe@your_company.com
 }

In this manual, we assume you have a dedicated Linux machine with a
local user called ''''taskjuggler''''. Your project files (*.tjp and
<nowiki>*</nowiki>.tji) is under Subversion control and the
taskjuggler user has a checked-out version in
''''/home/taskjuggler/projects/prj''''. You can use another user name,
another source code management system and even another operating
system like Windows or MacOS. This is all possible, but not the scope
of this manual.

To use the tracking system, you need to setup the
[[Software#tj3d|taskjuggler server]] to serve your project.

==== The Time Sheet Template Sender ====

Each project contributor needs to fill out a time sheet each week. To
simplify the process each contributor will receive a template that
already contains a lot of the information they need to provide.

To send out the time sheets, the command ''''tj3ts_sender'''' must be
used. It will call ''''tj3client'''' with appropriate parameters. To
use it, you need to have a properly configured daemon running and the
appropriate project loaded. Then you need to add the configuration
data for ''''tj3ts_sender'''' to your TaskJuggler configuration file.
The time sheet related settings have their own top-level section:

 _global:
   smtpServer: smtp.your_company.com
   authKey: topsecret
   scmCommand: "svn add %f ; svn commit -m '%m' %f"
   projectId: prj
 _timesheets:
   senderEmail: 'TaskJuggler <timesheets@taskjuggler.your_company.com>'
   _sender:
     hideResource: '~isleaf()'
   _summary:
     sheetRecipients:
       - team@your_company.com
     digestRecipients:
       - managers@your_company.com

The ''''smtpServer'''' defines which host will handle your emails. Replace the
host name with your local SMTP server. The 'scmCommand' setting contains the
command to add and commit new and old files to the source code management
system. The command in this example works for Subversion.

The TaskJuggler server may serve multiple projects. With the
''''projectId'''' option you have to specify which project you would
like to work with. ''''senderEmail'''' is the email address the time
sheet infrastructure will use. Outgoing emails will have this address
as sender so that replies will come back to this email address. We'll
cover later how these are processed.

The hideResource option works similarly to the [[hideresource]]
attribute in the report definitions of the project plan. It allows
you to restrict the sending of time sheet templates to a subset of
your defined resources. In this example, we only want to send
templates to individual resources and not the teams you might have
defined.

By default the time sheets will cover the week from Monday morning
0:00 to Sunday night 24:00. When called without the ''''-e''''
option, ''''tj3ts_sender'''' will send out templates for the current
week.

To call the ''''tj3ts_sender'''' command you either need to be in the
''''/home/taskjuggler/projects/prj'''' directory or use the
''''-c'''' command line option to point it to the configuration file
to use. In the latter case you also need to call it with the
''''-d'''' option to change the output directory to your project
directory.

To test the command without sending out actual emails you can use the
''''--dryrun'''' option on the command line. To do its job,
''''tj3ts_sender'''' needs to generate a number of files and
directories. A copy of the generated templates will be stored in
''''TimeSheetTemplates/<date>/'''' under
''''<resource_id>-date.tji''''. ''''<date>'''' is replaced with the
end date of the reporting interval and ''''<resoruce_id>'''' is the ID
of the resource.

If you re-run the command existing templates will not be regenerated
nor will they be sent out again. You can use the ''''-f''''
command line option to force them to be generated and sent out again.

The ''''tj3ts_sender'''' command will also add the reporting interval
to a file called ''''TimeSheetTemplates/acceptable_invervals''''.
We'll cover this file later on when we deal with the time sheet
receiver.

==== The Time Sheet Receiver ====

To receive the filled-out time sheets and to process them
automatically you need to create a special user. TaskJuggler requires
a number of email addresses to be setup to receive emails. We
recommend to use the following setup. Create a special user called
''''taskjuggler'''' on a dedicated Linux machine. Then create the
following email aliases for this user.

 timesheets
 timesheet-request
 statussheets
 statussheet-request

Your MTA must be configured to use procmail for email delivery. See
the manual of your MTA for details on how to configure aliases and
for using procmail for delivery. If you have a resident MTA expert
you should ask him or her for support.

The next step is to configure procmail to forward the incoming emails
to the appropriate TaskJuggler components. Create a file called
''''.procmailrc'''' in the home directory of the taskjuggler user and
put in the following content:

For debugging and testing purposes, all incoming emails are archived
in a directory called ''''Mail''''. If there is no such directory in
the taskjuggler home directory, you need to create it now.

 PATH=$HOME/bin:/usr/bin:/bin:/usr/local/bin            
 MAILDIR=$HOME/Mail/                                    
 DEFAULT=$HOME/Mail/all                                 
 LOGFILE=$MAILDIR/procmail.log                          
 SHELL=/bin/sh                                          
 PROJECTDIR=/home/taskjuggler/projects/prj       
 LANG=en_US.UTF-8                                       
 LC_ALL=en_US.UTF-8                                     

 # Archive all incoming emails in a file called all 
 :0 c
 all 
 
 :0
 * ^Subject:.*Out of Office.*
 /dev/null                   
 
 :0
 * ^To:.*timesheets@taskjuggler\.your_company\.com
 {                                       
   :0 c:                                 
   timesheets                            
 
   :0 w: tj3ts_receiver.lock
   | tj3ts_receiver --silent -c $PROJECTDIR/.taskjugglerrc -d $PROJECTDIR
 
   :0
   failed_sheets
 }
 
 :0
 * ^To:.*timesheet-request@taskjuggler\.your_company\.com
 {
   ID=`formail -xSubject:`
 
   :0 c:
   timesheet-request
 
   :0 w: tj3ts_sender.lock
   | tj3ts_sender -r $ID -f --silent -c $PROJECTDIR/.taskjugglerrc -d $PROJECTDIR
 }
 
 :0
 * ^To:.*statussheets@taskjuggler\.your_company\.com
 {
   :0 c:
   statussheets
 
   :0 w: tj3ss_receiver.lock
   | tj3ss_receiver --silent -c $PROJECTDIR/.taskjugglerrc -d $PROJECTDIR
 
   :0
   failed_sheets
 }
 
 :0
 * ^To:.*statussheet-request@taskjuggler\.your_company\.com
 {
   ID=`formail -xSubject:`
 
   :0 c:
   statussheet-request
 
   :0 w: tj3ss_sender.lock
   | tj3ss_sender -r $ID -f --silent -c $PROJECTDIR/.taskjugglerrc -d $PROJECTDIR
 }
 
 # Forward a copy to project admins
 :0 c
 ! taskjuggler-admin@your_company.com
 
 # Since we have archived a copy we can discard all mails here.
 :0
 /dev/null

This procmail configuration will cause incoming emails that are
addressed to timesheets@taskjuggler.your_company.com to be forwarded
to the ''''tj3ts_receiver'''' program. Of course you need to replace
''your_comany.com'' with whatever domain you are using.

The received emails are then checked for syntactical and logical
errors. If such are found, an email is sent back with an appropriate
error message. The time sheet contains the resource ID of the
reporting resource. As soon as this has been detected, all email
communication will be sent to the email address in the project plan.
Only when the resource ID could not be identified, the sender of the
email will get the answer. This was implemented as a security measure
so other users cannot easily retrieve project related information
from other users.

Correct time sheets are archived in the ''''TimeSheets/<date>/''''
directory where ''''<date>'''' is the end date of the reporting
period. If the directory does not exist yet, it will be created. The
file will be called ''''<resource_id>-<date>.tji''''. If
a SCM command was specified, the file will be automatically put under
revision control. Subsequent submission of the same time sheet will
simply overwrite the earlier submissions. The file name will also be
added to a file called ''''all.tji'''' which consists of include
statements of all time sheet files in the directory. There also is an
automatically maintained file ''''all.tji'''' in the
''''TimeSheets'''' directory that includes all the ''''<date>/all.tji''''
files. To add all the submitted time sheets to your project plan,
simply include the top-level ''''all.tji''''.

''''tj3ts_receiver'''' will only accept time sheets for the time
periods listed in ''''TimeSheetTemplates/acceptable_intervals''''.
''''tj3ts_sender'''' will automatically enable the current period
when it sends out the templates. If you want to stop receiving time
sheet updates for a certain period, simply remove the period from the
''''acceptable_intervals'''' file.

==== Time Sheet Template Requests ====

Normally, the time sheets are sent out once a week automatically. In
case a project contributor leaves earlier for vacation or has lost
the template, they can request the template for the current week
again.

By sending an email to
''''timesheet-request@taskjuggler.your_company.com'''' and putting
their resource ID in the subject of the email, they will receive an
email with the time sheet template. The email will be sent to the
email address in the project plan, not the sender of the request
email.

==== Time Sheet Summaries ====

All time sheets should be successfully submitted by Sunday 24:00.
After this deadline, your can send out a summary of all submitted
time sheets. This summary will also contain a list of those project
contributors that have not submitted their time sheet. These
individuals will also get a reminder to submit their time sheets
immediately.

To send out the summary report, the program ''''tj3ts_summary'''' is
used. Before you can use it, you need to add a few settings to the
TaskJuggler configuration file.

 _global:
   smtpServer: smtp.your_company.com
   authKey: topsecret
   projectId: prj
 _timesheets:
   senderEmail: 'TaskJuggler <timesheets@taskjuggler.your_company.com>'
   _summary:
     sheetRecipients:
       - team@your_company.com
     digestRecipients:
       - managers@your_company.com

''''sheetRecipients'''' is a list of email addresses that should
receive a copy of the submitted time sheet. Each email address must
be put on a separate, properly indented line that starts with a dash
followed by a space. The emails will have the email of the original
time sheet author as sender address.

==== Updating the Project Plan ====

The time sheets contain two kind of information that are intended for
two sets of audiences. Project managers will be interested primarily
in the scheduling related information but surely like to look at the
task status as well.

Managers responsible for certain parts of the project will be
primarily interested in the status reports for the ongoing tasks.
We'll cover the processing of the status information in the next
sections.

This section deals with the processing of the scheduling related
information. Project contributors can specify several deviations of
the current project plan.

* Task may need more effort or time than was originally planned for.

* They may have not worked the planned amounts on the tasks.

* They may have started to work on new tasks that are not even in the
project plan. The is usually a sign of project discipline and should
be avoided. But in reality this will happen and TaskJuggler is able
to handle it.

TaskJuggler can print a summary of all the deltas between the plan
and the actual reports in the time sheets.

 tj3 --warn-ts-deltas YourProject.tjp TimeSheets/all.tji

In this example call ''''YourProject.tjp'''' is your main project
file and all submitted time sheets are included by
TimeSheets/all.tji. This file and all subsequent include files are
automatically generated and updated by ''''tj3ts_receiver''''.

Project managers should use the printed output of this command to
update the project plan accordingly. The specified deltas of existing
tasks must be updated in the main project plan. For new tasks in the
time sheets, the task has to be created in the project plan. Then the
newtask statement in the time sheet needs to be converted into a
normal task report.

  newtask some.task.id "My new task" {
     ...
  }

Needs to be converted into

  task some.task.id {
    ...
  }

The task ID in the status sheet must match the newly created task in
the project plan.

To check that all deltas were properly processed, re-run the check
command.

 tj3 --warn-ts-deltas YourProject.tjp TimeSheets/all.tji

You may also want to remove the interval from the
''''TimeSheetTemplates/acceptable_intervals'''' file to prevent
further submissions of time sheets for this time period.

=== Recording actual Resource Usage ===

To ensure that future changes won't change the past of the project,
you should follow the procedure described in this section. 

The initial project plan should be made by entering the minimum amount of
required information such as task dependencies and efforts. TaskJuggler will
then compute all the missing data based on this initial setup. This is your
project baseline. As the project progresses you can now track the work already
completed by recording the work that your resources have done. Let's assume you
had the following task in your original plan: 

 task impl "Implementation" {
   depends !spec
   effort 4w
   allocate dev1, dev2
 }

After the first week of work on this task the two resources have really been
able to complete half the job. You can capture this in your project plan using
the booking attribute. Bookings are resource specific, so you have to add the
booking to the resource definition, not the task definition.

 resource dev1 "Developer 1" {
   booking impl 2005-04-11 - 2005-04-16 { sloppy 2 }
 }
 
 resource dev2 "Developer 2" {
   booking impl 2005-04-11 - 2005-04-16 { sloppy 2 }
 }

The sloppy attribute defines the accuracy of your bookings. If it's missing or
0, the booking must only describe a continuous working period during working
hours. With higher values the interval may overlap with off-hour or vacation
time slots. See details on sloppy.

The booking statements are designed to describe actual work performed
by resources at a very accurate level. Many project managers are too
lazy to record information at such a level of detail. TaskJuggler
offers some mechanisms to simplify your work. Using ''''sloppy'''' is
one of them, but you should read very carefully what it does. In
almost every case we recommend to use the procedure described below
instead.

Another popular mistake is that user forget that dates for bookings
behave just like every other date in TaskJuggler.

 resource dev1 "Developer 1" {
   booking impl 2005-04-11 +8h { sloppy 2 }
 }

This is almost a classic on the mailing list. 2005-04-11 means
2005-04-11-0:00. So you are trying to allocate dev1 from midnight to
8am. Since dev1 is usually is off duty at this time no allocations
will be performed. By using the ''''sloppy 2'''' attribute you won't
even get a warning for this mistake.

If you don't like to mix the resource definitions and their bookings, you can
specify the bookings with supplement statements. These supplement statements
can even reside in an other file.

It is ok to specify bookings beyond the effort value found in the task
definition. In case you want to declare a task as done, even if the bookings do
not reach the specified effort or length, you can use the scheduled property.

 supplement task impl {
   actual:scheduled
 }

In case your actual progress does not deviate a lot from your project plan, you
can generate the file with the booking statements automatically.

 export "DoneWork-Week15.tji" {
   hideresource 0
   start 2005-04-11
   end 2005-04-16
   taskattributes *
 }

This will generate a TaskJuggler include file that contains all bookings
according to the project plan for the specified interval. You can then use this
file as a baseline and modify it to reflect the real work that has happened
during the interval. After that you can include it into your project again.

 include "DoneWork-Week15.tji"

As this include file references the tasks and resources of your project you
should include it after all task and resource definitions.

To make TaskJuggler aware that you want to compute the end date based on the
bookings and the effort you need to enable the projection mode for the
scenario. This has to be done in the scenario definition in the project header.
If you don't have a scenario definition because you are only using the built-in
default scenario, you have to add a scenario definition.

 project prj "Project" "1.0" 2005-04-01 - 2005-05-01 {
   scenario plan "Plan" {
     # Compute when the task will be ready based on the already
     # done work and the current date.
     projection
   }
 }

TaskJuggler now assumes that for all tasks that have bookings, all work has
been specified with bookings up to the current date. It then calculates the end
date of the task based on the effort that is still left over. It also computes
the complete value based on the specified bookings. So if you specify bookings
for a task you should not specify a completion value as well. It will be
ignored and replaced by a value based on the specified bookings.

When you now schedule the project again, it will take these bookings into
account and generate a new project plan based on your current project status.
Each time you review your project status you should generate such an include
file for the period that you are reviewing. Then you sync the content with the
feedback that you get from your resources and add the file to the project plan.

==== Status Sheets ====

For larger projects with many contributors the flood of time sheets
can become hard to manage. Higher level managers are usually not
interested in all the details as long as the project executes
according to plan. To keep the managers on each level informed with
the proper amount and content TaskJuggler provides the concept of
status sheets.

To use status sheets, the reporting chains must be reflected in the
task hierarchy of the project. The [[responsible]] attribute must be
used to assign tasks to managers. Leaf tasks or whole sub trees must
be assigned to the lowest level of management. The responsibility for
one or more level of parent tasks must be assigned to the next level
of managers and so on.

When all time sheets have been submitted, the reports for all tasks
are sent to the responsible managers for these tasks. The information
is generated by the ''''tj3ss_sender'''' program and is called a status
report template. Each manager will get one template that includes the
status reports for the tasks they are responsible for.

It's not the managers task to prepare the report for the next level
of management. To do this, the manager has 3 options:

* Forward the status report of a task directly to the next level. The
original authorship can be keep or removed. The content can also be
edited if needed.

* Similar reports for a task or a whole task sub-tree can be combined
into just one report. To achieve this a new task report must be
created for the parent tasks of these lower-level tasks. This will
replace all reports for sub tasks with this newly created report.

* A task report can simply be removed from the status report.

The status sheet template is designed to perform all three actions in
a simple manner. The original reports are commented out. To remove a
report, it needs to be uncommented and the headline must be set to an
empty string. To change a report, the text must be edited after
the comment marks have been removed. To create a summary report for a
group of tasks, a new report for the common parent task must be
created.

==== The Status Sheet Template Sender ====

To send out the time sheets, the command ''''tj3ts_sender'''' must be
used. It will use the ''''tj3client'''' program to do retrieve the
necessary data from the TaskJuggler server.

Before the program can be used, a new section must be added to the
TaskJuggelr configuration file.

 _statussheets:
   projectId: prj
   _sender:
     senderEmail: 'TaskJuggler <statussheets@taskjuggler.amd.com>'
     hideResource: '~(isleaf()  & manager)'

If you are using status sheets for only one level of management you
can hardcode that like in the example above. For multiple level of
management you need to specify which group of managers should the
report templates be generated for and pass that information on the
command line. Use the ''''--hideresource'''' option to specify a
logicalexpression to filter away the resources you don't want
templates to be generated for. The easiest way to achieve this is by
using unique flags for each management level. In the example above we
assume you have assigned the flag ''''manager'''' to each first-level
manager.

For the override mechanism to work, the manager reports must always
have a newer date than the original report. So, the end date of the
first-level manager status sheets must be after the time sheet
interval. The second-level mangers must use a later date than the
first-level managers and so on.

By default ''''tj3ss_sender'''' will use the next Wednesday as end
date. If you need a different date, you must use the ''''-e''''
option to specify that date.

Let's say you have two levels of managers that use status sheets. The
time sheets are due midnight on Sunday. The project managers can work
in the deltas and new tasks on Monday. After that you generate the
reports for the first level managers with and end date of Wednesday.
This implies a submission deadline of midnight on Tuesday. The second
level manager templates will be sent out right after this deadline
with an end date of Thursday. That would be the deadline for the
second-level managers. The final report can than be generated by
TaskJuggler automatically right after that deadline.

==== Requesting Status Sheet Templates ====

Usually the status sheets templates should be send out automatically.
But sometimes a manager needs them earlier or needs an updated
version due to a late incoming downstream report.

The above provided procmail configuration supports the generation of
status sheets templates on request by email.

By sending an email to statussheet-request@taskjuggler.your_company.com
and putting their resource ID in the subject of the email, managers will
receive an email with the status sheet template. The email will be sent
to the email address in the project plan, not the sender of the
request email.

The setup described here only works for first-level managers. By
adding more email addresses, this can easily be extended for more
levels of management. You just need to make sure that
''''tj3ss_sender'''' is called with the proper parameters to change
the resource selection and end date.

==== The Status Sheet Receiver ====

Similarly to the time sheets a the completed status sheets must be
send back by email. We already described how the necessary email
aliases should be configured. For status sheets the address
''''statussheets@taskjuggler.your_company.com'''' can be used.

The incoming emails will then be forwarded to the
''''tj3ss_receiver'''' program that will process them. To use it, you
first need to add the following settings to the ''''statussheets''''
section of your TaskJuggler configuration file:

 _statussheets:
   projectId: prj
   _receiver:
     senderEmail: 'TaskJuggler <statussheets@taskjuggler.amd.com>'
 
This will set the sender email of outgoing emails. Every incoming
status sheet will be checked and either an error message will be
returned or a consolidated status report for all tasks that the
resource is responsible for. This report can either be directly
forwarded to the next level manager or interested groups, or an HTML
report can be generated and shared. This is especially useful in case
the next level management is not getting status sheet templates.

Usually status reports only contain task reports for the current
reporting period. But if there were tasks with an elevated status,
these will be carried forward until they were removed by providing an
empty headline or replaced with a new report for the same task or a
parent task.