185 lines
8.0 KiB
Markdown
185 lines
8.0 KiB
Markdown
# Timesheet
|
|
|
|
User manual on the timesheet tables and actions.
|
|
|
|
Kimai 2 provides also a [calendar view](calendar.md), which displays your timesheet entries in an easy readable format.
|
|
|
|
## Starting records
|
|
|
|
You can start new timesheet records like so:
|
|
- Click the **redo** button in the "last activities" dropdown in the upper toolbar
|
|
- Click the **redo** button from one of the activities in your timesheet
|
|
- Start a completely new activity, by clicking the big **play** button in the toolbar
|
|
|
|
## Stopping records
|
|
|
|
You can stop timesheet records like so:
|
|
- Click the **stop** button in the "active records" dropdown in the upper toolbar
|
|
- Click the **stop** button from one of the running activities in your timesheet
|
|
- Edit a running activity, add an end date and save
|
|
|
|
## Duration only mode
|
|
|
|
Kimai supports two modes for displaying and recording timesheet entries:
|
|
|
|
- `begin` and `end` time (default)
|
|
- `date` and `duration` (the so called `duration_only` mode)
|
|
|
|
When activating the `duration_only` mode all timesheet tables will only display the `date` and `duration` of all records.
|
|
In addition, the "edit timesheet" forms will be changed and instead of displaying the `end` date you will see a field for `duration`.
|
|
The `start` date is only visible in these forms when editing an active or starting a new record.
|
|
|
|
You can activate the `duration_only` mode by switching the configuration key `kimai.timesheet.duration_only` to `true` in your `local.yaml`:
|
|
|
|
```yaml
|
|
kimai:
|
|
timesheet:
|
|
duration_only: true
|
|
```
|
|
|
|
### Duration format
|
|
|
|
The `duration` field supports entering data in the following formats:
|
|
|
|
| Name | Format | Description | Examples |
|
|
|---|---|---|---|
|
|
| Colons | {hours}:{minutes}[:{seconds}] | Seconds are optional, overflow is supported for every field | `2:27` = 2 Hours, 27 Minutes / `3:143:13` = 5 Hours, 23 Minutes, 13 Seconds|
|
|
| Natural | {hours}h{minutes}m[{seconds}s] | Seconds are optional, overflow is supported for every field | `2h27m` = 2 Hours, 27 Minutes / `3h143m13s` = 5 Hours, 23 Minutes, 13 Seconds |
|
|
| Seconds | {seconds} | | `3600` = 1 Hour / `8820` = 2 Hours, 27 Minutes |
|
|
|
|
Please note: if time rounding is activated (which is the default behaviour), then your entered seconds might be removed after submitting the form.
|
|
|
|
## Limit active entries
|
|
|
|
To limit the amount of active entries each user can have, the configuration `active_entries` can be changed:
|
|
|
|
```yaml
|
|
kimai:
|
|
timesheet:
|
|
active_entries:
|
|
soft_limit: 1
|
|
hard_limit: 3
|
|
```
|
|
|
|
The `soft_limit` is used as theme setting (formerly "kimai.theme.active_warning") to display a warning if the user has at least X active recordings.
|
|
|
|
The `hard_limit` is used to detect how many active records are allowed per user (by default 3 active time-records are allowed).
|
|
If `hard_limit` is 1, the active record is automatically stopped when a new one is started.
|
|
When `hard_limit` is greater than 1 and as soon as the limit is reached, the user has to manually stop at least one active
|
|
entry (an error message is shown, indicating why it is not possible to start another one).
|
|
|
|
## Descriptions with Markdown
|
|
|
|
The description for every timesheet entry can be formatted in two different ways, configured with the `markdown_content` setting.
|
|
|
|
- `false` - simple newlines in the description box will be displayed in the frontend as well (default)
|
|
- `true` - description will be rendered with a markdown engine, supporting simple lists and other HTML content
|
|
|
|
Allowing Markdown in timesheet descriptions is beautiful, but also could be a [security risk](https://github.com/erusev/parsedown/blob/master/README.md#security).
|
|
Kimai will only apply the markdown in the user timesheet and not in the admin section as additional security measure.
|
|
|
|
## Rounding of begin, end and duration for timesheet records
|
|
|
|
Rounding rules are used to round the begin & end dates and the duration for timesheet records.
|
|
|
|
1. You can define as many rules as you want ("default" is only an example)
|
|
2. Every matching rule will be applied, so be careful with overlapping rules
|
|
3. The end_date of timesheet records will be used to match the day (think about entries which are recorded overnight)
|
|
4. If you set one of "begin", "end", "duration" to 0 no rounding will be applied for that field and the exact time (including seconds) is used for calculation
|
|
5. The values of the rules are minutes (not the minute of an hour), so 5 for "begin" means we round down to the previous multiple of five
|
|
6. You can define different rules for different days of the week
|
|
7. "begin" will always be rounded to the floor (down) and "end" & "duration" to the ceiling (up)
|
|
8. Rounding rules will be applied on stopped timesheet records only, so you might see an un-rounded value for the start time and duration until you stop the record
|
|
|
|
You can configure your `rounding` rules by changing the configuration file [kimai.yaml](../../config/packages/kimai.yaml).
|
|
|
|
### Examples
|
|
|
|
A simple example to always charge at least 1 hour for weekend work (even if you only worked for 5 minutes) could look like this:
|
|
|
|
```yaml
|
|
kimai:
|
|
timesheet:
|
|
rounding:
|
|
weekend:
|
|
days: ['saturday','sunday']
|
|
begin: 1
|
|
end: 1
|
|
duration: 60
|
|
```
|
|
|
|
A rule which is often used is to round up to a mulitple of 10:
|
|
|
|
```yaml
|
|
kimai:
|
|
timesheet:
|
|
rounding:
|
|
workdays:
|
|
days: ['monday','tuesday','wednesday','thursday','friday','saturday','sunday']
|
|
begin: 10
|
|
end: 10
|
|
duration: 0
|
|
```
|
|
|
|
## Rate calculation
|
|
|
|
There are two rate types:
|
|
|
|
- __Fixed rate__: the value will be used to set the records rate, no matter how long the duration is
|
|
- __Hourly rate__: will be used to calculate the records rate by multiplying it with the duration (see below)
|
|
|
|
If any of the above is set to 0, the records rate will be set to 0.
|
|
|
|
While calculating the rate of a timesheet entry, the first setting that is found will be used (in order of appearance):
|
|
|
|
- Timesheet fixed rate
|
|
- Activity fixed rate
|
|
- Project fixed rate
|
|
- Customer fixed rate
|
|
- Timesheet hourly rate
|
|
- Activity hourly rate
|
|
- Project hourly rate
|
|
- Customer hourly rate
|
|
- Users hourly rate
|
|
|
|
If neither a fixed nor a hourly rate can be found, the users rate will be used to calculate the records rate.
|
|
If that is the case and if the users rate is not set or equals 0, the records rate will be set to 0.
|
|
|
|
The calculation is based on the following formula:
|
|
|
|
- __Fixed rate__: `$fixedRate`
|
|
- __Hourly rate__: `$hourlyRate * ($durationInSeconds / 3600) * $factor`
|
|
|
|
Please see below to see how you can apply configurable multiplying factors based on day and time.
|
|
|
|
### Rate multiplier for specific weekdays
|
|
|
|
If you want to apply different hourly rates multiplication `factor` for specific weekdays, you can use this `rates` configuration.
|
|
|
|
1. You can define as many rules as you want ("workdays" and "weekend" are only examples)
|
|
2. Every matching rule will be applied, so be careful with overlapping rules
|
|
3. The end_date of timesheet records will be used to match the day (think about entries which are recorded overnight)
|
|
4. "days" is an array of weekdays, where the days need to be written in english and in lowercase
|
|
5. "factor" will be used as multiplier for the applied hourly rate
|
|
6. Rate rules will be applied on stopped timesheet records only, as it can't be calculated before
|
|
7. There is no default rule active, by default the users hourly-rate is used for calculation
|
|
|
|
You can configure the `hourly_rate` rules by changing the configuration file [kimai.yaml](../../config/packages/kimai.yaml).
|
|
|
|
#### Examples
|
|
|
|
1. The "workdays" rule will use the default "hourly rate" for each timesheet entry recorded between "monday" to "friday" as a multiplication with 1 will not change the result
|
|
2. The "weekend" rule will add 50% to each timesheet entry that will be recorded on "saturdays" or "sundays"
|
|
|
|
```yaml
|
|
kimai:
|
|
timesheet:
|
|
rates:
|
|
workdays:
|
|
days: ['monday','tuesday','wednesday','thursday','friday']
|
|
factor: 1
|
|
weekend:
|
|
days: ['saturday','sunday']
|
|
factor: 1.5
|
|
```
|