Installing Teamwork via console

A Debian console.
A Debian console.

This is a post for Linux-console lovers.

We have done a big effort to obtain a reliable and friendly graphical installer; but still we received several requests for detailed instructions for hand installations in a non graphical environment, as this is often where Teamwork gets installed when out of the evaluation phase. So we provide here complete instructions, taken from the installation guide.

Complete installation by hand

We assume that you have Java’s JDK 5 or 6 already installed, and also a Tomcat running. If you don’t, download and install those first.

We are also assuming that you are not deploying as an unpacked war, as the web app needs to write in its folders, so if you want to use a war, you must use a “unpacked” war.

1.    Download and extract the archive version of Teamwork here (zip, gz, or rpm)

2.    Take the folder Teamwork, it contains the folders and files shown in the picture.


This is the web app you need to install (you may remove .install4j).

3.    Copy the web application inside your Tomcat webapps, in a folder with the name you please, say “teamwork”. You must ensure that it is using JDK 5 or 6.

4.    In WEB-INF/ you must write the JDBC connection data and other configurations, an example config for MySQL:


5.    In WEB-INF you must also create a file file in which you paste the evaluation license, for example


The license can be generated any time here, by clicking on “Generate a free evaluation key”.

6.    This done, you may launch the web app; if you did the deploy operations while Tomcat was running, you may need to restart the web app. If the JDBC configuration is correct (this is most frequent mistake), the application will start, create the tables and insert sample data; you may now browse to the web app and you’ll be asked for login.

7.    DEBUG If the web application “started too soon”, and say the insertion of sample data failed, open
remove the lines

And restart the web app.

8.    Remember to set the repository, file storage, indexing etc . paths in the admin pages.

If you are deploying under JBoss, take care of the Hibernate (including Annotations and Search) version you are using, Teamwork provides its own, and it must be the same.

Effortless work logging

The worklog day on my dashboard nicely filled.
The worklog day on my dashboard nicely filled.

Yesterday I was about to go home and before leaving on my Teamwork dashboard I noticed that my worklog was already all there without me having to insert it: I just opened and closed issues all day (one click for any of these) and.. the log was all already there!

I don’t love recording work logs, actually, I hate it and often just don’t do it; but since issues are just so easy to add/close, and they really help me “get things done”, I’m now getting work log recorded for free: nice!

In other words, with the effort of a to-do list I’m filling the requirements of a project-management app. What made a difference is that the in-line multi edit of issues is so fast to operate, and so easily linked to my different tasks, that it is my sole entry point in Teamwork, where I insert all my work. It was also important that even if issues come from different tasks, as long as I am focused on myself I can sort them, and give my chaotic day an order, with very very little effort. In this, Teamwork version 4 really solved the problem.

Multi editing/ordering issues.
Multi editing/ordering issues.

Teamwork Webcast #2 – IT integration

teamworkWebcast#2In this webcast Silvia Chelazzi and Pietro Polsinelli (I’m the latter, posting this) talk about Teamwork and IT integration. We focus the talk on built-in integration with other technologies.We talk about Subversion, Twitter, LDAP, ICal / Google calendars / Outlook, POP3/s SMTP/s IMAP, Microsoft Project / Basecamp import / export, Google docs, PDF /Excel exports; so it is a bit long…

We don’t talk about how you may get to integrate technologies by yourself, maybe that will be a topic for a future talk.

See the webcast in our player here; or see it on Vimeo here.


References in and around the webcast: the IT integration part is documented on the web site here and here and in the user guide.

Notes on webcast #1 are here.

Managing with lists vs. managing with trees

listOrTreeThe field of “software aided project management”, which should by now more aptly named “web based work management” today can be divided by two basically different approaches to management: list based, and tree based. There are also other approaches, like “let’s just use a blog/a wiki”, or “e-mail is the way to go”, but I believe these to be simply a bit too naive.

The reference application for “managing with lists” is Basecamp, an excellent “work management” application built by 37Signals, which became famous by building RubyOnRails, a web development framework.

Basecamp is considered a prime example of a “project management 2.0” application, changing the old approach to the problem: purely online (but this is not such great news), and based on the idea of to-do list, with a very very very simple user interface. This in contrast with more classical Gantt-based planning. It also looks so simply done that it has also uncountably many clones, see e.g. this discussion and links, but the original is probably better, and keeps improving.

Before releasing Teamwork 4, we studied (among many other usability books) Defensive Design for the Web: How to improve error messages, help, forms, and other crisis points, a book still by 37Signals, which gave us some good ideas which you see for example in Teamwork 4 error page.

