# Task and todo-list management plugin for Kimai 2

A Kimai plugin, which allows you to plan your work and distribute tasks among your users and teams.
It features two new dashboard widgets and a new "Task management" administration view.

Translated to: English, German, Finnish.

You can test it in the ["Plugins" demo](https://www.kimai.org/demo/).

## Features

Adds "task management" to manage your work and for starting/grouping of timesheet records.

Each task has the following fields:
  - Title
  - Work description
  - End date (optional)
  - Time estimation (optional: if given, a progressbar for duration vs estimation will be shown in the listing page)
  - User (optional: if left empty, the task can be self-assigned from the "pending tasks" widget)
  - Team (optional: if given, only users from this team see this task and can assign it)
  - Customer (will be copied to the started timesheet)
  - Project (will be copied to the started timesheet)
  - Activity (will be copied to the started timesheet)
  - Description (will be copied to the started timesheet)
  - Tags (will be copied to the started timesheet)
  - List of comments (to share updates with others)

Ships new reports:
  - List all users with the number of assigned tasks and progress (via estimation / logged duration)
  - List all teams with the number of assigned tasks and progress (via estimation / logged duration)

Users can log work time for tasks with drag & drop support in the calendar view. 

Ships two new dashboard widgets (see screenshots):
  - The amount of rows in the dashboard widgets can be configured in the user-preferences
  - With the help of the dashboard widgets every user can manage their work 

You can configure the permissions in multiple ways:
  - First version: allows self-management by the user via the dashboard widgets, by assigning to pending tasks
  - Second version: only the "My tasks" widget will be shown, listing page is hidden from "normal users" and teamleads will 
  plan the work schedule (a list of tasks) for the users, who then use the widget to start/pause/stop their assigned tasks
  - Third version: Tasks are shared, pending tasks can be started and stopped by everyone/team members 

A task can reach the `overdue` status, which means:
  - the task reached its end date without being finished
  - or the duration of all logged entries is higher than the estimation of the task  

Tasks which are `overdue` will be highlighted by a warning color.

A task can be created from an Activity, pre-setting all possible values from the project and activity.  

## Dashboard widgets

This bundle ships two new dashboard widgets (see [screenshots](https://www.kimai.org/store/task-management-bundle.html)).

### My tasks widget

Displays all tasks which:
  - are not "closed"
  - are assigned to you

This widget has the following UI elements:
  - a checkbox to close the task (moving to status done will stop all related timesheet entries)
  - a title 
  - a status indicator (colored "red" if the task is `overdue`, otherwise green) 
  - a "Play" or "Pause" button (pause means that you already recorded times for the task) 
  - an "Edit" button to change the task fields
  - an "Unassign" button (will stop all related timesheet entries and move the task to the "Pending tasks widget")
  - a "Delete" button (will remove the task entirely, but keep the related timesheet entries)
  - a "Create" button (create a new task for the currently logged-in user)      

Visible for all user with `task_start` permission.

### Pending tasks widget

Displays all tasks which:
  - have the "pending" or "running" status
  - and are not assigned to a user
  - and are either 
    - not assigned to a team
    - or are assigned to the users team
    - or the current user owns the `view_all_data` permission (like admins)

This widget has the following UI elements (if permissions are set for the user):
  - a title 
  - a status indicator (colored "red" if the task is `overdue`, otherwise green) 
  - a "Play" or "Pause" button (needs special permission) 
  - an "Edit" button
  - an "Assign" button (move the task back to the "My tasks widget")
  - a "Delete" button (will remove the task entirely, but keep the related timesheet entries)
  - a "Create" button (create a new pending task)   

Visible for all user with `task_start` and either one of `task_assign` or `task_team_view` permission.

## Installation

### Compatibility

The plugin is compatible with the following Kimai releases:

| Bundle version    | Minimum Kimai 2 version  |
| ---               |---                       |
| 1.10 - 1.11       | 1.15                     |
| 1.9               | 1.14                     |
| 1.7 - 1.8         | 1.11                     |
| 1.4 - 1.6         | 1.10                     |
| 1.3               | 1.9                      |
| 1.0 - 1.2         | 1.7                      |

### Copy the files 

Extract the ZIP file and upload the included directory and all files to your Kimai installation to the new directory:  
`var/plugins/TaskManagementBundle/`

The file structure needs to look like this afterwards:

```
var/plugins/
├── TaskManagementBundle
│   ├── TaskManagementBundle.php
|   └ ... more files and directories follow here ... 
```
### Rebuild the cache

After uploading the files, Kimai needs to know about the new plugin. It will be found, once the cache was re-built:

```
cd kimai2/
bin/console kimai:reload --env=prod
```

### Install the bundle database

Run the following command:

```bash
bin/console kimai:bundle:tasks:install
```

This will install all required databases.

## Permissions

This bundle introduces new permissions, which limit access to certain functions:

| Permission         | Description |
|---                 |--- |
| `task_edit_own`    | Create and edit tasks that are assigned to the currently logged-in user. |
| `task_edit_other`  | Allows to edit all tasks that are visible to the user. Create new unassigned tasks, assign team and user. Remove assignment and close tasks which are assigned to another user (stops running records). |
| `task_assign`      | Self-assign a pending task by the currently logged-in user. |
| `task_start`       | Start a task. Only possible if task is assigned to the current user. Required to see the "My tasks" widget on the dashboard. |
| `task_start_all`   | Start a pending task. Only possible if the task is not assigned to the current user. |
| `task_close`       | Close a task. Possible if task is assigned to the current user or the user owns the `task_edit_other` permission. The task will be removed from the "My tasks" widget. |
| `task_delete`      | Delete any existing task. |
| `task_view`        | Gives access to the task listing page and task reports. |
| `task_team_view`   | Display tasks in listing page, which are assigned to team members. |
| `task_details`     | Gives access to the detail view of a single task. |

A pre-configured permission set for all default user roles is applied by the plugin. 
Please adjust them to your needs in "System > Roles" administration. 

## Updating the plugin

Updating the bundle works the same way as the installation does. 

- Delete the directory `var/plugins/TaskManagementBundle/`
- Execute all installation steps again:
  - Copy files
  - Clear cache
  - Update database with `bin/console kimai:bundle:tasks:install` 

## Screenshots

Screenshots are available [in the store page](https://www.kimai.org/store/task-management-bundle.html).

## Uninstall

- Delete the extension directory `var/plugins/TaskManagementBundle/`
- Remove the database tables ONLY if you don't want to keep the data (create a backup first!):
```sql
DROP TABLE kimai2_tasks;
DROP TABLE bundle_migration_tasks;
```
- Reload your cache with `bin/console kimai:reload --env=prod`