[IMP] Time Off: updating requested carry over time info

closes odoo/documentation#10747

X-original-commit: 98f2adbd13
Signed-off-by: Lara Martini (larm) <larm@odoo.com>

content/applications/hr/time_off.rst

@@ -4,8 +4,8 @@
 Time Off
 ========
 
-Odoo's *Time Off* application serves as a centralized hub for all time-off-related information. This
+Odoo's **Time Off** application serves as a centralized hub for all time-off-related information.
-application manages requests, balances, allocations, approvals, and reports.
+This application manages requests, balances, allocations, approvals, and reports.
 
 Users can :doc:`request time off <../hr/time_off/request_time_off>`, and see an overview of their
 requests and time off balances. Managers can :doc:`allocate time off <time_off/allocations>` to
@@ -17,13 +17,12 @@ time off) are being used, :ref:`accrual plans <time_off/accrual-plans>` can be c
 :ref:`public holidays <time_off/public-holidays>` can be set.
 
 .. note::
-   Be advised, only users with specific access rights can see all aspects of the *Time Off*
+   Be advised, only users with specific access rights can see all aspects of the **Time Off** app.
-   application.
 
-   All users can access the :guilabel:`My Time Off` and :guilabel:`Overview` sections of the *Time
+   All users can access the *My Time Off* and *Overview* sections of the **Time Off** app. All other
-   Off* application. All other sections require specific access rights.
+   sections require specific access rights.
 
-   To better understand how access rights affect the *Time Off* application, refer to the
+   To better understand how access rights affect the **Time Off** app, refer to the
    :doc:`employees/new_employee` document, specifically the section about configuring the work
    information tab.
 
@@ -42,9 +41,9 @@ Time off types
 To view the currently configured time off types, navigate to :menuselection:`Time Off app -->
 Configuration --> Time Off Types`. The time off types are presented in a list view.
 
-The *Time Off* application comes with four pre-configured time off types: :guilabel:`Paid Time Off`,
+The **Time Off** app comes with four preconfigured time off types: :guilabel:`Paid Time Off`,
 :guilabel:`Sick Time Off`, :guilabel:`Unpaid`, and :guilabel:`Compensatory Days`. These can be
-modified to suit business needs or used as-is.
+modified to suit business needs, or used as-is.
 
 Create time off type
 ~~~~~~~~~~~~~~~~~~~~
@@ -67,26 +66,26 @@ Time Off Requests section
 - :guilabel:`Approval`: select what specific kind of approval is required for the time off type. The
   options are:
 
-  - :guilabel:`No Validation`: no approvals are required when requesting this type of time off. The
+  - :guilabel:`No Validation`: No approvals are required when requesting this type of time off. The
     time off request is automatically approved.
-  - :guilabel:`By Time Off Officer`: only the specified :ref:`Time Off Officer
+  - :guilabel:`By Time Off Officer`: Only the specified :ref:`Time Off Officer
     <time_off/time-off-officer>`, set on this form in the :guilabel:`Notified Time Off Officer`
-    field, is required to approve the time off request. This option is selected by default.
+    field, is required to approve the time off request. This option is selected, by default.
-  - :guilabel:`By Employee's Approver`: only the employee's specified approver for time off, which
+  - :guilabel:`By Employee's Approver`: Only the employee's specified approver for time off, which
     is set on the *Work Information* tab on the :ref:`employee's form <employees/work-info-tab>`, is
     required to approve the time off request.
-  - :guilabel:`By Employee's Approver and Time Off Officer`: both the employee's :ref:`specified
+  - :guilabel:`By Employee's Approver and Time Off Officer`: Both the employee's :ref:`specified
     time off approver<employees/work-info-tab>` and the :ref:`Time Off Officer
     <time_off/time-off-officer>` are required to approve the time off request.
 
 Allocation Requests section
 ***************************
 
-- :guilabel:`Requires allocation`: if the time off must be allocated to employees, select
+- :guilabel:`Requires allocation`: If the time off must be allocated to employees, select
   :guilabel:`Yes`. If the time off can be requested without time off being previously allocated,
   select :guilabel:`No Limit`. If :guilabel:`No Limit` is selected, the following options do not
   appear on the form.
-- :guilabel:`Employee Requests`: select :guilabel:`Extra Days Requests Allowed` if the employee is
+- :guilabel:`Employee Requests`: Select :guilabel:`Extra Days Requests Allowed` if the employee is
   able to request more time off than was allocated.
 
   If employees should **not** be able to make requests for more time off than what was allocated,
@@ -102,7 +101,7 @@ Allocation Requests section
      It is important to note that requesting additional time off does **not** guarantee that time
      off is granted.
 
-- :guilabel:`Approval`: select the type of approvals required for the allocation of this particular
+- :guilabel:`Approval`: Select the type of approvals required for the allocation of this particular
   time off type.
 
   - :guilabel:`Approved by Time Off Officer` indicates the :ref:`Time Off Officer