Teamwork could hardly be more different from Basecamp, as we disagree on the basic philosophy: we still think that the good way to model management problems is with the project tree / assignment  notion (though not necessarily presented through a Gantt graph), and not with to-do lists.  We share with 37Signals the idea that the user interface should be as simple as possible, and that usability concerns should be at the center of development. But we also believe that usability is not necessarily synonymous with poverty of features and integrations.

The difference between lists and tree based management may seem misleadingly small: notice that for example it touches on whether the order of things to be done is just as the order in the list, or is linked to dates. There are far-reaching consequences of this assumption: it is difficult to imagine how ordered lists can be the source of a shared organization, instead of being the result of a shared planning tree of events and dates. These results in completely different applications: Basecamp with a universal dashboard, Teamwork with dates, projects, and different views for different users. And it would be a big mistake to think that one can be somehow transformed in the other.

You may ask: why can’t I have both? In fact, both applications do some of both approaches, but it is a general philosophical choice that has been done: Basecamp has a minimal modeling structure, Teamwork tries to keep it maximal, giving all options to the users. If you are familiar with Teamwork, “trees” (projects) do indeed “manage” lists (issues and to-do’s), but you can’t do without the central notion of assignment, linking “branches” to “leafs” (people).

Teamwork also tries to embrace the existing IT infrastructure (so it can become complex to configure), and hence it is not necessarily an online service: not a purely “web 2.0” service in this.

On how to improve usability, without impoverishing the model, see for example this blog post. Also if you want to try switching from lists to trees, Teamwork provides an import from Basecamp, see the user guide, section “Escape from Basecamp”.

So, between lists and trees, the choice is yours…

The name and logo for Basecamp and 37signals are registered trademarks of 37signals, LLC. Teamwork and Open Lab are in no way affiliated to Basecamp or 37signals, LLC.

Smarter search and recent object functionality

Here we examine a technique to improve usability in complex applications by introducing smarter search and “recent objects” functionalities. As usability becomes more and more a crucial feature of applications, helping users with full-text search and recent object lists may still prove insufficient. You may need to go beyond these features, by having a way to keep track of “most used” objects, which will help to:

– guess what you are looking for

– find what you are searching for

The problem

Lets see an example.

In these weeks you are working on items A, B and C of your favorite web application. Friday, you actually briefly worked on X, Y and Z before going home, as you had these for quite a while in the bottom of your to-do list. Now, you get back to work on Monday, and what you have in your “recent objects” list? Well, X, Y,Z. Useless. But you have full-text search. You search for the name of A, which actually hundreds of other objects share, and which maybe there are far more occurrences than in A, even if nobody has been using them for quite a while, so they fill results on top of your A. Useless. There is no easy way to get back to A: something here is not working.

This is a usability problem; in order to make your application more helpful, you should somehow keep track of what is being used most often by the users. How to do that? A complete answer is not trivial: as often happens in usability problems, what looks simple from the point of view of the user, is actually complex to solve and render. In the end, all complexity should be hidden, but the solution is not trivial.

Area of focused interest
Area of focused interest in time.

What is relevant to you is not just stuff that you occasionally visited, but say projects or documents to which you recently returned to again and again: you need to keep in focus a window of attention. See it in this way: you want the projects or documents to which you are frequently linking to. You need a sort of personal page rank.

Recording hits

Well, the way to go is record what are doing; you have to record it somehow as a parallel, probably de-normalized table of “hits”, keeping it very simple, as you will probably get quickly really a lot of records there.

A sample hit collector class in Java/Hibernate
A sample hit collector class in Java/Hibernate

In the picture you see an example “hit”, when a user looks and/or works on something. Notice that as you will collect a lot of data, you will need to filter out in function also of your security model: that is why we have the “areaId” field there.

Now however you decide to collect hits, you will have to meet the problem of how to weigh them, that is, have a hit rank function defined on users, objects and time.

In our implementation, we created a function that for every Teamwork user and every entity (be it task, issue, diary entry, document, worklog action) computes the user hit rank for the entity; if the entity is relevant for the user, the hit rank will be high. Rank gets high by “hitting” i.e. visiting an entity.

As we said before, interest is assumed to fade in time, otherwise you’d end to have too many entities with high rank: so you have to define a sort of window of attention, with a degradation of relevance.

gaussian GaussianParameters

You need a way to compute degradation of relevance; we defined degradation with the rigth side of a Gaussian curve with the constants in the code.

Hit rank can be refined to group rank notion, if your application has a notion of workgroup, so that you could define the activity of the group. Another benefit of hit rank is that you can efficiently monitor your application usage, or “activity”, and could lead to introducing badges et cetera.

Example implementation

An example implementation is in Teamwork: as it includes project management, business processes and groupware, there are many objects around. Hit rank has proven useful in a number of ways to improve usability, without impoverishing the model.

