jjsm01/kimai2
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

release 0.8 (#567)

Browse Source
This commit is contained in:
Kevin Papst
2019-02-19 11:03:11 +01:00
committed by GitHub
parent b4f1cae323
commit 47b7046743
40 changed files with 446 additions and 341 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
var/docs/configurations.md
View File

@@ -1,5 +1,18 @@
# Configurations
This is an introduction into the configuration options and files, which are used by Kimai and an explanantion on how to change them.
Specific configurations are explained in the detailed feature docs:
- [Timesheet](timesheet.md)
- [Permissions](permissions.md)
- [Invoice](invoices.md)
- [Calendar](calendar.md)
- [Customer](customer.md)
- [Emails](emails.md)
- [Dashboard widgets](dashboard.md)
- [Theme](theme.md)
## Environment specific settings (.env)
The most basic settings, which need always be adjusted are stored in the `.env` file:
@@ -19,20 +32,12 @@ Configuration of Kimai is spread in all files in the `config/`directory but main
- `config/packages/kimai.yaml` - Kimai specific settings
- `config/packages/admin_lte.yaml` - Kimai base theme
- `config/packages/fos_user.yaml` - user management and email settings
- `config/packages/local.yaml` - your local configuration settings
- `config/packages/local.yaml` - your configuration settings (file needs to be created by yourself)
There are several other configurations that could potentially be interesting for you in [config/packages/*.yaml](../../config/packages/).
If you want to adjust a setting from any of these files, use `local.yaml` (see below).
#### Other topics
- [Theme settings](theme.md) - in `kimai.yaml` and `admin_lte.yaml`
- [Email configuration](emails.md) - in `swiftmailer.yaml`
- [Dashboard widgets](dashboard.md) - in `kimai.yaml`
- [Calendar](calendar.md) - in `kimai.yaml`
- [Invoices](invoices.md) - in `kimai.yaml`
## Overwriting local configs (local.yaml)
You should NOT edit the file `config/packages/kimai.yaml` directly, as it contains default settings and will be overwritten during an update.
@@ -71,202 +76,3 @@ bin/console cache:warmup --env=prod
Depending on your setup it might be necessary to execute these commands as webserver user,
please read the [UPGRADING guide](../../UPGRADING.md) for more details.
## Security
Kimai uses the FOSUserBundle for security related tasks like user management. Its configuration can be found in [fos_user.yaml](../../config/packages/fos_user.yaml).
### User management emails (fos_user.yaml)
Read more about [email configuration](emails.md).
### Remember me login (security.yaml)
The default period for the `Remember me` option can be changed in the config file [security.yaml](../../config/packages/security.yaml).
### User registration
If you want your new users to use [email](emails.md) based activation add this to your `local.yaml`:
```yaml
fos_user:
registration:
confirmation:
enabled: true
```
#### Disable user registration
If you want to disable the user registration, add this your `local.yaml`:
```yaml
kimai:
user:
registration: false
```
If you only want to hide the link from the login form but keep the functionality, add this your `local.yaml`:
```yaml
admin_lte:
routes:
adminlte_registration: ~
```
### Password reset
If you want to configure the behaviour (like the allowed time between multiple retries) then configure the settings:
- in `config/packages/fos_user.yaml` the key below `fos_user.registration.resetting` (see [documentation](https://symfony.com/doc/current/bundles/FOSUserBundle/configuration_reference.html))
- the values `retry_ttl` and `token_ttl` are configured in seconds (7220 = 2 hours)
#### Disable password reset
If you want to disable the password reset, add this your `local.yaml`:
```yaml
kimai:
user:
password_reset: false
```
If you only want to hide the link from the login form but keep the functionality, add this your `local.yaml`:
```yaml
admin_lte:
routes:
adminlte_password_reset: ~
```
## Timesheets (kimai.yaml)
### 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.
### Duration only
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 the file [kimai.yaml](../../config/packages/kimai.yaml).
For supported formats while entering the `duration` please see the [timesheet chapter](timesheet.md)
### 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
```
### Hourly rates for timesheet records
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
```
## Forms (kimai.yaml)
You can set some defaults for various forms within Kimai, to easify the creation process.
### Customer creation
Define the default values for a customer like this:
```yaml
kimai:
defaults:
customer:
timezone: Europe/London
country: GB
currency: GBP
```