@@ -114,9 +113,9 @@ Configuration section
 
   .. _`time_off/time-off-officer`:
 
-- :guilabel:`Notified Time Off Officer`: select the person who is notified and responsible for
+- :guilabel:`Notified Time Off Officer`: Select the person who is notified and responsible for
   approving requests and allocations for this specific type of time off.
-- :guilabel:`Take Time Off in`: select the format the time off is requested in from the drop-down
+- :guilabel:`Take Time Off in`: Select the format the time off is requested in from the drop-down
   menu.
 
   The options are:
@@ -127,22 +126,22 @@ Configuration section
 
   .. _`time_off/deduct-extra-hours`:
 
-- :guilabel:`Deduct Extra Hours`: enable this option if the time off request should factor in any
+- :guilabel:`Deduct Extra Hours`: Enable this option if the time off request should factor in any
-  extra time accrued by the employee
+  extra time accrued by the employee.
 
   .. example::
      If an employee works two extra hours for the week, and requests five hours of time off, the
      request would be for three hours, since the two extra worked hours are used first, and deducted
      from the request.
 
-- :guilabel:`Allow To Attach Supporting Document`: enable this option to allow the employee to
+- :guilabel:`Allow To Attach Supporting Document`: Enable this option to allow the employee to
   attach documents to the time off request. This is useful in situations where documentation is
   required, such as long-term medical leave.
-- :guilabel:`Kind of Time Off`: select from the drop-down menu the type of time off this is, either
+- :guilabel:`Kind of Time Off`: From the drop-down menu, select the type of time off, either
-  :guilabel:`Worked Time` or :guilabel:`Absence`. :guilabel:`Worked Time` indicates that the time
+  :guilabel:`Worked Time` or :guilabel:`Absence`. :guilabel:`Worked Time` indicates the time off
-  off taken counts toward worked time for any type of accrual the employee is working towards,
+  taken counts toward worked time for any type of accrual the employee is working towards, whereas
-  whereas :guilabel:`Absence` does not count toward any type of accrual.
+  :guilabel:`Absence` does not count toward any type of accrual.
-- :guilabel:`Company`: if multiple companies are created in the database, and this time off type
+- :guilabel:`Company`: If multiple companies are created in the database, and this time off type
   only applies to one company, select the company from the drop-down menu. If this field is left
   blank, the time off type applies to all companies in the database. This field **only** appears in
   a multi-company database.
@@ -172,8 +171,8 @@ field appears. In this field, enter the maximum amount of negative time allowed,
 Payroll section
 ***************
 
-If the time off type should create :doc:`../hr/payroll/work_entries` in the *Payroll* application,
+If the time off type should create :doc:`../hr/payroll/work_entries` in the **Payroll** app, select
-select the :guilabel:`Work Entry Type` from the drop-down list.
+the :guilabel:`Work Entry Type` from the drop-down list.
 
 Timesheets section
 ******************
@@ -183,17 +182,17 @@ Timesheets section
    :ref:`developer-mode` document for details on how to access the developer mode.
 
 When an employee takes time off, and is also using timesheets, Odoo creates entries in the
-*Timesheets* application for the time off. This section defines how they are entered.
+**Timesheets** app for the time off. This section defines how they are entered.
 
-- :guilabel:`Project`: select the project that the time off type entries appear in.
+- :guilabel:`Project`: Select the project the time off type entries appear in.
-- :guilabel:`Task`: select the task that appears in the timesheet for this time off type. The
+- :guilabel:`Task`: Select the task that appears in the timesheet for this time off type. The
   default options are: :guilabel:`Time Off`, :guilabel:`Meeting`, or :guilabel:`Training`.
 
 Display Option section
 **********************
 
-- :guilabel:`Color`: select a color to be used in the *Time Off* application dashboard.
+- :guilabel:`Color`: Select a color to be used in the **Time Off** app dashboard.
-- :guilabel:`Cover Image`: select an icon to be used in the *Time Off* application dashboard.
+- :guilabel:`Cover Image`: Select an icon to be used in the **Time Off** app dashboard.
 
 .. image:: time_off/time-off-type-form-bottom.png
    :align: center
@@ -221,35 +220,31 @@ Plans`. Then, click the :guilabel:`New` button, which reveals a blank accrual pl
 
 Enter the following information on the form:
 
-- :guilabel:`Name`: enter the accrual plan name.
+- :guilabel:`Name`: Enter the accrual plan name.
-- :guilabel:`Accrued Gain Time`: select when the employee begins to accrue time off, either
+- :guilabel:`Accrued Gain Time`: Select when the employee begins to accrue time off, either
   :guilabel:`At the start of the accrual period` or :guilabel:`At the end of the accrual period`.
-- :guilabel:`Carry-Over Time`: select when the employee received previously earned time. The options
+- :guilabel:`Carry-Over Time`: Select when the employee received previously earned time. The options
   are:
 
-  - :guilabel:`At the start of the year`: select this if the accrual rolls over on January 1 of the
+  - :guilabel:`At the start of the year`: Select this if the accrual rolls over on January 1 of the
     upcoming year.
-  - :guilabel:`At the allocation date`: select this if the accrual rolls over as soon as time is
+  - :guilabel:`At the allocation date`: Select this if the accrual rolls over as soon as time is
     allocated to the employee.
-  - :guilabel:`Other`: select this option if neither of the other two options are applicable. When
+  - :guilabel:`Other`: Select this option if neither of the other two options are applicable. When
     selected, a :guilabel:`Carry-Over Date` field appears. Select the date using the two drop-down
     menus, one for the day and one for the month.
 
-- :guilabel:`Based on worked time`: enable this option if time off accrual is determined by the
+- :guilabel:`Based on worked time`: Enable this option if time off accrual is determined by the
   employee's worked hours. Days **not** considered as worked time do **not** contribute to the
   accrual plan in Odoo.
-- :guilabel:`Milestone Transition`: this selection determines when employees move up to a new
+- :guilabel:`Milestone Transition`: This field is **only** visible after a minimum of two
-  milestone. If they qualify to change milestones in the middle of a pay period, select if the
+  :ref:`rules <time_off/rules>` have been configured on the accrual plan. This selection determines
-  employee changes milestones :guilabel:`Immediately` or :guilabel:`After this accrual's period`
+  when employees move up to a new milestone. If they qualify to change milestones in the middle of a
-  (after the current pay period).
+  pay period, decide whether the employee changes milestones :guilabel:`Immediately` or
-
+  :guilabel:`After this accrual's period` (after the current pay period).
-  .. important::
+- :guilabel:`Company`: This field **only** appears in a multi-company database. Using the drop-down
-     The :guilabel:`Milestone Transition` field is **only** visible after a minimum of two
+  menu, select the company the accrual plan applies to. If left blank, the accrual plan can be used
-     :ref:`rules <time_off/rules>` have been configured on the accrual plan.
+  for all companies.
-
-- :guilabel:`Company`: using the drop-down menu, select the company the accrual plan applies to. If
-  left blank, the accrual plan can be used for all companies. This field only appears in a
-  multi-company database.
 
 .. image:: time_off/accrual-plan-form.png
    :align: center
@@ -267,7 +262,7 @@ section, and a :guilabel:`Create Milestone` modal form appears.
 
 Fill out the following fields on the form:
 
-- :guilabel:`Employee accrue`: select the parameters for earned time off in this section.
+- :guilabel:`Employee accrue`: Select the parameters for earned time off in this section.
 
   First, select either :guilabel:`Days` or :guilabel:`Hours` for the increment of accrued time using
   the drop-down menu.
@@ -281,8 +276,8 @@ Fill out the following fields on the form:
 
   Depending on which option is selected, additional fields may appear. For example, if
   :guilabel:`Twice a month` is selected, two additional fields appear, to specify the two days of