“You mostly visited” is a portlet which you may have on your dashboards, and you also see search results ranked:

Your highest ranked entities.
Your highest ranked entities.

Configuration of rank portlet.
Configuration of rank portlet.

Search results ranked.
Search results ranked.

In this way you should always have “at hand” what you’re really working on: you should be able to access your most relevant objects with one click.


Google’ page rank paper: The Anatomy of a Large-Scale Hypertextual Web Search Engine

A discussion on badges:

An introduction to full text search:

Hibernate full-text search:

Our contribution to Hibernate full-text search:

See hit rank in action in the demo or by installing the web app.

See an interesting infographic here Anatomy of a Search Engine by First Site Guide

Teamwork 4.0.8152 with Gmail service support

Rounded search.
Rounded search.

Now you can use a new Gmail (©Google Inc.) account as Teamwork’s, and send and receive e-mail to and from that account; see the user guide for instructions.

Technically, introduced support for pop3s and smtps and, in theory, for imap (experimental).

In this release we also have:

– prettier search and send message
– area managers have link to area and roles
– nicer forgot password

Download the update here.

Teamwork 4.0.8063 released

This is a functionally minor update. with some nice bug fixes. We’ve also updated the user guide.

– Friendlier file storage editor
– On shutdown HsqlDB files get optimized
– Smarter full text search user “t:” shortcuts etc.
– Check overwork runs only if estimation is >0.

Bug fixes
– Bug on full text search in case of “:”
– Fix for schema evolution HsqlDB

Attempts to manage work with social networks: Twitter limits

One of the open discussions I’ve found wondering on the web is about people who try to manage their work with social networks. Since I’m a developer of a work management software and at the same time I’m social network addicted, I find this topic quite interesting. My first consideration is that social networks can be used to manage work only if your needs are limited, for example if you need only to log your time; for this, some use Twitter. This friendly little tool lets you share brief contents, send message to friends and trace activity in time (by scrolling it 🙁 ).


Reading blog discussions about social tools for management, I gather that who uses Twitter for work management, uses it also to log personal experiences and communicate with friends.

Probably if you write a twit every hour, it comes natural to use Twitter as time tracking tool, moreover with the  @tag you can send personal message, creating a sort of work group. Using Twitter in this case is a good way to save time considering that you will probably spend the same time on it even if you don’t use it for work!

However I can’t believe that users are satisfied from this service. The other day I read the post of Seth Godin Love(and annoying) and I immediately connected his words with my consideration about Twitter. Seth Goding said that

“If people love it, they’ll forgive a lot. They’ll talk about it. They’ll promote it. They’ll come back. They’ll be less price sensitive. They’ll bring their friends. They’ll work with you to make it better.”

But he doesn’t say that if people love it, they also probably will use it in a way that hasn’t been foreseen: using Twitter to manage work is a very clear example of this, and it happens all the time with many other applications like Excel, for example. This is fine, as long as you don’t want to extract information afterwards….
Twitter can log your activity but it can’t tell you which twits go where and how much time you have spent on a specific project, you can only calculate it by hand.
I think that the needs of work groups that really want to organize their work can’t be satisfied from what Twitter gives; it wasn’t meant to give more, it’s the above usage which is forced.
My conclusion is that some people use Twitter to manage work only because they love using Twitter, and having it as work tool sometimes is a good excuse to use it frequently :-).

Silvia Chelazzi
Follow me on Twitter (I have no fear of paradox)

Scrum tools: visually creating Sprints – a mockup

In this post we refer to Scrum and Sprint, which are terms taken from the Scrum management methodology: see here for an introduction.

Following Skype, Twitter and e-mail discussions with Rick Cogley, looking for example at Scrum-ban, we thought about how to improve the current Scrum module, creating a more “visual” interface for creating Sprints.  So this is our first mockup of the new “create sprint” page:

Teamwork visual Sprint creation page- first update
Teamwork visual Sprint creation page- first update

Now if you have a suggestion for this interface, just download the mock-up here, modify it and publish the link on our UserVoice or send it back to me (ppolsinelli at open – lab dot com).

Teamwork is (fortunately) not just a specific Scrum tool, in fact in the same company different methodologies may be used in different projects; sometimes only some parts of a methodology may be used. For example, in Open Lab we use pair programming and short cycles, taken from XP, but we do not use test-first coding; Teamwork is flexible enough to adapt to all these, so that you may use a single tool to manage differently structured projects.

First update. Received a mock-up with suggestions from Mr. Cogley:

Cogley update #1
Cogley update #1

adopted all, apart from “info on tasks” as left side is a single backlog hence from a single task. Thanks!

