| << Software << | Table Of Contents | >> TaskJuggler_Internals >> |
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.
project "Example" 2007-05-29 - 2007-07-01 {
timezone "America/Denver"
scenario plan "Planned Scenario" {
scenario actual "Actual Scenario"
scenario test "Test Scenario" {
active no
}
}
}
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 set the active attribute to no.
task t "Task" {
start 2007-05-29
actual:start 2007-06-03
test:start 2007-06-07
}
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.
By default, the scheduler tries to guess the right priority of tasks. The higher the priority, the more likely it will get the requested resources. To override this mechanism, the priority attribute can be used.
task jobs "Project breakdown" {
start ${projectstart}
task work "The regular work" {
effort 20d
priority 500
allocate tux
limits { weeklymax 25h }
}
task support "Customer Support" {
# This is a high priority task. Due to the high priority tux is
# spending the required daily maximum on it.
end ${projectend}
priority 800
allocate tux
limits { dailymax 2h }
}
task conference "Attend Conference" {
period 2011-04-25 +2d
allocate tux
priority 1000
}
task maintenance "Maintenance work" {
# This is a fallback task. Whenever tux is not doing something
# else he is allocated to this task.
end ${projectend}
priority 300
allocate tux
limits { weeklymax 2d }
}
}
In the above example, the regular project work needs to be frequently interrupted by the Customer Support task. It's only 2 hours a day, but it's pretty important that this is done. Since the task has a higher priority than the regular work, the scheduler will try to ensure that a maximum of 2 hours per day is spent on support. There is no guarantee, that the task will always get the resource for 2 hours each day, but it's pretty likely in this setup.
There is only one task that is more important, the Attend Conference task. It has fixed dates and we want to make sure Tux can attend. So we use priority 1000, the highest possible priority. There should be only one such task. If not, you need to ensure that the top priority tasks don't compete for the same resource in the same time frame.
In contrast to the support and conference task, the Maintenance work task is a fall-back task. It has a lower priority than the regular work. Tux only gets assigned to it when there is no other work. We have limited the regular work to 25 hours per week. Since we spend up to 10 hours per week on support, there should be a remainder of 5 hours per week for the maintenance task. Again, no guarantees given.
If you want to ensure that a certain minimum or maximum effort is spent on a task, you can use the warn attribute. This will not affect the decisions of the scheduler, but at least it will trigger a warning if your criteria are not met.
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. As the work progresses, you continuously review the state of the project and update the plan accordingly. A weekly review and update cycle seems to be pretty common for most projects. Usually the plan for the past week and the reality are mostly aligned. The future parts of the project often are more affected by necessary changes.
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 getting out of control and they are desperate for any help they can get.
Of course, 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.
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.
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 current date. Tasks that have no completion specification will be assumed to be on track and 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.
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 statements. When the past is exactly described by providing booking statements, you can enable 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 either the --freeze option of tj3 or by generating a manual export report. Before we discuss this in more detail, we need to make sure that the plan is up-to-date.
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 the project contributors.
These status updates should be provided by all project contributors on a regular basis, usually once a week. The gathered information 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 the project is in 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 with varying level of details.
All of this creates additional overhead but is usually inevitable to ensure that you complete the project within the given 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 any time recording tools. Please consult with your corporate counsel or legal expert for all geographic regions of your teams before you deploy a time tracking solution.
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 new process.
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.
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.
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 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 postfix as MTA and 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 *.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 taskjuggler server to serve your project.
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.
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.
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.
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.
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.
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.
To ensure that future changes won't change the past of the project, we need to freeze the history of the project. History in this context means which resource worked on what task from when to when. Since TaskJuggler cannot know what level of detail you want to include in the reports, this information has to be recorded with the highest possible accuracy. This means that we have to capture the exact start and end dates for every period that a resource worked on a task.
Unless you use some external time tracking system to capture this information and export it to TaskJuggler, you probably want TaskJuggler to generate this data for you based on the plan information.
Before you can freeze that past part of your project, you need to tell TaskJuggler which scenario should be used for tracking the actual progress. See the trackingscenario documentation for more details on this. Before you freeze your project for the first time, you should make sure that the current date is still before the project start. If that is not the case, use the now attribute to set the current date to the project start:
now ${projectstart}
Once you have frozen the project for the first time, you should remove the now attribute again. It will be automatically updated.
To freeze your project up to a certain date, you can use the following command:
tj3 --freeze yourproject.tjp --freezedate YYYY-MM-DD
This will generate two files, yourproject-header.tji and yourproject-bookings.tji. The header files contains the date of the freeze as a now attribute. You must
include this file at the end of your project header section.
The bookings file contains the resource assignment data. It usually contains many booking entries that look similar to this:
supplement task t {
booking r 2010-02-19-09:00-+0000 + 3.0h,
2010-02-19-13:00-+0000 + 5.0h,
2010-02-22-09:00-+0000 + 3.0h,
2010-02-22-13:00-+0000 + 5.0h,
}
The booking file must be included at the end of your main project file.
In case there are still some discrepancies between the booking data and the actual assignments of the resources, you can edit the booking file to correct the data.
The next time you run tj3 with your project, all assignments prior to the date in the project header file will be taken only from the bookings file. All assignments after this date will be determined by the scheduler according to your provided constraints.
When you run tj3 --freeze again, it will update the header and booking files. Since you have included your booking file, any modifications you have made, will be preserved. That is, the actual data will be preserved, not the formatting since the file will be completely re-generated again.
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:
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.
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.
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.
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.
| << Software << | Table Of Contents | >> TaskJuggler_Internals >> |