-  each month that the milestone occurs.
+  each month the milestone occurs.
-- :guilabel:`Cap accrued time`: if there is a maximum amount of days the employee can accrue with
+- :guilabel:`Cap accrued time`: If there is a maximum amount of days the employee can accrue with
   this plan, enable this option.
 
   When enabled, two additional fields appear beneath it. Select the type of time period from the
@@ -290,7 +285,7 @@ Fill out the following fields on the form:
 
   Then, enter a numerical value in the field to specify the maximum amount of time that can be
   accrued.
-- :guilabel:`Milestone reached`: enter the number and value of the time period that must pass before
+- :guilabel:`Milestone reached`: Enter the number and value of the time period that must pass before
   the employee starts to accumulate time off. The first value is numerical; enter a number in the
   first field.
 
@@ -298,17 +293,37 @@ Fill out the following fields on the form:
   are: :guilabel:`Days`, :guilabel:`Months`, or :guilabel:`Years`.
 - :guilabel:`Carry over`: select how any unused time off is handled. The options are either:
 
-  - :guilabel:`None. Accrued time reset to 0`: any unused time off is gone.
+  - :guilabel:`None. Accrued time reset to 0`: Any unused time off is gone.
-  - :guilabel:`All accrued time carried over`: all unused time off is rolled over to the next
+  - :guilabel:`All accrued time carried over`: All unused time off is rolled over to the next
     calendar year.
-  - :guilabel:`Carry over with a maximum`: unused time off is rolled over to the next calendar year,
+  - :guilabel:`Carry over with a maximum`: Unused time off is rolled over to the next calendar year,
     but there is a cap. An :guilabel:`Up to` field appears if this is selected. Enter the maximum
     number of :guilabel:`Days` that can roll over to the following year. Any time off beyond this
     parameter is lost.
 
-Once the form is completed, click :guilabel:`Save & Close` to save the form and close the modal, or
+.. important::
-click :guilabel:`Save & New` to save the form and create another milestone. Add as many milestones
+   If the :guilabel:`Carry over` field is set to :guilabel:`None. Accrued time reset to 0`, that
-as desired.
+   rule *overrides* the :guilabel:`Carry-Over Time` set on the accrual plan.
+
+   If a company creates an accrual plan, granting employees time off :guilabel:`At the start of the
+   accrual period` (i.e., the beginning of the year), and sets the :guilabel:`Carry-Over Time` on
+   the *accrual plan* to :guilabel:`At the start of the year`, it allows unused vacation time to
+   rollover to the following year.
+
+   Then, the company adds rules to the accrual plan, allocating five days of vacation, annually, on
+   the first of the year (one week of vacation allocated on January 1st).
+
+   If the :guilabel:`Carry over` field is set to :guilabel:`None. Accrual time reset to 0` on the
+   :guilabel:`Create Milestone` pop-up for, any unused vacation time *does not* carry over, even
+   though on the :guilabel:`Accrual Plan` form, the :guilabel:`Carry-Over Time` is set to
+   :guilabel:`At the start of the year`.
+
+   The carry over set on the *rule* takes precedence over the carry over set on the *accrual plan
+   form*.
+
+Once the form is completed, click :guilabel:`Save & Close` to save the :guilabel:`Create Milestone`
+form, and close the modal, or click :guilabel:`Save & New` to save the form and create another
+milestone. Add as many milestones as desired.
 
 .. image:: time_off/milestone.png
    :align: center
@@ -325,8 +340,8 @@ configure the observed *public holidays* in Odoo.
 It is important to configure these days in Odoo, so employees are aware of the days they have off,
 and do not request time off on days that are already set as a public holiday (non-working days).
 
-Additionally, all public holidays configured in the *Time Off* app are also reflected in any app
+Additionally, all public holidays configured in the **Time Off** app are also reflected in any app
-that uses working schedules, such as *Calendar*, *Planning*, *Manufacturing*, and more.
+that uses working schedules, such as **Calendar**, **Planning**, **Manufacturing**, and more.
 
 Due to Odoo's integration with other apps that use working schedules, it is considered best practice
 to ensure *all* public holidays are configured.