How Teamwork is made with Teamwork

The guys developing Teamwork are indeed using Teamwork for managing work. How we do that? Well, even in our small group, people have different functions and habits. We have two areas, production and accounting; inside prodution, there are people with different roles, and consequently see and use different data, to which the interface adapts seamlessly. We extensively use the dashboard customization functionalities so that everybody sees what they want.

Some issues editable in place.
Some issues editable in place.

Teamwork 4 has won the long-standing war with paper. We have to confess that for some short-lived issues, some of us (including me) were still using post-its and notes on paper as an integration of issues. But Teamwork 4 won: the Ajax issue multi-editor is just too practical. There is no more paper on our desks; add Balsamiq mockups for replacing paper interface drafts, and the coverage is complete.

We cross post issues and bugs, which we get notified thanks to the subscription engine.

Worklog reads from Twitter and Subversion
Worklog reads from Twitter and Subversion

Teamwork worklogs are inserted with help from Twitter and Subversion logs, which Teamwork 4 does natively.

A section which is widely used is the agenda integrated with meetings, which as it synchronizes with our e-mail clients, is quite practical.

stickyNotesWe use boards too, for example to collect notes for our technical meetings. Careful collection of worklogs allows to monitor costs, and also comparison between releases, cost per team etc. .

For authentication, our Teamwork is integrated with our Active Directory. As we are  “advanced users” :-), we have added to the scheduled jobs a “SiteAliveTester” job which tests that our servers are up and sends e-mail alerts.

Strategic company news.
Strategic company news.

We have added some parts to the defaults, such as RSS reader, user voice reader.

Of course we also use news, for example to publish scores of our table-tennis tournament!

Teamwork and multilinguism

Teamwork 4 interface in German
Teamwork 4 interface in German

Teamwork’s translation in German is almost ready, thanks to Koelnticket, in particular Andreas Nebinger (thank you Andreas!). Let’s see a bit in detail how we dealt in general with internationalization issues in Teamwork; actually this set of problems will have to be met by any sufficiently powerful web application.

There are many senses in which an application might be said to “support multi-languages”, or be “internationalized”:

Interface. Labels and messages of the web interface are available in several languages. Teamwork contains a label editor, where you can create a new language and also modify existing labels.  Teamwork is used in 43 countries, almost all using it in English; actually some project managers like to have it English as teams are made from people from different countries, so it encourages communication.

Teamwork multi edit labels

But as usual 🙂 Teamwork does more: it lets you change labels on the fly in the web interface, saving them on the database so that you don’t lose customizations on application update.

Some fake data in Chinese

Data. Data inserted in the application can be inserted in any language. We have been careful about the encoding (always a problem in web applications), so that the full spectrum of UTF-8 supported languages is included, which means also Greek, Cyrillic, Arabic, Japanese… . This also assumes that the database on which Teamwork is running supports Unicode or UTF-8 data. THen you have the further problem that labels and data you have on the interface may need to be channeled on a different mean, e.g. exported in an Excel file, or in a PDF, and there again you may be plagued by encoding problems.

Search. (This is often forgotten) Full-text search requires multi-language stemming of contents: this is from our technical contribution, which is in the context of Hibernate (an object/relational tool) and Lucene (an indexing engine):

You need to know the language in which a document is written, in order to correctly index it; once you know the language, you can instantiate say the Snowball analyzer with the correct language stemmer. To make a practical system, you will need to guess the documents language from its content. We have found a very simple and effective solution […].
In order to make a content “findable” also when searching from a language (say, German) a document in another language (say, English), we actually double indexed the content field, once with the nowball analyzer and once with the simple StopAnalyzer; so that if you are searching from German and you search “Telefunken”, which stemmed would be searched as “Telefunk”, will find also “Telefunken” in English documents ? .

See and

So Teamwork’s full text search is language-aware. Actually search in Teamwork is much smarter than that, but this is a topic for another post.

Documentation. Documentation may be provided in several languages. In Teamwork’s case, as it is by now in 99% of the web applications, it is provided only in English. We also believe that it will be the “power user” of the application that will mostly need documentation, and we assume that she/he can read English.

So how can we evaluate Teamwork w.r.t. all these aspects?

Feature How it is dealt with in Teamwork
Interface Available in English and Italian. German is almost ready, Spanish is planned.
Data Data in all languages is supported (UTF-8 supported).
Search Stemming is available for all Lucene analyzers: Teamwork provides out of the box English, Spanish, French, German, Portuguese, Italian, Swedish, Danish, Dutch, Norwegian, Russian, Finnish, but it is easy to include other Lucene extensions.
Documentation This is provided only in English.

A F.A.Q. on Teamwork’s site talks about changing labels: