added time budget docs (#28)

_data/menu-documentation.yml

@@ -1,7 +1,7 @@
 - title: Administration
   pages: [installation, updates, docker, backups]
 - title: User manual
-  pages: [timesheet, invoices, export, users, customer, project, tags]
+  pages: [timesheet, invoices, export, users, customer, project, activity, tags]
 - title: Configuration
   pages: [configurations, user-preferences, calendar, dashboard, emails, permissions, ldap]
 - title: Developer

_documentation/activity.md

@@ -0,0 +1,31 @@
+---
+title: Activities
+description: Activities in Kimai 2
+---
+
+Activities in Kimai are defining the current task you are working on.
+
+## Global activities vs project activities
+
+Activities can be assigned to a project, which means you can only choose them if the linked project was chosen before.
+But activities can also be global, meaning they are not linked to a project and can be re-used with EVERY project and customer.
+
+Examples for global activities are things like:
+- meetings
+- phone calls
+- administrative tasks
+
+So tasks which repeat in each of your projects.
+
+## Activity colors
+
+Each activity can be assigned its own color, for easier identification in the timesheets.
+
+If no color is applied, the project color will be used.
+
+See [customer documentation]({% link _documentation/customer.md %}) for the default color.
+
+## Time budget
+{% include new_since.html version="1.0" %}
+
+{% include time_budget.md %}

_documentation/customer.md

@@ -34,3 +34,8 @@ The customers currency is used when displaying the recorded entries in the times
 
 It is also used for printing invoices, which is the reason while the invoice screen needs one applied customer filter 
 before any data will be shown. 
+
+## Time budget
+{% include new_since.html version="1.0" %}
+
+{% include time_budget.md %}

_documentation/ldap.md

@@ -16,20 +16,20 @@ This is the full available configuration, with some examples and all optional se
 ```yaml
 kimai:
     ldap:
-        active: true  # default: false
+        # whether LDAP authentication should be used
+        active: true                            # default: false
 
         # more infos about the connection params can be found at:
         # https://docs.zendframework.com/zend-ldap/api/
+
         connection:
             host: 127.0.0.1
-            #port: 389
+            #port: 389                          # LDAP port, default is 389
             #useSsl: false                      # Enable SSL negotiation
             #useStartTls: false                 # Enable TLS negotiation
             #username: foo
             #password: bar
             #bindRequiresDn: false
-            #baseDn: ou=users, dc=kimai, dc=org # will use "user.baseDn" if not given
-            #accountFilterFormat: (&(uid=%s))   # %s will be replaced with the username
             #allowEmptyPassword: false
             #optReferrals: false
             #tryUsernameSplit: 
@@ -39,21 +39,35 @@ kimai:
             #accountDomainNameShort: HOST
 
         user:
-            baseDn: ou=users, dc=kimai, dc=org    # baseDn to query for users
-            #filter: (&(ObjectClass=Person))      # extended search filter for users
-            #usernameAttribute: uid               # field used in the LDAP bind for the given "login username" 
+            baseDn: ou=users, dc=kimai, dc=org  # baseDn to query for users
+            #filter: (&(uid=%s))                # search filter for users
+                                                # defaults to (&(usernameAttribute=%s)) 
+                                                # this search filter must return 1 result only 
+                                                # %s will be replaced with the username
+
+            #usernameAttribute: uid             # field used in bind for the "login username"
+                                                # defaults to "uid" 
 
             # Mapping LDAP attributes to user entity
-            attributes:
-                - { ldap_attr: uid, user_method: setUsername }
+            # defaults to:
+            # - { ldap_attr: "usernameAttribute", user_method: setUsername }
+            # - { ldap_attr: "usernameAttribute", user_method: setEmail }
+
+            #attributes:
             #    - { ldap_attr: mail, user_method: setEmail }
             #    - { ldap_attr: cn, user_method: setAlias }
 
+        # If you want to use the LDAP groups to Kimai role import, you have to
+        # uncomment at least "role" and "role.baseDn"
+
         #role:
-            #baseDn: ou=groups, dc=kimai, dc=org    # baseDn to query for groups - MUST be set, if "role" is uncommented
-            #filter: (&(objectClass=groupOfNames))  # additional filter to query the groups
-            #nameAttribute: cn                      # the group name
-            #userDnAttribute: member                # field to look in for the users dn 
+            #baseDn: ou=groups, dc=kimai, dc=org    # baseDn to query for groups
+                                                    # MUST be set to activate "group import"
+
+            #filter: (&(objectClass=groupOfNames))  # additional filter to query user groups
+                                                    # defaults to userDnAttribute=usersDn
+            #nameAttribute: cn                      # field that holds the group name
+            #userDnAttribute: member                # field that holds the users dn 
 
             # Convert LDAP group name (nameAttribute) to Kimai role
             #groups:
@@ -70,34 +84,42 @@ User data is synchronized on each login, fetching the latest data from your LDAP
 
 **How it works**
 
-There are 2-3 steps involved:
-- the login is performed by a `bind`
+- if `bindRequiredDn` is active, a `search` is executed to find the users DN by the given username
+- the authentication is checked with a `bind`
 - if the `bind` was successful:
-  - a `search` is executed to find and map LDAP attributes to the Kimai profile
-  - if configured, another `search` is executed to sync the user groups
+    - another `bind` using the service account (connection.username/connection.password) is executed and under that scope:
+      - a `search` is executed to find and map LDAP attributes to the Kimai profile
+      - if configured, another `search` is executed to sync and map the users LDAP groups to Kimai roles 
 
 **Password handling**
 
-Obviously Kimai does not store the users password when logged-in via LDAP.
-There is no fallback mechanism, if your LDAP is not available, the user will not be able to login.
+Obviously Kimai does not store the users password when logged-in via LDAP and there is 
+no fallback mechanism implemented, if your LDAP is not available (currently only ONE server can be configured).
 
 {% include alert.html type="danger" alert="The default configuration allows a user to change the internal password. This manually chosen password is not overwritten by the LDAP plugin and would allow a user to login, if if you removed him from LDAP." %} 
 
 To prevent that problem:
 - disable the "[Password reset]({% link _documentation/users.md %})" function
-- disable the "change my own password" permission for each role:
-
 ```yaml
 kimai:
+    user:
+        registration: false
+        password_reset: false
+```
+- disable the "change my own password" permission for each role:
+```yaml
     permissions:
         roles:
             ROLE_USER: ['!password_own_profile']
             ROLE_TEAMLEAD: ['!password_own_profile']
             ROLE_ADMIN: ['!password_own_profile']
 ```
+
 Read more about `password_own_profile` and `password_other_profile` [permissions]({% link _documentation/permissions.md %}).
 
-If you don't adjust your configuration, you have to deactivate users manually in Kimai.
+If you don't adjust your configuration, you have to:
+- either deactivate users manually in Kimai after deleting their LDAP account
+- or use a attribute mapping to set the user deactivated flag via `setEnabled()`
 
 ### User attributes
 
@@ -116,7 +138,7 @@ kimai:
 ```
 {% include alert.html type="warning" alert="You need to configure the attributes in lower-case, otherwise they won't be processed." %}
 
-This will tell Kimai to sync the following fields:
+In this example we tell Kimai to sync the following fields:
 - `uid` will be the username in Kimai (will fail with a 500 if not unique)
 - `mail` will be the account email address (read "known limitations" below)
 - `cn` will be used for the display name in Kimai
@@ -180,8 +202,8 @@ But: fields which are not synced, won't be changed during the user login.
 
 If you configured the group sync, the assigned user roles in Kimai will be overwritten on login.
 
-As the roles are resetted and replaced with the LDAP groups during authentication, 
-you cannot demote or promote a User permanently to another role in Kimai.
+Roles are not merged, but replaced during authentication, so you cannot  
+demote or promote a User permanently to another role in Kimai.
 
 The rule is: either manage all roles in Kimai or in LDAP, mixing is not possible.
 
@@ -194,13 +216,15 @@ The rule is: either manage all roles in Kimai or in LDAP, mixing is not possible
 A minimal setup with a local OpenLDAP without roles sync:
 
 ```yaml
+kimai:
     ldap:
         active: true
         connection:
             host: 127.0.0.1
             bindRequiresDn: true
         user:
             baseDn: ou=users, dc=kimai, dc=org
+            filter: (&(objectClass=inetOrgPerson))
             attributes:
                 - { ldap_attr: uid, user_method: setUsername }
                 - { ldap_attr: mail, user_method: setEmail }
@@ -213,6 +237,7 @@ Please start with a minimal setup. Only if that works: start extending your conf
 A secured local OpenLDAP on port 543 with roles sync for the objectClass `inetOrgPerson` users:
 
 ```yaml
+kimai:
     ldap:
         active: true
         connection:

_documentation/project.md

@@ -14,3 +14,8 @@ If no color is applied, the customers color will be used.
 If an activity linked to the project does not have its own color, the projects color will be used (and as fallback again the customers color).
 
 See [customer documentation]({% link _documentation/customer.md %}) for the default color.
+
+## Time budget
+{% include new_since.html version="1.0" %}
+
+{% include time_budget.md %}

_documentation/timesheet.md

@@ -72,13 +72,7 @@ that should limit access to this data, make sure to remove this permission for p
 
 #### Duration format
 
-The `duration` field in the "edit timesheet" form supports entering data in the following formats:
-
-| Format | Description | Examples |
-|---|---|---|
-| {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|
-| {hours}h{minutes}m{seconds}s | Each section is optional, overflow is supported for every field | `2h` = 2 Hours / `147m` = 2 Hours, 27 Minutes / `3h14m13s` = 3 Hours, 14 Minutes, 13 Seconds |
-| {seconds} | | `3600` = 1 Hour / `8820` = 2 Hours, 27 Minutes |
+{% include duration_format.md %}
 
 Please note: 
 - if time rounding is activated (which is the default behaviour), then your entered seconds might be removed after submitting the form.

_includes/duration_format.md

@@ -0,0 +1,9 @@
+{% assign fieldName = include.field_name|default: 'duration' %}
+
+The `{{ fieldName }}` field supports entering data in the following formats:
+
+| Format | Description | Examples |
+|---|---|---|
+| {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|
+| {hours}h{minutes}m{seconds}s | Each section is optional, overflow is supported for every field | `2h` = 2 Hours / `147m` = 2 Hours, 27 Minutes / `3h14m13s` = 3 Hours, 14 Minutes, 13 Seconds |
+| {seconds} | | `3600` = 1 Hour / `8820` = 2 Hours, 27 Minutes |

_includes/new_since.html

@@ -0,0 +1,4 @@
+<span class="tag" style="float: right">
+	Added with
+	<span class="tag-addon">v {{ include.version }}</span>
+</span>

_includes/time_budget.md

@@ -0,0 +1,3 @@
+{% include duration_format.md field_name="Time budget" %}
+
+Time budgets are not used for hard limitations, but rather for the base of reporting calculations.