@@ -343,25 +358,26 @@ Click the :guilabel:`New` button, and a new line appears at the bottom of the li
 
 Enter the following information on that new line:
 
-- :guilabel:`Name`: enter the name of the holiday.
+- :guilabel:`Name`: Enter the name of the holiday.
-- :guilabel:`Company`: if in a multi-company database, the current company populates this field by
+- :guilabel:`Company`: If in a multi-company database, the current company populates this field by
-  default. It is not possible to edit this field.
+  default. It is **not** possible to edit this field.
 
   .. note::
-     The :guilabel:`Company` field is hidden by default. To view this field, click the two dots in
+     The :guilabel:`Company` field is hidden, by default. To view this field, click the
-     the top-right corner of the list, to the far-right of the column titles, and activate the
+     :icon:`oi-settings-adjust` :guilabel:`(additional options)` icon in the top-right corner of the
-     :guilabel:`Company` selection from the drop-down menu that appears.
+     list, to the far-right of the column titles, and activate the :guilabel:`Company` selection
+     from the drop-down menu that appears.
 
-- :guilabel:`Start Date`: using the date and time picker, select the date and time that the holiday
+- :guilabel:`Start Date`: Using the date and time picker, select the date and time the holiday
-  starts. By default, this field is configured for the current date. The start time is set according
+  starts, then click :icon:`fa-check` :guilabel:`Apply`. By default, this field is configured for
-  to the start time for the company (according to the :ref:`working schedules
+  the current date. The start time is set according to the start time for the company (according to
-  <payroll/working-times>`). If the user's computer is set to a different time zone, the start time
+  the :ref:`working schedules <payroll/working-times>`). If the user's computer is set to a
-  is adjusted according to the difference in the time zone, compared to the company's time zone.
+  different time zone, the start time is adjusted according, compared to the company's time zone.
-- :guilabel:`End Date`: using the date and time picker, select the date and time that the holiday
+- :guilabel:`End Date`: Using the date and time picker, select the date and time the holiday ends,
-  ends. By default, this field is configured for the current date, and the time is set to the end
+  then click :icon:`fa-check` :guilabel:`Apply`. By default, this field is configured for the
-  time for the company (according to the :ref:`working schedules <payroll/working-times>`). If the
+  current date, and the time is set to the end time for the company (according to the :ref:`working
-  user's computer is set to a different time zone, the start time is adjusted according to the
+  schedules <payroll/working-times>`). If the user's computer is set to a different time zone, the
-  difference in the time zone, compared to the company's time zone.
+  start time is adjusted accordingly, compared to the company's time zone.
 
   .. example::
      A company located in San Francisco operates from 9:00 AM - 6:00 PM, with an eight hour work day
@@ -374,12 +390,12 @@ Enter the following information on that new line:
      Similarly, a user located in Los Angeles, with a computer time zone set to Pacific Standard
      Time, sees a public holiday time as 9:00 AM - 6:00 PM.
 
-- :guilabel:`Working Hours`: if the holiday should only apply to employees who have a specific set
+- :guilabel:`Working Hours`: If the holiday should only apply to employees who have a specific set
   of working hours, select the working hours from the drop-down menu. If left blank, the holiday
   applies to all employees.
-- :guilabel:`Work Entry Type`: if using the *Payroll* application, this field defines how the
+- :guilabel:`Work Entry Type`: If using the **Payroll** app, this field defines how the :ref:`work
-  :ref:`work entries <payroll/work-entries>` for the holiday appear. Select the work entry type
+  entries <payroll/work-entries>` for the holiday appear. Select the work entry type from the
-  from the drop-down menu.
+  drop-down menu.
 
 .. image:: time_off/holidays.png
    :align: center
@@ -405,25 +421,26 @@ Click the :guilabel:`New` button in the top-left corner, and a blank line appear
 
 Enter the following information on that new line:
 
-- :guilabel:`Name`: enter the name of the mandatory day.
+- :guilabel:`Name`: Enter the name of the mandatory day.
-- :guilabel:`Company`: if in a multi-company database, this field is visible, and the current
+- :guilabel:`Company`: If in a multi-company database, this field is visible, and the current
-  company populates this field by default. Using the drop-down menu, select the company the
+  company populates this field, by default. Using the drop-down menu, select the company the
   mandatory day is for.
