Tutorial – Wekan

Kanban, the Japanese word for signboard, is a workflow management system for organizing and tracking work. Kanban boards show team members the status of each task at any given time, including ownership and task order, with the aim of limiting the number of tasks "in progress" at any given time.

First developed in the 1980s to improve the efficiency of Toyota's assembly lines [1], kanban has proven its usefulness as a general-purpose organization tool. Today, people use kanban for everything from simple personal to-do lists to coordinating teams that produce complex goods or services.

The original kanban boards were physical boards attached to factory or office walls. While many people still use physical kanban boards (even if it's just on paper), a variety of kanban board software tools exist (see also the "Scrum vs. Kanban" box). Before using any type of kanban system, I recommend reading why some people still choose physical kanban boards [3].

In this tutorial, I take a look at Wekan [4], an open source, MIT-licensed, web-based kanban system. Written with the Meteor Javascript framework [5] and using a MongoDB database, Wekan runs on any web browser. I'll show you how to install and use Wekan using general kanban principles.

Installation

You can download the Wekan source code, as well as Snap packages for several Linux distributions, from the Wekan website [4]. Alternatively, you could use Wekan as an application inside the open source Sandstorm platform for self-hosting web apps [6].

Although the process is not complicated, installing Wekan and all its dependencies from scratch on a dedicated server can be a lengthy process with a lot of details. I don't have the space to cover installing Wekan from source here, but an online tutorial written for CentOS 7 can point you in the right direction [7]. Though not completely up to date, the CentOS tutorial is very detailed and an excellent addition to the official Wekan documentation, regardless of your distribution.

If you don't need to install from source code, the Snap packages are much easier to use. On Ubuntu, you can run

sudo snap install wekan
sudo snap set wekan port="3500"
sudo snap enable wekan

at the prompt to install Wekan v5.37.0 and tell Wekan to answer connection requests on IP port number 3500. After installation, if you want to connect to Wekan from the same host, you must point your browser to the location http://localhost:$IP_PORT, where $IP_PORT is the parameter value you set in the second command above. I chose port 3500, but any port will do as long as it is not already used by another service on the same host. The final command above tells Linux to start Wekan automatically at bootup.

For this tutorial, I ran Wekan on my main Linux computer. If you need your installation to be accessible from the Internet, Wekan will also need to know the URL it should answer to, and you will have to open the corresponding IP port in the server firewall (please consult your firewall's documentation for instructions). The URL can be set with just one more snap command:

sudo snap set wekan root-url="https://wekan.example.com"

Initial Configuration

When you first connect to your Wekan installation, you must create at least one user account. Next, you need to configure several system-wide features, including email configuration, which allows Wekan to notify users whenever something happens associated with their accounts (see the Wekan wiki [8] for instructions).

After configuring email, you may want to customize parameters found in the Admin Panel's Registration, Accounts, and Layout tabs (Figure 1). You can allow (or forbid) self-registration. Existing users can also be given permission to change their personal Wekan account's primary data (i.e, username and email). In the Layout tab, you can define a clickable logo with a custom URL, as well as a few other cosmetic details.

Figure 1: The Wekan Admin Panel settings are simple but functional.

Potentially very interesting, Global Webhooks lets you define site-wide hooks that automatically notify external applications of something that happened inside Wekan or load data from external applications. You can also define board-specific webhooks. Unfortunately, at the time of writing, this feature is not adequately documented to be easily usable without spending significant time studying the code or hunting for answers in the Wekan support forum. However, webhooks may not be needed at all by the majority of projects that use Wekan.

A single Wekan installation supports multiple users who can be grouped into separate organizations, each composed of different teams (Figure 2). Figure 3 shows configuration options for an organization, and Figure 4 shows the team options.

Figure 2: One kanban to rule them all: Wekan supports independent organizations consisting of teams and individual users.

Figure 3: The New Organization dialog.

Figure 4: The New Team dialog.

Columns, Cards, and WIPs

Regardless of the type of project, all kanban boards should support, at a minimum, three types of components: columns, cards, and Work In Progress (WIP) limits.

A column, or a list, in Wekan lingo, defines a specific activity or phase of the entire workflow. For instance, a restaurant may have columns that indicate each client's current status: a list for clients waiting for their orders and another list for clients being actively served. The simplest possible workflow in most cases probably contains only three lists: To-Do, In Progress, and Finished. However, every project can create as many lists as needed and name them in whatever way makes their function clear to the whole team.

A card contains a single task managed on a kanban board. Each card moves through the columns in the workflow as a given tasks progresses toward completion. In most kanban systems, including Wekan, you can share the workload by explicitly assigning team members to specific cards. To make things even clearer, Wekan lets you attach colored labels to cards, allowing you to group or sort and filter the cards by title, creation date, or due date.

The WIP limit defines the maximum number of cards that can be in one column at any given time, in other words, the maximum number of tasks that the team allows itself to have in that particular state at any given moment. When the number of cards in a column exceeds the WIP limit, anyone responsible for any of the cards must focus to complete those tasks and move them to the next column before other cards begin to pile up in that column. In my opinion, the WIP limit is the kanban method's core strength. Make the WIP limit an adequate value for your team and project, which of course only you can estimate, and life will be good as long as everyone respects the limit. If the WIP limit is ignored, problems could arise. A WIP limit set too low results in unrealistic expectations and unnecessary stress. In contrast, a value set too high, even in just one column, can slow down the entire workflow represented on the board.

In Wekan, you can create and use several boards simultaneously (each containing a separate project) and set each of them as public or private (Figure 5). Once you have created a board, click on the plus sign at the bottom to add as many lists (columns) as you want to the board. After attaching a list to the board, you can (and should) assign a separate color to the list, but most importantly, you should define a list's WIP limit. Each list can have a different WIP value, set as either a hard or soft limit. A soft limit means the limit can be exceeded, but a warning will be given. After you have created all your lists, you can rearrange them by dragging and dropping them inside the board. You can also rename a list by selecting it and then clicking again on its name.

Figure 5: Wekan supports both public and private kanban boards.

View Modes

Each Wekan board has three View Modes: Lists, Calendar View, and Swimlanes. The default mode, Lists (shown in Figure 6), shows all the lists side by side, each with its own cards. Calendar View, which I'll cover later, shows the start and due dates for all active cards.

Figure 6: The default Lists view in Wekan: Each project phase has its own list (column) with individual tasks (cards), along with a WIP limit displayed below the list name.

The Swimlanes view may be unnecessary for single individuals or simple projects, but this view is essential in almost all other cases. Kanbanize.com defines swimlanes as "horizontal lines that split a kanban board into sections, [in order to] visually separate different work types on the same board and organize homogenous tasks together" [9]. In other words, if your organization has different teams that work mostly autonomously, with the same workflow but without continuous direct interactions, you can still place them on the same board by putting each team in a separate swimlane. In that way, their activities (i.e., the workload and responsibilities for each member of each team) remain as visually separated as possible. Figure 7 shows how this looks in practice inside Wekan, with swimlanes for communication and development activities.

Figure 7: Wekan swimlanes (in this example, Communication and Development) keep the work of independent teams separate but still visible at a glance.

Cards, at Last!

Wekan offers so many configuration options for cards, that at first glance the options may seem overwhelming or unnecessary (Figure 8). The Labels option lets users group and filter cards. The Received option lets you assign a start, due, and end date for each card, which you can see in the Calendar View mentioned earlier (Figure 9). You can also add comments to each card at the bottom.

Figure 8: Wekan cards have enough configuration options to make the most demanding project managers happy.

Figure 9: While Calendar View may be the least used view mode in Wekan, it will show you the start, end, and due dates for all active tasks.

Most crucial, the Description option lets you specify without ambiguities the nature of the task and when it can be considered finished. Both Checklists, which lets you attach one or more checklists to each card, and Activity, which lets you measure how much time is spent on each task, are useful but probably not essential.

A couple of options should be used with caution. The Subtasks option, which lets you assign subtasks to a task, should be monitored closely for one simple reason: If a team finds itself relying too much on subtasks, always attaching several to each card, it may be a strong sign that the overall workflow (the number of lists and swimlanes on the kanban board) needs a serious redesign. In addition, the Attachments option, which lets you attach any type of file to a card, can lead to confusion if an important document is only attached to one Wekan card and then forgotten. You can also run into problems if attachments are duplicated in a document management system, such as the SeedDMS [10].

In the card's titlebar, you'll find a link icon and a hamburger menu. The link icon lets you link a card to other cards (similar features are available to link boards or lists) to highlight the dependencies across different operations and teams. If you click on the hamburger menu in the card's titlebar, the Card Actions dialog opens (shown in Figure 10). Here you can, among other things, edit custom fields, set color, move a card around the board, use a card as a template, and eventually archive the cards.

Figure 10: The Wekan Card Actions menu allows you to further customize your project tasks.

Other Useful Features

Wekan can also generate usage reports. The most important reports are the ones that show broken (unlinked or inconsistent) cards and "orphaned" files (uploaded files that are no longer attached to existing cards) on a given board.

If you have boards from other kanban software or in plain text CSV format, you can import these boards into Wekan. To do so, click on the plus sign in the top menubar, and then click Import and follow the on-screen instructions.

Conclusions

Kanban boards have been around for decades without substantial changes to their original form. While they may not be the best tool for every team or project, kanban boards deliver what they promise: immediate visibility of a project's process, the responsibilities for each task, and any bottlenecks in the workflow. Kanban boards present this information in a way that is particularly well suited to self-organized teams without a boss directing tasks.

Wekan effectively implements kanban principles for workflow management. However, Wekan's effectiveness relies on all users following the rules. If all team members reliably enter all tasks, update the task statuses, and so on, Wekan will be helpful. Otherwise, it may create (or hide until it's too late) problems and frustration. If you and your team decide to use Wekan as your assistant, you must really be faithful to Wekan's kanban principles.

To find out how Wekan (and kanban principles in general) can benefit your team, give Wekan a try for a week or two on a test project. Wekan is a cool tool, as long as you use it appropriately.

The Author

Marco Fioretti (http://mfioretti.com) is a freelance author, trainer, and researcher based in Rome, Italy. He has been working with free/open source software since 1995 and on open digital standards since 2005. Marco also is a Board Member of the Free Knowledge Institute (http://freeknowledge.eu) and blogs about digital rights at https://stop.zona-m.net.