-- :guilabel:`Departments`: this column is hidden by default. First, click the :guilabel:`(optional
+- :guilabel:`Departments`: This column is hidden by default. First, click the
-  columns)` icon in the top-right corner, next to :guilabel:`Colors`, and then click the checkbox
+  :icon:`oi-settings-adjust` :guilabel:`(additional options)` icon in the top-right corner, next to
-  next to :guilabel:`Departments` to reveal that column.
+  :guilabel:`Color`, and then tick the checkbox next to :guilabel:`Departments` to reveal that
+  column.
 
   Next, select the desired departments from the drop-down menu. Multiple departments can be
   selected, and there is no limit to the amount of departments that can be added.
 
   If this field is left blank, the mandatory day applies to the entire company.
-- :guilabel:`Start Date`: using the calendar picker, select the date the mandatory day starts.
+- :guilabel:`Start Date`: Using the calendar picker, select the date the mandatory day starts.
-- :guilabel:`End Date`: using the calendar picker, select the date the mandatory day ends. If
+- :guilabel:`End Date`: Using the calendar picker, select the date the mandatory day ends. If
   creating a single mandatory day, the end date should be the same as the start date.
-- :guilabel:`Color`: if desired, select a color from the available presented options. If no color is
+- :guilabel:`Color`: If desired, select a color from the available presented options. If no color is
   desired, select the `No color` option, represented by a white box with a red line diagonally
-  across it. The selected color appears on the main *Time Off* application dashboard, in both the
+  across it. The selected color appears on the main **Time Off** app dashboard, in both the calendar
-  calendar and in the legend.
+  and in the legend.
 
 .. image:: time_off/mandatory.png
    :align: center
@@ -480,9 +497,13 @@ The reporting feature allows users to view time off for their team, either by em
 time off. This allows users to see which employees are taking time off, how much time off they are
 taking, and what time off types are being used.
 
-Any report can be added to a spreadsheet through the *Insert in Spreadsheet* button that appears in
+Any report can be added to a spreadsheet, when in either the :icon:`fa-area-chart`
-the top-left of a report. If the *Documents* application is installed, an option to add the report
+:guilabel:`(Graph)` or :icon:`oi-view-pivot` :guilabel:`(Pivot)` view, through the *Insert in
-to a spreadsheet appears. If not, the report can be added to a *Dashboard*.
+Spreadsheet* button that appears in the top-left of the report.
+
+.. note::
+   If the **Documents** app is installed, an option to add the report to a spreadsheet appears. If
+   not, the report can be added to a *Dashboard*.
 
 By employee
 -----------
@@ -507,12 +528,8 @@ Days` off requested, the :guilabel:`Start Date`, :guilabel:`End Date`, :guilabel
 
 The report can be displayed in other ways, as well. Click the corresponding button option in the
 top-right corner of the page to view the data in that specific way. The various options are a
-:guilabel:`List` (the default view), :guilabel:`Graph`, :guilabel:`Pivot` table, or
+:icon:`oi-view-list` :guilabel:`(List)`, or default view, :icon:`fa-area-chart` :guilabel:`(Graph)`,
-:guilabel:`Calendar` view.
+:icon:`oi-view-pivot` :guilabel:`(Pivot)` table, or :icon:`fa-calendar` :guilabel:`(Calendar)` view.
-
-.. image:: time_off/report-options.png
-   :align: center
-   :alt: The various other views highlighted, for the employee time off report.
 
 When a selection has been made, additional options appear for that particular selection. For more
 detailed information on the reports and their various options, refer to the :doc:`reporting
@@ -539,7 +556,8 @@ Each request is listed, with the following information displayed: the :guilabel:
 
 The report can be displayed in other ways, as well. Click the corresponding button option in the
 top-right corner of the page to view the data in that way. The various options are a
-:guilabel:`Graph` (the default view), :guilabel:`List`, or :guilabel:`Pivot` table.
+:icon:`fa-area-chart` :guilabel:`(Graph)` (the default view), :icon:`oi-view-list`
+:guilabel:`(List)`, or :icon:`oi-view-pivot` :guilabel:`(Pivot)` table.
 
 When a selection has been made, additional options appear for that particular selection. For more
 detailed information on the reports, and their various options, refer to the :doc:`reporting