[IMP] tutorials: add example code for LazyComponent

js framework/Build a Dashboard/part 8 (LazyComponent)

There is no explicit instructions on how to use `LazyComponent`.

- add an example code snippet for minimal use of `LazyComponent`
- add the `.js` extension to the file you're supposed to create to make it a bit more intuitive
- fix `actions` registry name (missing an s)
- reword instructions in a more straightforward way

content/administration/odoo_accounts.rst

@@ -30,6 +30,8 @@ confirmation for the account deletion.
 To confirm the deletion, enter the :guilabel:`Password` and the :guilabel:`Login` for the account
 being deleted. Then, click the :guilabel:`Delete Account` button to confirm the deletion.
 
+.. _odoocom/change_password:
+
 Odoo.com account password change
 ================================
 

content/administration/on_premise/deploy.rst

@@ -740,7 +740,143 @@ It should be stored securely, and should be generated randomly e.g.
 
     $ python3 -c 'import base64, os; print(base64.b64encode(os.urandom(24)))'
 
-which will generate a 32 characters pseudorandom printable string.
+which generates a 32-character pseudorandom printable string.
+
+Reset the master password
+-------------------------
+
+There may be instances where the master password is misplaced, or compromised, and needs to be
+reset. The following process is for system administrators of an Odoo on-premise database detailing
+how to manually reset and re-encrypt the master password.
+
+.. seealso::
+   For more information about changing an Odoo.com account password, see this documentation:
+   :ref:`odoocom/change_password`.
+
+When creating a new on-premise database, a random master password is generated. Odoo recommends
+using this password to secure the database. This password is implemented by default, so there is a
+secure master password for any Odoo on-premise deployment.
+
+.. warning::
+   When creating an Odoo on-premise database the installation is accessible to anyone on the
+   internet, until this password is set to secure the database.
+
+The master password is specified in the Odoo configuration file (`odoo.conf` or `odoorc` (hidden
+file)). The Odoo master password is needed to modify, create, or delete a database through the
+graphical user interface (GUI).
+
+Locate configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First, open the Odoo configuration file (`odoo.conf` or `odoorc` (hidden file)).
+
+.. tabs::
+
+   .. tab:: Windows
+
+      The configuration file is located at: `c:\\ProgramFiles\\Odoo{VERSION}\\server\\odoo.conf`
+
+   .. tab:: Linux
+
+      Depending on how Odoo is installed on the Linux machine, the configuration file is located in
+      one of two different places:
+
+      - Package installation: `/etc/odoo.conf`
+      - Source installation: `~/.odoorc`
+
+Change old password
+~~~~~~~~~~~~~~~~~~~
+
+Once the appropriate file has been opened, proceed to modify the old password in the configuration
+file to a temporary password.
+
+.. tabs::
+
+   .. group-tab:: Graphical user interface
+
+      After locating the configuration file, open it using a (:abbr:`GUI (graphical user
+      interface)`). This can be achieved by simply double clicking on the file. Then, the device
+      should have a default :abbr:`GUI (graphical user interface)` to open the file with.
+
+      Next, modify the master password line `admin_passwd = $pbkdf2-sha…` to `admin_passwd =
+      newpassword1234`, for example. This password can be anything, as long as it is saved
+      temporarily. Make sure to modify all characters after the `=`.
+
+      .. example::
+         The line appears like this:
+         `admin_passwd =
+         $pbkdf2-sh39dji295.59mptrfW.9z6HkA$w9j9AMVmKAP17OosCqDxDv2hjsvzlLpF8Rra8I7p/b573hji540mk/.3ek0lg%kvkol6k983mkf/40fjki79m`
+
+         The modified line appears like this: `admin_passwd = newpassword1234`
+
+   .. group-tab:: Command-line interface
+
+      Modify the master password line using the following Unix command detailed below.
+
+      Connect to the Odoo server's terminal via Secure Shell (SSH) protocol, and edit the
+      configuration file. To modify the configuration file, enter the following command:
+      :command:`sudo nano /etc/odoo.conf`
+
+      After opening the configuration file, modify the master password line `admin_passwd =
+      $pbkdf2-sha…` to `admin_passwd = newpassword1234`. This password can be anything, as long as
+      it is saved temporarily. Make sure to modify all characters after the `=`.
+
+      .. example::
+         The line appears like this:
+         `admin_passwd =
+         $pbkdf2-sh39dji295.59mptrfW.9z6HkA$w9j9AMVmKAP17OosCqDxDv2hjsvzlLpF8Rra8I7p/b573hji540mk/.3ek0lg%kvkol6k983mkf/40fjki79m`
+
+         The modified line appears like this: `admin_passwd = newpassword1234`
+
+.. important::
+   It is essential that the password is changed to something else, rather than triggering a new
+   password reset by adding a semicolon `;` at the beginning of the line. This ensures the database
+   is secure throughout the entire password reset process.
+
+Restart Odoo server
+~~~~~~~~~~~~~~~~~~~
+
+After setting the temporary password, a restart of the Odoo server is **required**.
+
+.. tabs::
+
+   .. group-tab:: Graphical user interface
+
+      To restart the Odoo server, first, type `services` into the Windows :guilabel:`Search` bar.
+      Then, select the :guilabel:`Services` application, and scroll down to the :guilabel:`Odoo`
+      service.
+
+      Next, right click on :guilabel:`Odoo`, and select :guilabel:`Start` or :guilabel:`Restart`.
+      This action manually restarts the Odoo server.
+
+   .. group-tab:: Command-line interface
+
+      Restart the Odoo server by typing the command: :command:`sudo service odoo15 restart`
+
+      .. note::
+         Change the number after `odoo` to fit the specific version the server is running on.
+
+Use web interface to re-encrypt password
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First, navigate to `/web/database/manager` or `http://server_ip:port/web/database/manager` in a
+browser.
+
+.. note::
+   Replace `server_ip` with the IP address of the database. Replace `port` with the numbered port
+   the database is accessible from.
+
+Next, click :guilabel:`Set Master Password`, and type in the previously-selected temporary password
+into the :guilabel:`Master Password` field. Following this step, type in a :guilabel:`New Master
+Password`. The :guilabel:`New Master Password` is hashed (or encrypted), once the
+:guilabel:`Continue` button is clicked.
+
+At this point, the password has been successfully reset, and a hashed version of the new password
+now appears in the configuration file.
+
+.. seealso::
+   For more information on Odoo database security, see this documentation:
+   :ref:`db_manager_security`.
 
 Supported Browsers
 ==================

content/applications/finance/accounting/get_started/avg_price_valuation.rst

@@ -24,12 +24,14 @@ to reflect the change in inventory valuation. However, Odoo does **not** automat
 valuation <inventory/avg_price/leaving_inventory>`.
 
 .. note::
-   This document addresses a specific use case for theoretical purposes. Navigate :ref:`here
-   <inventory/management/inventory_valuation_config>` for instructions on how to set up and use
-   |AVCO| in Odoo.
+   This document addresses a specific use case for theoretical purposes. For instructions on how to
+   set up and use |AVCO|, refer to the :doc:`inventory valuation configuration
+   <../../../inventory_and_mrp/inventory/warehouses_storage/inventory_valuation/inventory_valuation_config>`
+   doc.
 
 .. seealso::
-   - :ref:`Using inventory valuation <inventory/reporting/using_inventory_val>`
+   - :doc:`Using inventory valuation
+     <../../../inventory_and_mrp/inventory/warehouses_storage/inventory_valuation/using_inventory_valuation>`
    - :ref:`Other inventory valuation methods <inventory/inventory_valuation_config/costing_methods>`
 
 Configuration
@@ -41,7 +43,8 @@ product category page, set :guilabel:`Costing Method` to `Average Cost (AVCO)` a
 :guilabel:`Inventory Valuation` to `Automated`.
 
 .. seealso::
-   :ref:`Inventory valuation configuration <inventory/management/inventory_valuation_config>`
+   :doc:`Inventory valuation configuration
+   <../../../inventory_and_mrp/inventory/warehouses_storage/inventory_valuation/inventory_valuation_config>`
 
 Using average cost valuation
 ============================

content/applications/finance/accounting/reporting/year_end.rst

@@ -101,8 +101,9 @@ correctly reporting a balance of zero. If that is the case, set an :guilabel:`Al
 to the last day of the fiscal year by going to :menuselection:`Accounting --> Accounting --> Lock
 Dates`.
 
-.. warning::
-   Setting an :guilabel:`All Users Lock Date` is **irreversible** and cannot be removed.
+.. tip::
+   Install the :guilabel:`Irreversible Lock Date` (`account_lock`) module to make the :guilabel:`All
+   Users Lock Date` *irreversible* once set.
 
 .. note::
    A specific year-end closing entry is **optional** in order to close out the **profit and loss

content/applications/finance/accounting/taxes/avatax.rst

@@ -1,74 +1,440 @@
+:show-content:
+
 ==================
-Avatax integration
+AvaTax integration
 ==================
 
-Avatax is a tax calculation provider that can be integrated in Odoo.
+Avalara's *AvaTax* is a cloud-based tax software. Integrating *AvaTax* with Odoo provides real-time
+and region-specific tax calculations when users sell, purchase, and invoice items in Odoo. *AvaTax*
+tax calculation is supported with every United Nations charted country, including inter-border
+transactions.
+
+.. important::
+   *AvaTax* is only available for integration with databases/companies that have locations in the
+   United States, Canada, and Brazil. This means the fiscal position/country of a database can only
+   be set to the United States, Canada, or Brazil. For more information, reference this
+   documentation: :ref:`avatax/fiscal_country`.
+
+*AvaTax* accounts for location-based tax rates for each state, county, and city. It improves
+remittance accuracy by paying close attention to laws, rules, jurisdiction boundaries, and special
+circumstances (like, tax holidays, and product exemptions). Companies who integrate with *AvaTax*
+can maintain control of tax-calculations in-house with this simple :abbr:`API (application
+programming interface)` integration.
+
+.. important::
+   Some limitations exist in Odoo while using *AvaTax* for tax calculation:
+
+   - *AvaTax* is **not** supported in Odoo's *Point of Sale* app, because a dynamic tax calculation
+     model is excessive for transactions within a single delivery address, such as stores or
+     restaurants.
+   - *AvaTax* and Odoo use the company address and **not** the warehouse address.
+   - Exercise tax is **not** supported. This includes tobacco/vape taxes, fuel taxes, and other
+     specific industries.
+
+.. seealso::
+   Avalara's support documents: `About AvaTax
+   <https://community.avalara.com/support/s/document-item?language=en_US&bundleId=dqa1657870670369_dqa1657870670369&topicId=About_AvaTax.html&_LANG=enus>`_
+
+Set up on AvaTax
+================
+
+To use *AvaTax*, an account with Avalara is required for the setup. If one has not been set up yet,
+connect with Avalara to purchase a license: `Avalara: Let's Talk
+<https://www.avalara.com/us/en/get-started.html>`_.
+
+.. tip::
+   Upon account setup, take note of the *AvaTax* :guilabel:`Account ID`. This will be needed in the
+   :ref:`Odoo setup <avatax/credentials>`. In Odoo, this number is the :guilabel:`API ID`.
+
+Then, `create a basic company profile
+<https://community.avalara.com/support/s/document-item?bundleId=dqa1657870670369_dqa1657870670369&topicId=Create_a_Basic_company_profile.html&_LANG=enus>`_.
+
+Create basic company profile
+----------------------------
+
+Collect essential business details for the next step: locations where tax is collected,
+products/services sold (and their sales locations), and customer tax exemptions, if applicable.
+Follow the Avalara documentation for creating a basic company profile:
+
+#. `Add company information
+   <https://community.avalara.com/support/s/document-item?bundleId=dqa1657870670369_dqa1657870670369&topicId=Add_your_company_information.html&_LANG=enus>`_.
+#. `Tell us where the company collects and pays tax
+   <https://community.avalara.com/support/s/document-item?bundleId=dqa1657870670369_dqa1657870670369&topicId=Tell_us_where_you_collect_and_pay_tax.html&_LANG=enus>`_.
+#. `Verify jurisdictions and activate the company
+   <https://community.avalara.com/support/s/document-item?bundleId=dqa1657870670369_dqa1657870670369&topicId=Verify_your_jurisdictions_and_activate_your_company.html&_LANG=enus>`_.
+#. `Add other company locations for location-based filing
+   <https://community.avalara.com/support/s/document-item?bundleId=dqa1657870670369_dqa1657870670369&topicId=Add_other_company_locations_for_location-based_filing.html&_LANG=enus>`_.
+#. `Add a marketplace to the company profile
+   <https://community.avalara.com/support/s/document-item?bundleId=dqa1657870670369_dqa1657870670369&topicId=Add_marketplace_transactions_to_your_company_profile.html&_LANG=enus>`_.
+
+.. _avatax/create_avalara_credentials:
+
+Connect to AvaTax
+-----------------
+
+After creating the basic company profile in Avalara, connect to *AvaTax*. This step links Odoo and
+*AvaTax* bidirectionally.
+
+Navigate to either Avalara's `sandbox <https://sandbox.admin.avalara.com/>`_ or `production
+<https://admin.avalara.com/>`_ environment. This will depend on which type of Avalara account the
+company would like to integrate.
+
+.. seealso::
+   `Sandbox vs production environments in Avalara
+   <https://knowledge.avalara.com/bundle/fzc1692293626742/page/sandbox-vs-production.html>`_.
+
+Log in to create the :guilabel:`License Key`. Go to :menuselection:`Settings --> License and API
+Keys`. Click :guilabel:`Generate License Key`.
+
+.. note::
+   A warning appears stating: `If your business app is connected to Avalara solutions, the
+   connection will be broken until you update the app with the new license key. This action cannot
+   be undone.`
+
+   Generating a new license key breaks the connection with existing business apps using the *AvaTax*
+   integration. Make sure to update these apps with the new license key.
+
+If this will be the first :abbr:`API (application programming interface)` integration being made
+with *AvaTax* and Odoo, then click :guilabel:`Generate license key`.
+
+If this is an additional license key, ensure the previous connection can be broken. There is
+**only** one license key associated with each of the Avalara sandbox and production accounts.
+
+.. important::
+   Copy this key to a safe place. It is **strongly encouraged** to backup the license key for future
+   reference. This key cannot be retrieved after leaving this screen.
+
+Odoo configuration
+==================
+
+Before using *AvaTax*, there are some additional configurations in Odoo to ensure tax calculations
+are made accurately.
+
+Verify that the Odoo database contains necessary data. The country initially set up in the database
+determines the fiscal position, and aids *AvaTax* in calculating accurate tax rates.
+
+.. _avatax/fiscal_country:
+
+Fiscal country
+--------------
+
+To set the :guilabel:`Fiscal Country`, navigate to :menuselection:`Accounting app --> Configuration
+--> Settings`.
+
+.. seealso::
+   :doc:`../../fiscal_localizations`
+
+Under the :guilabel:`Taxes` section, set the :guilabel:`Fiscal Country` feature to :guilabel:`United
+States`, :guilabel:`Canada`, or :guilabel:`Brazil`. Then, click :guilabel:`Save`.
+
+Company settings
+----------------
+
+All companies operating under the Odoo database should have a full and complete address listed in
+the settings. Navigate to the :menuselection:`Settings app`, and under the :guilabel:`Companies`
+section, ensure there is only one company operating the Odoo database. Click :guilabel:`Update Info`
+to open a separate page to update company details.
+
+If there are multiple companies operating in the database, click :guilabel:`Manage Companies` to
+load a list of companies to select from. Update company information by clicking into the specific
+company.
+
+Database administrators should ensure that the :guilabel:`Street...`, :guilabel:`Street2...`,
+:guilabel:`City`, :guilabel:`State`, :guilabel:`ZIP`, and :guilabel:`Country` are all updated for
+the companies.
+
+This ensures accurate tax calculations and smooth end-of-year accounting operations.
+
+.. seealso::
+   - :doc:`../../../general/companies`
+   - :doc:`../get_started`
+
+Module installation
+-------------------
+
+Next, ensure that the Odoo *AvaTax* module is installed. To do so, navigate to the
+:menuselection:`Apps application`. In the :guilabel:`Search...` bar, type in `avatax`, and press
+:kbd:`Enter`. The following results populate:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 25 50
+
+   * - Name
+     - Technical name
+     - Description
+   * - :guilabel:`Avatax`
+     - `account_avatax`
+     - Default *AvaTax* module. This module adds the base *AvaTax* features for tax calculation.
+   * - :guilabel:`Avatax for geo localization`
+     - `account_avatax_geolocalize`
+     - This module includes the features required for integration of *AvaTax* into geo-localization
+       in Odoo.
+   * - :guilabel:`Avatax for SO`
+     - `account_avatax_sale`
+     - Includes the information needed for tax calculation on sales orders in Odoo.
+   * - :guilabel:`Avatax for Inventory`
+     - `account_avatax_stock`
+     - Includes tax calculation in Odoo Inventory.
+   * - :guilabel:`Amazon/Avatax Bridge`
+     - `sale_amazon_avatax`
+     - Includes tax calculation features between the *Amazon Connector* and Odoo.
+   * - :guilabel:`Avatax Brazil`
+     - `l10n_br_avatax`
+     - Includes information for tax calculation in the Brazil localization.
+   * - :guilabel:`Avatax Brazil for Services`
+     - `l10n_br_avatax_services`
+     - This module includes the required features for tax calculation for services in the Brazil
+       localization.
+   * - :guilabel:`Avatax Brazil Sale for Services`
+     - `l10n_br_edi_sale_services`
+     - This module includes the required features for tax calculation for the sale of services in
+       the Brazil localization. This includes electronic data interchange (EDI).
+   * - :guilabel:`Test SOs for the Brazilian AvaTax`
+     - `l10n_br_test_avatax_sale`
+     - This module includes the required features for test sales orders in the Brazil localization.
+
+Click the :guilabel:`Install` button on the module labeled, :guilabel:`Avatax`: `account_avatax`.
+Doing so installs the following modules:
+
+- :guilabel:`Avatax`: `account_avatax`
+- :guilabel:`Avatax for SO`: `account_avatax_sale`
+- :guilabel:`Avatax for Inventory`: `account_avatax_stock`
+
+Should *AvaTax* be needed for geo-localization, or with the *Amazon Connector*, then install those
+modules individually by clicking on :guilabel:`Install` on :guilabel:`Avatax for geo localization`
+and :guilabel:`Amazon/Avatax Bridge`, respectively.
+
+.. seealso::
+   For localization specific *AvaTax* instructions, view the following :doc:`fiscal localization
+   <../../fiscal_localizations>` documentation:
+
+   - :doc:`../../fiscal_localizations/brazil`
 
 .. _avatax/credentials:
 
-Credential configuration
-========================
+Odoo AvaTax settings
+--------------------
 
-To integrate Avatax with Odoo, go to :menuselection:`Accounting --> Configuration --> Settings -->
-Taxes` and add your Avatax credentials in the :guilabel:`Avatax` section.
+To integrate the *AvaTax* :abbr:`API (application programming interface)` with Odoo, go to
+:menuselection:`Accounting app --> Configuration --> Settings` section. The :guilabel:`AvaTax`
+fields in the :guilabel:`Taxes` section is where the *AvaTax* configurations are made, and the
+credentials are entered in.
 
-.. tip::
-   If you do not yet have credentials, click on :guilabel:`How to Get Credentials`.
+First, tick the checkbox to the left of the :guilabel:`AvaTax` settings, to activate *AvaTax* on the
+database. This is a quick, convenient way to activate and deactivate *AvaTax* tax calculation on the
+Odoo database.
 
 .. image:: avatax/avatax-configuration-settings.png
    :align: center
-   :alt: Configure Avatax settings
+   :alt: Configure AvaTax settings
 
-.. _avatax/tax-mapping:
+Prerequisites
+~~~~~~~~~~~~~
+
+First, select the :guilabel:`Environment` in which the company wishes to use *AvaTax* in. It can
+either be :guilabel:`Sandbox` or :guilabel:`Production`.
+
+.. seealso::
+   For help determining which *AvaTax* environment to use (either :guilabel:`Production` or
+   :guilabel:`Sandbox`), visit: `Sandbox vs Production environments
+   <https://knowledge.avalara.com/bundle/fzc1692293626742/page/sandbox-vs-production.html>`_.
+
+Credentials
+~~~~~~~~~~~
+
+Now, the credentials can be entered in. The *AvaTax* :guilabel:`Account ID` should be entered in the
+:guilabel:`API ID` field, and the :guilabel:`License Key` should be entered in the :guilabel:`API
+Key` field.
+
+.. important::
+   The :guilabel:`Account ID` can be found by logging into the *AvaTax* portal (`sandbox
+   <https://sandbox.admin.avalara.com/>`_ or `production <https://admin.avalara.com/>`_). In the
+   upper-right corner, click on the initials of the user and :guilabel:`Account`. The
+   :guilabel:`Account ID` is listed first.
+
+   To access the :guilabel:`License Key` see this documentation:
+   :ref:`avatax/create_avalara_credentials`.
+
+For the :guilabel:`Company Code` field, enter the Avalara company code for the company being
+configured. Avalara interprets this as `DEFAULT`, if it is not set. The :guilabel:`Company Code` can
+be accessed in the Avalara management portal.
+
+First, log into the *AvaTax* portal (`sandbox <https://sandbox.admin.avalara.com/>`_ or `production
+<https://admin.avalara.com/>`_). Then, navigate to :menuselection:`Settings --> Manage Companies`.
+The :guilabel:`Company Code` value is located in the row of the :guilabel:`Company` in the
+:guilabel:`Company Code` column.
+
+.. image:: avatax/company-code.png
+   :align: center
+   :alt: AvaTax company code highlighted on the company details page.
+
+Transaction options
+~~~~~~~~~~~~~~~~~~~
+
+There are two transactional settings in the Odoo *AvaTax* settings that can be configured:
+:guilabel:`Use UPC` and :guilabel:`Commit Transactions`.
+
+If the checkbox next to :guilabel:`Use UPC` is ticked, the transactions will use Universal Product
+Codes (UPC), instead of custom defined codes in Avalara. Consult a certified public accountant (CPA)
+for specific guidance.
+
+Should the :guilabel:`Commit Transactions` checkbox be ticked, then, the transactions in the Odoo
+database will be committed for reporting in *AvaTax*.
+
+Address validation
+~~~~~~~~~~~~~~~~~~
+
+The *Address Validation* feature ensures that the most up-to-date address by postal standards is set
+on a contact in Odoo. This is important to provide accurate tax calculations for customers.
+
+.. important::
+   The :guilabel:`Address Validation` feature only works with partners/customers in North America.
+
+Additionally, tick the checkbox next to the :guilabel:`Address validation` field.
+
+.. important::
+   For accurate tax calculations, it is best practice to enter a complete address for the contacts
+   saved in the database. However, *AvaTax* can still function by implementing a best effort attempt
+   using only the :guilabel:`Country`, :guilabel:`State`, and :guilabel:`Zip code`. These are the
+   three minimum required fields.
+
+:guilabel:`Save` the settings to implement the configuration.
+
+.. tip::
+   Manually :guilabel:`Validate` the address by navigating to the :menuselection:`Contacts app`, and
+   selecting a contact. Now that the *AvaTax* module has been configured on the database, a
+   :guilabel:`Validate` button appears directly below the :guilabel:`Address`.
+
+   Click :guilabel:`Validate`, and a pop-up window appears with a :guilabel:`Validated Address` and
+   :guilabel:`Original Address` listed. If the :guilabel:`Validated Address` is the correct mailing
+   address for tax purposes, click :guilabel:`Save Validated`.
+
+   .. image:: avatax/validate-address.png
+      :align: center
+      :alt: Validate address pop-up window in Odoo with "Save Validated" button and "Validated
+            Address" highlighted.
+
+.. warning::
+   All previously-entered addresses for contacts in the Odoo database will need to be validated
+   using the manually validate process outlined above. Addresses are not automatically validated if
+   they were entered previously. This only occurs upon tax calculation.
+
+Test connection
+~~~~~~~~~~~~~~~
+
+After entering all the above information into the *AvaTax* setup on Odoo, click :guilabel:`Test
+connection`. This ensures the :guilabel:`API ID` and :guilabel:`API KEY` are correct, and a
+connection is made between Odoo and the *AvaTax* application programming interface (API).
+
+Sync parameters
+~~~~~~~~~~~~~~~
+
+Upon finishing the configuration and settings of the *AvaTax* section, click the :guilabel:`Sync
+Parameters` button. This action synchronizes the exemption codes from *AvaTax*.
+
+.. _avatax/fiscal_positions:
+
+Fiscal position
+---------------
+
+Next, navigate to :menuselection:`Accounting app --> Configuration --> Accounting: Fiscal
+Positions`. A :guilabel:`Fiscal Position` is listed named, :guilabel:`Automatic Tax Mapping
+(AvaTax)`. Click it to open *AvaTax's* fiscal position configuration page.
+
+Here, ensure that the :guilabel:`Use AvaTax API` checkbox is ticked.
+
+Optionally, tick the checkbox next to the field labeled: :guilabel:`Detect Automatically`. Should
+this option be ticked, then, Odoo will automatically apply this :guilabel:`Fiscal Position` for
+transactions in Odoo.
+
+Enabling :guilabel:`Detect Automatically` also makes specific parameters, such as :guilabel:`VAT
+required`, :guilabel:`Foreign Tax ID`, :guilabel:`Country Group`, :guilabel:`Country`,
+:guilabel:`Federal States`, or :guilabel:`Zip Range` appear. Filling these parameters filters the
+:guilabel:`Fiscal Position` usage. Leaving them blank ensures all calculations are made using this
+:guilabel:`Fiscal Position`.
+
+.. warning::
+   Should the :guilabel:`Detect Automatically` checkbox not be ticked, each customer will need to
+   have the :guilabel:`Fiscal Position` set on their :guilabel:`Sales and Purchase` tab of the
+   contact record. To do so, navigate to :menuselection:`Sales app --> Order --> Customers`, or
+   :menuselection:`Contacts app --> Contacts`. Then, select a customer or contact to set the fiscal
+   position on.
+
+   Navigate to the :guilabel:`Sales and Purchase` tab, and down to the section labeled,
+   :guilabel:`Fiscal Position`. Set the :guilabel:`Fiscal Position` field to the fiscal position
+   for the customer.
+
+.. seealso::
+   :doc:`fiscal_positions`
+
+AvaTax accounts
+~~~~~~~~~~~~~~~
+
+Upon selecting the checkbox option for :guilabel:`Use AvaTax API` a new :guilabel:`AvaTax` tab
+appears. Click into this tab to reveal two different settings.
+
+The first setting is the :guilabel:`AvaTax Invoice Account`, while the second is, :guilabel:`AvaTax
+Refund Account`. Ensure both accounts are set for smooth end-of-year record keeping. Consult a
+certified public accountant (CPA) for specific guidance on setting both accounts.
+
+Click :guilabel:`Save` to implement the changes.
 
 Tax mapping
-===========
+-----------
 
-The Avatax integration is available on Sale Orders and Invoices with the included Avatax fiscal
+The *AvaTax* integration is available on sale orders and invoices with the included *AvaTax* fiscal
 position.
 
+.. tip::
+   Additionally, there is a :guilabel:`Tax Mapping` tab and :guilabel:`Account Mapping` tab in the
+   :guilabel:`Automatic Tax Mapping (AvaTax)` fiscal position, where mapping for products can also
+   be configured. To access :guilabel:`Fiscal Positions` navigate to :menuselection:`Accounting app
+   --> Configuration --> Accounting: Fiscal Positions`.
+
+Product category mapping
+~~~~~~~~~~~~~~~~~~~~~~~~
+
 Before using the integration, specify an :guilabel:`Avatax Category` on the product categories.
+Navigate to :menuselection:`Inventory app --> Configuration --> Product Categories`. Select the
+product category to add the :guilabel:`AvaTax Category` to. In the :guilabel:`AvaTax Category`
+field, select a category from the drop-down menu, or :guilabel:`Search More...` to open the complete
+list of options.
 
 .. image:: avatax/avatax-category.png
    :align: center
-   :alt: Specify Avatax Category on products
+   :alt: Specify AvaTax Category on products.
 
-Avatax Categories may be overridden or set on individual products as well.
+Product mapping
+~~~~~~~~~~~~~~~
+
+*AvaTax* Categories may be set on individual products, as well. To set the :guilabel:`Avatax
+Category` navigate to :menuselection:`Inventory app --> Products --> Products`. Select the product
+to add the :guilabel:`Avatax Category` to. Under the :guilabel:`General Information` tab, on the
+far-right, is a selector field labeled: :guilabel:`Avatax Category`. Finally, click the drop-down
+menu, and select a category, or :guilabel:`Search More...` to find one that is not listed.
+
+.. note::
+   If both the product, and its category, have an :guilabel:`AvaTax Category` set, the product's
+   :guilabel:`AvaTax Category` takes precedence.
 
 .. image:: avatax/override-avatax-product-category.png
    :align: center
-   :alt: Override product categories as needed
+   :alt: Override product categories as needed.
 
-.. _avatax/address-mapping:
-
-Address validation
-==================
-
-Manually validate customer addresses by clicking the :guilabel:`Validate address` link in the
-customer form view.
-
-.. image:: avatax/validate-customer-address.png
-   :align: center
-   :alt: Validate customer addresses
-
-If preferred, choose to keep the newly validated address or the original address in the wizard that
-pops up.
-
-.. image:: avatax/choose-customer-address.png
-   :align: center
-   :alt: Address validation wizard
-
-.. _avatax/tax-calculation:
-
-Tax calculation
-===============
-
-Automatically calculate taxes on Odoo quotations and invoices with Avatax by confirming the
-documents. Alternatively, calculate the taxes manually by clicking the :guilabel:`Compute taxes
-using Avatax` button while these documents are in draft mode.
-
-Use the :guilabel:`Avalara Code` field that's available on customers, quotations, and invoices to
-cross-reference data in Odoo and Avatax.
+.. important::
+   Mapping an :guilabel:`AvaTax Category` on either the *Product* or *Product Category* should be
+   completed for every *Product* or *Product Category*, depending the route that is chosen.
 
 .. seealso::
    - :doc:`fiscal_positions`
+   - :doc:`avatax/avatax_use`
+   - :doc:`avatax/avalara_portal`
+   - `US Tax Compliance: Avatax elearning video
+     <https://www.odoo.com/slides/slide/us-tax-compliance-avatax-2858?fullscreen=1>`_
+
+.. toctree::
+   :titlesonly:
+
+   avatax/avatax_use
+   avatax/avalara_portal

content/applications/finance/accounting/taxes/avatax/avalara_portal.rst

@@ -0,0 +1,259 @@
+
+.. _avatax/portal:
+
+=======================
+Avalara (Avatax) portal
+=======================
+
+Avalara's (*AvaTax*) management console offers account management options including: viewing/editing
+the transactions sent from Odoo to *AvaTax*, details on how the taxes are calculated, tax reporting,
+tax exemption management, and tax return resources.
+
+.. tip::
+   Avalara is the software developer of the tax software, *AvaTax*.
+
+To access the console, first, navigate to either Avalara's `sandbox
+<https://sandbox.admin.avalara.com/>`_ or `production <https://admin.avalara.com/>`_ environment.
+This will depend on which type of account was set in the :doc:`integration <../avatax>`. Log in to
+the management console.
+
+.. image:: avalara_portal/avalara-portal.png
+   :align: center
+   :alt: Avalara dashboard after logging into management portal.
+
+.. seealso::
+   For more information see Avalara's documentation: `Activate your Communications Customer Portal
+   account
+   <https://community.avalara.com/support/s/document-item?language=en_US&bundleId=qvv1656594440497&topicId=Activate_your_Communications_Customer_Portal_account.html&_LANG=enus>`_.
+
+.. _avalara/portal-transactions:
+
+Transactions
+============
+
+To access transactions, click in the :guilabel:`Transactions` link on the main dashboard upon
+logging into the :ref:`avatax/portal`. To manually access the *Transactions* page, while logged into
+the Avalara console, navigate to :menuselection:`Transactions --> Transactions`.
+
+.. image:: avalara_portal/avalara-transactions.png
+   :align: center
+   :alt: Avalara portal with the transactions shortcut highlighted.
+
+Edit transaction
+----------------
+
+Click into a transaction to reveal more details about the transaction. These details include
+sections on :guilabel:`Invoice detail`, :guilabel:`Additional info`, and :guilabel:`Customer info`.
+Click :icon:`fa-pencil` :guilabel:`Edit document details` to make changes to the transaction.
+
+A :guilabel:`Discount` can be added to adjust the invoice. This is especially useful in cases where
+the transaction has already synced with Avalara / *AvaTax*, and changes need to be made afterward.
+
+.. _avalara/portal-filter:
+
+Filter
+------
+
+Filter transactions on the :guilabel:`Transactions` page, by setting the :guilabel:`From` and
+:guilabel:`To` fields, and configuring other fields to filter by, including:
+
+- :guilabel:`Document Status`: any of the following options, :guilabel:`All`, :guilabel:`Voided`,
+  :guilabel:`Committed`, :guilabel:`Uncommitted`, or :guilabel:`Locked`.
+- :guilabel:`Document Code`: any of the following options, :guilabel:`Exactly match`,
+  :guilabel:`Starts with`, or :guilabel:`Contains`.
+- :guilabel:`Customer/Vendor Code`: the customer/vendor code in Odoo (e.g. `Contact18`).
+- :guilabel:`Country`: the country this tax was calculated in; this is a text field.
+- :guilabel:`Region`: the region of the country, which varies based on the :guilabel:`Country`
+  selection.
+
+Click :icon:`fa-plus` :guilabel:`Filters` to access the following filter conditions:
+
+- :guilabel:`Document Type`: any of the following selections, :guilabel:`All`, :guilabel:`Sales
+  Invoice`, :guilabel:`Purchase Invoice`, :guilabel:`Return Invoice`, :guilabel:`Inventory Transfer
+  Inbound Invoice`, :guilabel:`Inventory Transfer Outbound Invoice`, or :guilabel:`Customs
+  Invoice`.
+- :guilabel:`Import ID`: represents the import ID of the document.
+
+Sort by
+-------
+
+On the :guilabel:`Transactions` page, transactions will be listed below, according to the set
+:ref:`avalara/portal-filter`, located in the top half of the page. The following columns are
+available by default, to sort by ascending or descending order:
+
+- :guilabel:`Doc Code`: either of the following options, :guilabel:`Exactly match`,
+  :guilabel:`Starts with`, or :guilabel:`Contains`.
+- :guilabel:`Doc Status`: either of the following options, :guilabel:`All`, :guilabel:`Voided`,
+  :guilabel:`Committed`, :guilabel:`Uncommitted`, or :guilabel:`Locked`.
+- :guilabel:`Cust/Vendor Code` : this is the customer/vendor code in Odoo (e.g. Contact18).
+- :guilabel:`Region`: this is the region of the country, this will vary based on the
+  :guilabel:`Country` selection.
+- :guilabel:`Amount`: the numeric amount of the total amount on the Odoo document.
+- :guilabel:`Tax`: the numeric amount of the tax applied to the total.
+
+.. image:: avalara_portal/transactions.png
+   :align: center
+   :alt: Transactions page on the Avalara portal with the filter and sort-by options highlighted.
+
+Customize columns
+~~~~~~~~~~~~~~~~~
+
+Additional columns can be added by clicking the :icon:`fa-cog` :guilabel:`Customize columns`. On the
+resulting popover window, click the drop-down menu for the :guilabel:`column` that should be
+changed.
+
+The following columns can be added for additional transactional information:
+
+- :guilabel:`AvaTax calculated`: the amount of tax calculated by *AvaTax*.
+- :guilabel:`Country`: the country this tax was calculated in; this is a text field.
+- :guilabel:`Cust/vendor code`: the customer/vendor code in Odoo (e.g. `Contact18`).
+- :guilabel:`Currency`: the standardized abbreviation for the currency the amount total is in.
+- :guilabel:`Doc date`: the document's date of creation.
+- :guilabel:`Doc status`: any of the following options, :guilabel:`All`, :guilabel:`Voided`,
+  :guilabel:`Committed`, :guilabel:`Uncommitted`, or :guilabel:`Locked`.
+- :guilabel:`Doc type`: any of the following selections, :guilabel:`All`, :guilabel:`Sales
+  Invoice`, :guilabel:`Purchase Invoice`, :guilabel:`Return Invoice`, :guilabel:`Inventory Transfer
+  Inbound Invoice`, :guilabel:`Inventory Transfer Outbound Invoice`, or :guilabel:`Customs
+  Invoice`.
+- :guilabel:`Import ID`: represents the import ID of the document.
+- :guilabel:`Last modified`: timestamp of the last time the document was modified.
+- :guilabel:`Location code`: the location code used to calculate the tax, based on the delivery
+  address.
+- :guilabel:`PO number`: the purchase order number.
+- :guilabel:`Reference code`: the Odoo reference code (e.g. NV/2024/00003)
+- :guilabel:`Region`: the region of the country,which varies based on the :guilabel:`Country`
+  selection.
+- :guilabel:`Salesperson code`: the numeric ID of the user assigned to the sales order in Odoo.
+- :guilabel:`Tax date`: the month/day/year of the tax calculation.
+- :guilabel:`Tax override type`: where an exemption would appear, should there be none, the field
+  populates with :guilabel:`None`.
+
+To add a new column click the :icon:`fa-plus` :guilabel:`Column`.
+
+.. seealso::
+   For more information on *AvaTax* transactions, refer to this Avalara documentation: `Transactions
+   <https://community.avalara.com/support/s/document-item?language=en_US&bundleId=qvv1656594440497&topicId=transactions.html&_LANG=enus>`_.
+
+Import-export
+-------------
+
+While on the :ref:`avalara/portal-transactions`, click :icon:`fa-download` :guilabel:`Import
+transactions` or :icon:`fa-upload` :guilabel:`Export transactions` to import or export transactions.
+
+Reports
+-------
+
+To access reporting, navigate to the :menuselection:`Reports` link in the top menu of the Avalara
+management console. Next, select from one of the available reporting tabs: :guilabel:`Transactions
+reports`, :guilabel:`Liability & tax return reports`, or :guilabel:`Exemption reports`.
+
+.. tip::
+   Additionally, there is a :guilabel:`Favorites` tab and :guilabel:`Downloads` tab. The
+   :guilabel:`Favorites` tab contains any favorited report configurations for the Avalara user. The
+   :guilabel:`Downloads` tab contains a list view where the user can download the high-volume
+   transaction reports created in the last 30 days.
+
+Make a selection for the :guilabel:`Report Category`, and the :guilabel:`Report Name`, under the
+:guilabel:`Select a report` section.
+
+Next, fill out the :guilabel:`Select report details` section. These options will vary based on the
+tab selected above.
+
+Depending on the report size, the following two options are available in the section labeled,
+:guilabel:`Select the approximate number of transactions for your report`: :guilabel:`Create and
+download the report instantly` (for small reports) and :guilabel:`Create and download the report in
+the background` (for larger reports). Select one or the other depending on the volume of
+transactions in this report.
+
+Finally, under the section labeled, :guilabel:`Report preview and export` make a selection of the
+file type to download. Either a :guilabel:`.PDF` or :guilabel:`.XLS` can be chosen. Alternatively,
+the file can be previewed by selecting the :guilabel:`Preview` option.
+
+After making all the configurations, click :guilabel:`Create report` to download the report. Click
+:icon:`fa-star-o` :guilabel:`Make this report a favorite` to save the report configuration to the
+user's favorites.
+
+After the report is created, click :icon:`fa-download` :guilabel:`Download` to download the file to
+the device.
+
+.. tip::
+   Select a pre-configured report from the :guilabel:`Frequently used reports` section of the
+   reporting dashboard.
+
+   Access this list by clicking on the :guilabel:`Reports` option in the top menu of the Avalara
+   management console, and scroll to the bottom of the page.
+
+.. seealso::
+   `See Avalara's documentation: Reports in AvaTax
+   <https://community.avalara.com/support/s/document-item?language=en_US&bundleId=rjq1671176624730&topicId=Reports_in_AvaTax.html&_LANG=enus>`_.
+
+Add more jurisdictions
+======================
+
+Additional jurisdictions (tax locations) can be added in the Avalara management console. Navigate to
+either Avalara's `sandbox <https://sandbox.admin.avalara.com/>`_ or `production
+<https://admin.avalara.com/>`_ environment. This will depend on which type of account was set in the
+:doc:`integration <../avatax>`.
+
+Next, navigate to :menuselection:`Settings --> Where you collect tax`. Choose between the three
+different tabs, depending on the business need. The first tab is :guilabel:`Sales and use tax`,
+where tax can be collected for the United States. Click the :icon:`fa-plus` :guilabel:`Add to where
+you collect sales and use tax` to add another location where the company collects sales and use tax.
+
+The second option, is the :guilabel:`VAT/GST` tab where the :icon:`fa-plus` :guilabel:`Add a country
+or territory where you collect VAT/GST` can be selected to add another country or territory where
+the company collects VAT/GST.
+
+Finally, on the far-right, is the :guilabel:`Customs duty` tab, where a country can be added where
+the company collects customs duty. Simply click on the :icon:`fa-plus` :guilabel:`Add a country
+where you calculate customs duty` icon below the tab.
+
+.. image:: avalara_portal/where-you-collect-tax.png
+   :align: center
+   :alt: AvaTax management console, on the Where you collect tax page, with the add button and
+         sales and use tax tab highlighted.
+
+.. seealso::
+   `See Avalara's documentation: Add local jurisdiction taxes
+   <https://community.avalara.com/support/s/document-item?language=en_US&bundleId=bla1700809896571_bla1700809896571&topicId=nbw1698727575499.html&_LANG=enus>`_.
+
+Tax exemption certificate
+=========================
+
+Tax exemption certificates for customers can be added into the Avalara management console, so that
+*AvaTax* is aware of which customers may be exempt from paying certain taxes. To add an *exception
+certificate* navigate to :menuselection:`Exemptions --> Customer certificates`. From there, click on
+the :icon:`fa-plus` :guilabel:`Add a certificate` to configure an exemption.
+
+.. warning::
+   An Avalara subscription to Exemption Certificate Management (ECM) is required in order to attach
+   certificate images, and to be ready for an audit. For more on subscribing to this add-on, visit
+   `Avalara
+   <https://community.avalara.com/support/s/document-item?language=en_US&bundleId=hff1682048150115_hff1682048150115&topicId=fol1682356576230.html&_LANG=enus>`_.
+
+End-of-year operations
+======================
+
+Avalara's services include tax return services, for when it is time to file taxes at the end of the
+year. To access Avalara's tax services log, into the `management portal
+<https://admin.avalara.com/>`_. Then, from the main dashboard, click :guilabel:`Returns`. Avalara
+will prompt the Avalara user to log in for security purposes, and redirect the user to the *Returns*
+portal.
+
+.. image:: avalara_portal/avalara-returns.png
+   :align: center
+   :alt: Avalara portal with the returns shortcut highlighted.
+
+Click :guilabel:`Get started` to begin the tax return process. For more information, refer to this
+Avalara documentation: `About Managed Returns
+<https://community.avalara.com/support/s/document-item?language=en_US&bundleId=hps1656397152776_hps1656397152776&topicId=Learn_about_Managed_Returns.html&_LANG=enus>`_.
+
+.. tip::
+   Alternatively, click on the :menuselection:`Returns` button in the top menu of the Avalara
+   management console.
+
+.. seealso::
+   - :doc:`../avatax`
+   - :doc:`avatax_use`
+   - `US Tax Compliance: Avatax elearning video
+     <https://www.odoo.com/slides/slide/us-tax-compliance-avatax-2858?fullscreen=1>`_

content/applications/finance/accounting/taxes/avatax/avatax_use.rst

@@ -0,0 +1,166 @@
+==========
+AvaTax use
+==========
+
+AvaTax is a tax calculation software that can be integrated with Odoo in the United States and
+Canada. Once the :doc:`integration setup <../avatax>` is complete, the calculated tax is simple and
+automatic.
+
+Tax calculation
+===============
+
+Automatically calculate taxes on Odoo quotations and invoices with AvaTax by confirming the
+documents during the sales flow. Alternatively, calculate the taxes manually by clicking the
+:guilabel:`Compute Taxes` button, while these documents are in draft stage.
+
+.. tip::
+   Clicking the :guilabel:`Compute Taxes` button recalculates taxes, if any product lines are edited
+   on the invoice.
+
+.. image:: avatax_use/calculate-avatax.png
+   :align: center
+   :alt: Sales quotation with the confirm and compute taxes button highlighted.
+
+The tax calculation is triggered during the following :ref:`automatic trigger
+<avatax/automatic-triggers>` and :ref:`manual trigger <avatax/manual-triggers>` circumstances.
+
+.. _avatax/automatic-triggers:
+
+Automatic triggers
+------------------
+
+- When the sales rep sends the quote by email with :guilabel:`Send by email` button (pop-up).
+- When the customer views the online quote on the portal.
+- When a quote is confirmed and becomes a sales order.
+- When the customer views the invoice on the portal.
+- When a draft invoice is validated.
+- When the customer views the subscription in the portal.
+- When a subscription generates an invoice.
+- When the customer gets to the last screen of the eCommerce checkout.
+
+.. _avatax/manual-triggers:
+
+Manual triggers
+---------------
+
+- :guilabel:`Compute Taxes` button at the bottom of the quote.
+- :guilabel:`Compute Taxes` button at the top of the invoice.
+
+Use each of these buttons to manually re-calculate the sales tax.
+
+.. tip::
+   Use the :guilabel:`Avalara Partner Code` field that is available on customer records, quotations,
+   and invoices to cross-reference data in Odoo and AvaTax. This field is located under the
+   :menuselection:`Other info` tab of the sales order or quotation in the :guilabel:`Sales` section.
+
+   On the customer record, navigate to *Contacts app* and select a contact. Then open the
+   :guilabel:`Sales & Purchase` tab and the :guilabel:`Avalara Partner Code` under the
+   :guilabel:`Sales` section.
+
+.. important::
+   The :guilabel:`Automatic Tax Mapping (AvaTax)` fiscal position is also applied on those Odoo
+   documents, like subscriptions.
+
+.. seealso::
+   - :doc:`../fiscal_positions`
+
+AvaTax synchronization
+======================
+
+Synchronization occurs with AvaTax, when the *invoice* is created in Odoo. This means the sales tax
+is recorded with Avalara (AvaTax software developer).
+
+To do so, navigate to :menuselection:`Sales app --> Orders --> Quotations`. Select a quotation from
+the list.
+
+After confirming a quotation and validating the delivery, click :guilabel:`Create Invoice`. Indicate
+whether it is a :guilabel:`Regular invoice`, :guilabel:`Down payment (percentage)`, or
+:guilabel:`Down payment (fixed amount)`.
+
+Then click :guilabel:`Create and view invoice`. The recorded taxes can be seen in the
+:guilabel:`Journal Items` tab of the invoice. There will be different taxes depending on the
+location of the :guilabel:`Delivery Address`.
+
+.. image:: avatax_use/journal-items.png
+   :align: center
+   :alt: Journal items highlighted on a invoice in Odoo.
+
+Finally, press the :guilabel:`Confirm` button to complete the invoice and synchronize with the
+AvaTax portal.
+
+.. warning::
+   An invoice cannot be :guilabel:`Reset to draft` because this causes de-synchronization with the
+   AvaTax Portal. Instead, click :guilabel:`Add credit note` and state: `Sync with AvaTax Portal`.
+   See this documentation: :doc:`../../../accounting/customer_invoices/credit_notes`.
+
+Fixed price discounts
+=====================
+
+Add a fixed price discount to a valuable customer, by clicking :guilabel:`Add a line` on the
+customer's invoice. Add the product discount, and set the :guilabel:`Price` to either a positive or
+negative value. To recalculate the taxes, click :guilabel:`Compute Taxes`.
+
+.. tip::
+   Tax calculation can even be done on negative subtotals and credit notes.
+
+Logging
+=======
+
+It is possible to log Avalara/*AvaTax* actions in Odoo for further analysis, or verification of
+functionality. Logging is accessible through the *AvaTax* settings.
+
+To start logging *AvaTax* actions, first, navigate to the :menuselection:`Accounting app -->
+Configuration --> Settings`.
+
+Then, in the :guilabel:`Taxes` section, under the :guilabel:`AvaTax` settings, click
+:guilabel:`Start logging for 30 minutes`.
+
+Upon starting the log process, Odoo will log all Avalara/*AvaTax* actions performed in the database.
+
+To view the logs, click on :guilabel:`Show logs` to the right of the :guilabel:`Start logging for 30
+minutes`. This reveals a detailed list of Avalara/*AvaTax* actions. This list is sortable by the
+following columns:
+
+- :guilabel:`Created on`: timestamp of the *AvaTax* calculation.
+- :guilabel:`Created by`: numeric value of the user in the database.
+- :guilabel:`Database name`: name of the database.
+- :guilabel:`Type`: two values can be chosen for this field, :guilabel:`Server` or
+  :guilabel:`Client`.
+- :guilabel:`Name`: Avalara service name. In this case, it will be *AvaTax*.
+- :guilabel:`Level`: by default, this will be `INFO`.
+- :guilabel:`Path`: indicates the path taken to make the calculation.
+- :guilabel:`Line`: indicates the line the calculation is made on.
+- :guilabel:`Function`: indicates the calculation taken on the line.
+
+.. image:: avatax_use/logging.png
+   :align: center
+   :alt: Avalara logging page with top row of list highlighted.
+
+Click into the log line to reveal another field, called :guilabel:`Message`.
+
+This field populates a raw transcription of the transaction, which involves the creation (or
+adjustment) of a sales invoice using the Avalara *AvaTax* API.
+
+The transaction includes details, such as addresses for shipping from and to, line items describing
+the products or services, tax codes, tax amounts, and other relevant information.
+
+The :guilabel:`Message` contains the calculated taxes for different jurisdictions and confirms the
+creation (or adjustment) of the transaction.
+
+.. tip::
+   Custom fields can be made using Odoo *Studio*. Click the :icon:`fa-ellipsis-v`
+   :guilabel:`(ellipsis)` menu to the far-right of the header row. Then click :icon:`fa-plus`
+   :guilabel:`Add custom field`. This action opens Odoo *Studio*.
+
+.. important::
+   Odoo *Studio* requires a *custom* pricing plan. Consult the database's customer success manager
+   for more information on switching plans. Or to see if Odoo *Studio* is included in the database's
+   current pricing plan. See this documentation: :doc:`../../../../studio`.
+
+.. seealso::
+   - :doc:`../avatax`
+   - :doc:`avalara_portal`
+   - `US Tax Compliance: Avatax elearning video
+     <https://www.odoo.com/slides/slide/us-tax-compliance-avatax-2858?fullscreen=1>`_
+   - :doc:`../fiscal_positions`
+

content/applications/finance/fiscal_localizations/australia.rst

@@ -903,6 +903,9 @@ Configuration
         :alt: The Employment Hero "Business ID" number is in the URL
 
    - You can choose any Odoo journal to post the payslip entries.
+#. Configure the tax by going to :menuselection:`Accounting --> Configuration --> Taxes`. Create the
+   necessary taxes for the Employment Hero payslip entries. Fill in the tax code from
+   **Employment Hero** in the :guilabel:`Matching Employment Hero Tax` field.
 
 How does the API work?
 ----------------------

content/applications/finance/fiscal_localizations/brazil.rst

@@ -10,12 +10,12 @@ Introduction
 ============
 
 With the Brazilian localization, sales taxes can be automatically computed and electronic invoices
-(NF-e) for goods can be sent using AvaTax (Avalara) through |API| calls. Moreover, taxes for
-services can be configured.
+for goods (NF-e) and services (NFS-e) can be sent using AvaTax (Avalara) through |API| calls.
+Moreover, taxes for services can be configured.
 
-For the goods tax computation and electronic invoicing process, you need to configure the
-:ref:`contacts <brazil/contacts>`, :ref:`company <brazil/company>`, :ref:`products
-<brazil/products>`, and :ref:`create an account in Avatax <brazil/avatax-account>` need to be
+For the goods and services tax computation and electronic invoicing process, you need to configure
+the :ref:`contacts <brazil/contacts>`, :ref:`company <brazil/company>`, :ref:`products
+<brazil/products>`, and :ref:`create an account in AvaTax <brazil/avatax-account>` which needs to be
 configured in the general settings.
 
 For the services taxes, you can create and configure them from Odoo directly without computing them
@@ -27,9 +27,36 @@ needed.
 Configuration
 =============
 
-Install the :guilabel:`🇧🇷 Brazil` :ref:`fiscal localization package
-<fiscal_localizations/packages>` to get all the default accounting features of the Brazilian
-localization, following the :abbr:`IFRS (International Financial Reporting Standards)` rules.
+Modules installation
+--------------------
+
+:ref:`Install <general/install>` the following modules to get all the features of the Brazilian
+localization:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 25 50
+
+   * - Name
+     - Technical name
+     - Description
+   * - :guilabel:`Brazilian - Accounting`
+     - `l10n_br`
+     - Default :ref:`fiscal localization package <fiscal_localizations/packages>`, which represents
+       having the Generic Brazilian chart of accounts and Taxes, together with document types and
+       identification types.
+   * - :guilabel:`Brazil - Accounting Reports`
+     - `l10n_br_reports`
+     - Accounting reports for Brazil.
+   * - :guilabel:`AvaTax Brazil` & :guilabel:`AvaTax Brazil for Services`
+     - `l10n_br_avatax` & `l10n_br_avatax_services`
+     - Goods and Services tax computation through Avalara.
+   * - :guilabel:`Brazilian Accounting EDI` & :guilabel:`Brazilian Accounting EDI for services`
+     - `l10n_br_edi` & `l10n_br_edi_services`
+     - Provides electronic invoicing for goods and services for Brazil through AvaTax.
+   * - :guilabel:`Brazil Pix QR codes`
+     - `l10n_br_pix`
+     - Implements Pix QR codes for Brazil.
 
 .. _brazil/company:
 
@@ -42,40 +69,53 @@ given to your company.
 #. Select the :guilabel:`Company` option at the top of the page. Then, configure the following
    fields:
 
-   - :guilabel:`Name`.
-   - :guilabel:`Address` (add :guilabel:`City`, :guilabel:`State`, :guilabel:`Zip Code`,
-     :guilabel:`Country`).
+   - :guilabel:`Name`
+   - :guilabel:`Address`: add :guilabel:`City`, :guilabel:`State`, :guilabel:`Zip Code`,
+     :guilabel:`Country`
 
      - In the :guilabel:`Street` field, enter the street name, number, and any additional address
        information.
      - In the :guilabel:`Street 2` field, enter the neighborhood.
 
-   - :guilabel:`Identification Number` (:guilabel:`CNPJ`, :guilabel:`CPF`).
-   - :guilabel:`Tax ID` (associated with the identification type).
-   - :guilabel:`IE` (State registration).
-   - :guilabel:`IM` (Municipal registration).
-   - :guilabel:`SUFRAMA code` (Superintendence of the Manaus Free Trade Zone - add if applicable).
-   - :guilabel:`Phone`.
-   - :guilabel:`Email`.
+   - :guilabel:`Identification Number`: :guilabel:`CNPJ` or :guilabel:`CPF`
+   - :guilabel:`Tax ID`: associated with the identification type
+   - :guilabel:`IE`: State registration
+   - :guilabel:`IM`: Municipal registration
+   - :guilabel:`SUFRAMA code`: Superintendence of the Manaus Free Trade Zone - add if applicable
+   - :guilabel:`Phone`
+   - :guilabel:`Email`
 
    .. image:: brazil/contact-configuration.png
       :alt: Company configuration.
 
 #. Configure the :guilabel:`Fiscal Information` within the :guilabel:`Sales and Purchase` tab:
 
-   - Add the :guilabel:`Fiscal Position` for :ref:`Avatax Brazil <brazil/fiscal-positions>`.
-   - :guilabel:`Tax Regime` (Federal Tax Regime).
-   - :guilabel:`ICMS Taxpayer Type` (indicates ICMS regime, Exempt status, or Non-Taxpayer).
-   - :guilabel:`Main Activity Sector`.
+   - Add the :guilabel:`Fiscal Position` for :ref:`AvaTax Brazil <brazil/fiscal-positions>`.
+   - :guilabel:`Tax Regime`: Federal Tax Regime
+   - :guilabel:`ICMS Taxpayer Type`: indicates :guilabel:`ICMS regime`, :guilabel:`Exempt status`,
+     or :guilabel:`Non-Taxpayer`
+   - :guilabel:`Main Activity Sector`
 
    .. image:: brazil/contact-fiscal-configuration.png
       :alt: Company fiscal configuration.
 
-#. Finally, upload a company logo and save the contact
+#. Configure the following extra :guilabel:`Fiscal Information` if you are going to issue NFS-e:
+
+   - Add the :guilabel:`Fiscal Position` for :ref:`AvaTax Brazil <brazil/fiscal-positions>`.
+   - :guilabel:`COFINS Details`: :guilabel:`Taxable, Not Taxable, Taxable with rate 0%, Exempt,
+     Suspended`
+   - :guilabel:`PIS Details` :guilabel:`Taxable, Not Taxable, Taxable with rate 0%, Exempt,
+     Suspended`
+   - :guilabel:`CSLL Taxable` If the company is subject to CSLL or not
+
+   .. image:: brazil/contact-fiscal-configuration-nfse.png
+      :alt: Company fiscal configuration for NFSe.
+
+#. Finally, upload a company logo and save the contact.
 
 .. note::
    If you are a simplified regime, you need to configure the ICMS rate under
-   :menuselection:`Accounting --> Configuration --> Settings --> Taxes --> Avatax Brazil`.
+   :menuselection:`Accounting --> Configuration --> Settings --> Taxes --> AvaTax Brazil`.
 
 .. _brazil/avatax-account:
 
@@ -88,11 +128,14 @@ transaction information to retrieve the correct tax to be used and process the e
 with the government.
 
 Using this integration requires :doc:`In-App-Purchases (IAPs) <../../essentials/in_app_purchase>` to
-compute the taxes and to send the electronic invoices. Whenever you compute taxes, an |API| call is
-made using credits from your |IAP| credits balance.
+compute the taxes and to send the electronic invoices. Whenever you compute taxes, send an
+electronic document (NF-e, NFS-e, etc), or perform any electronic flow (NF-e Cancellation,
+Correction letter, Invalidate invoice number range), an API call is made using credits from your
+`IAP credits balance <https://iap.odoo.com/iap/in-app-services/819>`_.
 
 .. note::
-   Odoo is a certified partner of Avalara Brazil.
+   - Odoo is a certified partner of Avalara Brazil.
+   - You can `buy IAP credit on odoo.com <https://iap.odoo.com/iap/in-app-services/819>`_.
 
 Credential configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -100,19 +143,31 @@ Credential configuration
 To activate AvaTax in Odoo, you need to create an account. To do so, go to
 :menuselection:`Accounting --> Configuration --> Settings --> Taxes`, and in the :guilabel:`AvaTax
 Brazil` section, add the administration email address to be used for the AvaTax portal in the
-:guilabel:`Avatax Portal Email`, and then click on :guilabel:`Create account`.
+:guilabel:`AvaTax Portal Email`, and then click on :guilabel:`Create account`.
 
 .. warning::
-   When **testing** an :guilabel:`Avatax Portal Email` integration in a testing or sandbox database,
-   use an alternate email address. It is **not** possible to re-use the same email address on the
-   production database.
+   When **testing** or **creating a production** :guilabel:`AvaTax Portal Email` integration in a
+   sandbox or production database, use a real email address, as it is needed to log in to the
+   Avalara Portal and set up the certificates, whether you want to test or use it on production.
+
+   There are two different Avalara Portals, one for testing and one for production:
+
+   - Sandbox: https://portal.sandbox.avalarabrasil.com.br/
+   - Production: https://portal.avalarabrasil.com.br/
+
+   When you create the account from Odoo, be sure to select the right environment. Moreover, the
+   email used to open the account cannot be used to open another account. Save your :guilabel:`API
+   ID` and :guilabel:`API Key` when you create the account from Odoo.
+
+   .. image:: brazil/transfer-api-credentials.png
+      :alt: Transfer API Credentials.
 
 After you create the account from Odoo, you need to go to the Avalara Portal to set up your
 password:
 
 #. Access the `Avalara portal <https://portal.avalarabrasil.com.br/Login>`_.
 #. Click on :guilabel:`Meu primeiro acesso`.
-#. Add the email address you used in Odoo to create the Avalara/Avatax account, and then click
+#. Add the email address you used in Odoo to create the Avalara/AvaTax account, and then click
    :guilabel:`Solicitar Senha`.
 #. You will receive an email with a token and a link to create your password. Click on this link and
    copy-paste the token to allocate your desired password.
@@ -123,7 +178,7 @@ password:
    invoice service, you **must** access the AvaTax portal and upload your certificate there.
 
 .. image:: brazil/avatax-account-configuration.png
-   :alt: Avatax account configuration.
+   :alt: AvaTax account configuration.
 
 .. note::
    You can transfer |API| credentials. Use this only when you have already created an account in
@@ -139,6 +194,13 @@ The certificate will be synchronized with Odoo, as long as the external identifi
 AvaTax portal matches - without special characters - with the CNPJ number, and the identification
 number (CNPJ) in Odoo matches with the CNPJ in AvaTax.
 
+.. important::
+   To issue NFS-e, some cities require that you link the certificate within the City Portal system
+   before issuing NFS-e from Odoo.
+
+   If you receive an error message from the city that says :guilabel:`Your certificate is not linked
+   to the user`, that means this process needs to be done in the city portal.
+
 Configure master data
 ---------------------
 
@@ -187,15 +249,8 @@ be manually added and configured, as the rate may differ depending on the city w
 offering the service.
 
 .. important::
-   Taxes attached to services are not computed by AvaTax. Only goods taxes are computed.
-
-When configuring a tax used for a service that is included in the final price (when the tax is not
-added or subtracted on top of the product price), set the :guilabel:`Tax Computation` to
-:guilabel:`Percentage of Price Tax Included`, and, on the :guilabel:`Advanced Options` tab, check
-the :guilabel:`Included in Price` option.
-
-.. image:: brazil/tax-configuration.png
-   :alt: Tax configuration.
+   If you decide to do service taxes manually, you won't be able to issue an NFS-e. To
+   electronically send an NFS-e, you need to compute taxes using Avalara.
 
 .. warning::
    Do not delete taxes, as they are used for the AvaTax tax computation. If deleted, Odoo creates
@@ -212,14 +267,17 @@ Products
 ~~~~~~~~
 
 To use the AvaTax integration on sale orders and invoices, first specify the following information
-on the product:
+on the product depending on its intended use:
 
-- :guilabel:`CEST Code` (Code for products subject to ICMS tax substitution).
-- :guilabel:`Mercosul NCM Code` (Mercosur Common Nomenclature Product Code).
-- :guilabel:`Source of Origin` (Indicates the origin of the product, which can be foreign or
-  domestic, among other possible options depending on the specific use case).
-- :guilabel:`SPED Fiscal Product Type` (Fiscal product type according to SPED list table).
-- :guilabel:`Purpose of Use` (Specify the intended purpose of use for this product).
+E-Invoice for goods (NF-e)
+**************************
+
+- :guilabel:`CEST Code`: Code for products subject to ICMS tax substitution
+- :guilabel:`Mercosul NCM Code`: Mercosur Common Nomenclature Product Code
+- :guilabel:`Source of Origin`: Indicates the origin of the product, which can be foreign or
+  domestic, among other possible options depending on the specific use case
+- :guilabel:`SPED Fiscal Product Type`: Fiscal product type according to SPED list table
+- :guilabel:`Purpose of Use`: Specify the intended purpose of use for this product
 
 .. image:: brazil/product-configuration.png
    :alt: Product configuration.
@@ -231,6 +289,16 @@ on the product:
    :guilabel:`Product Type` `Service`, :guilabel:`Transportation Cost Type` `Insurance`, `Freight`,
    or `Other Costs`).
 
+E-Invoice for services (NFS-e)
+******************************
+
+- :guilabel:`Mercosul NCM Code`: Mercosur Common Nomenclature Product Code
+- :guilabel:`Purpose of Use`: Specify the intended purpose of use for this product
+- :guilabel:`Service Code Origin`: City Service Code where the provider is registered
+- :guilabel:`Service Codes`: City Service Code where the service will be provided, if no
+  code is added, the Origin City Code will be used
+- :guilabel:`Labor Assignment`: Defines if your services includes labor
+
 .. _brazil/contacts:
 
 Contacts
@@ -242,23 +310,23 @@ Before using the integration, specify the following information on the contact:
 
    - Select the :guilabel:`Company` option for a contact with a tax ID (CNPJ), or check
      :guilabel:`Individual` for a contact with a CPF.
-   - :guilabel:`Name`.
-   - :guilabel:`Address` (add :guilabel:`City`, :guilabel:`State`, :guilabel:`Zip Code`,
-     :guilabel:`Country`).
+   - :guilabel:`Name`
+   - :guilabel:`Address`: add :guilabel:`City`, :guilabel:`State`, :guilabel:`Zip Code`,
+     :guilabel:`Country`
 
      - In the :guilabel:`Street` field, enter the street, number, and any extra address information.
      - In the :guilabel:`Street 2` field, enter the neighborhood.
 
-   - :guilabel:`Identification Number` (:guilabel:`CNPJ`, :guilabel:`CPF`).
-   - :guilabel:`Tax ID` (associated with the identification type).
-   - :guilabel:`IE`: state tax identification number.
-   - :guilabel:`IM`: municipal tax identification number.
-   - :guilabel:`SUFRAMA code`: SUFRAMA registration number.
-   - :guilabel:`Phone`.
-   - :guilabel:`Email`.
+   - :guilabel:`Identification Number`: :guilabel:`CNPJ` or :guilabel:`CPF`
+   - :guilabel:`Tax ID`: associated with the identification type
+   - :guilabel:`IE`: state tax identification number
+   - :guilabel:`IM`: municipal tax identification number
+   - :guilabel:`SUFRAMA code`: SUFRAMA registration number
+   - :guilabel:`Phone`
+   - :guilabel:`Email`
 
    .. image:: brazil/contact-configuration.png
-     :alt: Contact configuration.
+      :alt: Contact configuration.
 
    .. note::
       The :guilabel:`CPF`, :guilabel:`IE`, :guilabel:`IM`, and :guilabel:`SUFRAMA code` fields are
@@ -269,13 +337,25 @@ Before using the integration, specify the following information on the contact:
    - :guilabel:`Fiscal Position`: add the AvaTax fiscal position to automatically compute taxes on
      sale orders and invoices automatically
    - :guilabel:`Tax Regime`: federal tax regime
-   - :guilabel:`ICMS Taxpayer Type`: taxpayer type determines if the contact is within the ICMS
-     regime, if it is exempt, or if it is a non-taxpayer
+   - :guilabel:`ICMS Taxpayer Type`: taxpayer type determines if the contact is within the
+     :guilabel:`ICMS regime`, :guilabel:`Exempt status`, or :guilabel:`Non-taxpayer`
    - :guilabel:`Main Activity Sector`: list of main activity sectors of the contact
 
    .. image:: brazil/contact-fiscal-configuration.png
       :alt: Contact fiscal configuration.
 
+#. Configure the following extra :guilabel:`Fiscal Information` if you are going to issue NFS-e:
+
+   - Add the :guilabel:`Fiscal Position` for :ref:`AvaTax Brazil <brazil/fiscal-positions>`
+   - :guilabel:`COFINS Details`: :guilabel:`Taxable, Not Taxable, Taxable with rate 0%, Exempt,
+     Suspended`
+   - :guilabel:`PIS Details`: :guilabel:`Taxable, Not Taxable, Taxable with rate 0%, Exempt,
+     Suspended`
+   - :guilabel:`CSLL Taxable`: If the company is subject to CSLL or not
+
+   .. image:: brazil/contact-fiscal-configuration-nfse.png
+      :alt: Contact fiscal configuration for NFSe.
+
 .. _brazil/fiscal-positions:
 
 Fiscal positions
@@ -285,8 +365,8 @@ To compute taxes and send electronic invoices on sale orders and invoices, both
 :guilabel:`Detect Automatically` and the :guilabel:`Use AvaTax API` options need to be enabled in
 the :guilabel:`Fiscal Position`.
 
-The :guilabel:`Fiscal Position` can be configured on the contact or selected when creating a sales
-order or an invoice.
+The :guilabel:`Fiscal Position` can be configured on the :ref:`contact <brazil/contacts>` or
+selected when creating a sales order or an invoice.
 
 .. image:: brazil/fiscal-position-configuration.png
    :alt: Fiscal position configuration
@@ -295,8 +375,8 @@ Workflows
 =========
 
 This section provides an overview of the actions that trigger `API calls
-<https://en.wikipedia.org/wiki/API>`_ for tax computation, and how to send an electronic invoice for
-goods (NF-e) for government validation.
+<https://en.wikipedia.org/wiki/API>`_ for tax computation, along with instructions on how to send
+electronic invoices for goods (NF-e) and services (NFS-e) for government validation.
 
 .. warning::
    Please note that each |API| call incurs a cost. Be mindful of the actions that trigger these
@@ -314,7 +394,7 @@ any of the following ways:
 - **Quotation confirmation**
     Confirm a quotation into a sales order.
 - **Manual trigger**
-    Click on :guilabel:`Compute Taxes Using Avatax`.
+    Click on :guilabel:`Compute Taxes Using AvaTax`.
 - **Preview**
     Click on the :guilabel:`Preview` button.
 - **Email a quotation / sales order**
@@ -326,8 +406,8 @@ any of the following ways:
 Tax calculations on invoices
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Trigger an |API| call to calculate taxes on a customer invoice automatically with AvaTax any of the
-following ways:
+Trigger an |API| call to calculate taxes on a customer invoice automatically with AvaTax in any of
+the following ways:
 
 - **Manual trigger**
     Click on :guilabel:`Compute Taxes Using AvaTax`.
@@ -351,21 +431,21 @@ Electronic documents
 Customer invoices
 ~~~~~~~~~~~~~~~~~
 
-To process an electronic invoice for goods (NF-e), the invoice needs to be confirmed and taxes need
-to be computed by Avalara. Once that step is done, click on the :guilabel:`Send \& Print` button in
-the upper left corner, and a pop-up will appear. Then click on :guilabel:`Process e-invoice` and any
-of the other options - :guilabel:`Download` or :guilabel:`Email`. Finally, click on :guilabel:`Send
-\& Print` to process the invoice against the government.
+To process an electronic invoice for goods (NF-e) or services (NFS-e), the invoice needs to be
+confirmed and taxes need to be computed by Avalara. Once that step is done, click on the
+:guilabel:`Send & Print` button in the upper left corner. In the pop-up that appears, click on
+:guilabel:`Process e-invoice` and any of the other options - :guilabel:`Download` or
+:guilabel:`Email`. Finally, click on :guilabel:`Send & Print` to process the invoice with the
+government.
 
-Before sending the electronic invoice for goods (NF-e) some fields need to be filled out on the
-invoice:
+Before sending the electronic invoice for goods (NF-e) or services (NFS-e), some fields need to be
+filled out on the invoice:
 
-- :guilabel:`Customer` with all the customer information
-- :guilabel:`Payment Method: Brazil` (how the invoice is planned to be paid)
+- :guilabel:`Customer`, with all the customer information
+- :guilabel:`Payment Method: Brazil`: how the invoice is planned to be paid
 - :guilabel:`Fiscal Position` set as the :guilabel:`Automatic Tax Mapping (Avalara Brazil)`
-- :guilabel:`Document Type` set as :guilabel:`(55) Electronic Invoice (NF-e)`. This is the only
-   electronic document supported at the moment. Non-electronic invoices can be registered, and other
-   document types can be activated if needed
+- :guilabel:`Document Type` set as :guilabel:`(55) Electronic Invoice (NF-e)` or :guilabel:`(SE)
+  Electronic Service Invoice (NFS-e)`
 
 There are some other optional fields that depend on the nature of the transaction. These fields are
 not required, so no errors will appear from the government if these optional fields are not
@@ -392,6 +472,9 @@ Credit notes
 If a sales return needs to be registered, then a credit note can be created in Odoo to be sent to
 the government for validation.
 
+.. note::
+   Credit notes are only available for electronic invoices for goods (NF-e).
+
 .. seealso::
    :ref:`Issue a credit note <accounting/issue-credit-note>`
 
@@ -401,7 +484,9 @@ Debit Notes
 If additional information needs to be included, or values need to be corrected that were not
 accurately provided in the original invoice, a debit note can be issued.
 
-.. important::
+.. note::
+   Debit notes are only available for electronic invoices for goods (NF-e).
+
    Only the products included in the original invoice can be part of the debit note. While changes
    can be made to the product's unit price or quantity, products **cannot** be added to the debit
    note. The purpose of this document is only to declare the amount that you want to add to the
@@ -415,22 +500,37 @@ Invoice cancellation
 
 It is possible to cancel an electronic invoice that was validated by the government.
 
-.. important::
+.. note::
    Check whether the electronic invoice is still within the cancellation deadline, which may vary
    according to the legislation of each state.
 
-This can be done in Odoo by clicking :guilabel:`Request Cancel` and adding a cancellation
-:guilabel:`Reason` on the pop-up that appears. If you want to send this cancellation reason to the
-customer via email, activate the :guilabel:`E-mail` checkbox.
+E-invoices for goods (NF-e)
+***************************
+
+Cancel an e-invoice for goods (NF-e) in Odoo by clicking :guilabel:`Request Cancel` and adding a
+cancellation :guilabel:`Reason` on the pop-up that appears. If you want to send this cancellation
+reason to the customer via email, activate the :guilabel:`E-mail` checkbox.
 
 .. image:: brazil/invoice-cancellation.png
    :alt: Invoice cancellation reason in Odoo.
 
+.. note::
+   This is an electronic cancellation, which means that Odoo will send a request to the government
+   to cancel the NF-e, and it will then consume one |IAP| credit, as an |API| call occurs.
+
+E-invoices for services (NFS-e)
+*******************************
+
+Cancel an e-invoice for services (NFS-e) in Odoo by clicking :guilabel:`Request Cancel`. In this
+case, there is no electronic cancellation process, as not every city has this service available. The
+user needs to manually cancel this NFS-e on the city portal. Once that step is completed, they can
+request the cancellation in Odoo, which will cancel the invoice.
+
 Correction letter
 ~~~~~~~~~~~~~~~~~
 
-A correction letter can be created and linked to an electronic invoice that was validated by the
-government.
+A correction letter can be created and linked to an electronic invoice for goods (NF-e) that was
+validated by the government.
 
 This can be done in Odoo by clicking :guilabel:`Correction Letter` and adding a correction
 :guilabel:`Reason` on the pop-up that appears. To send this correction reason to a customer via
@@ -439,6 +539,9 @@ email, activate the :guilabel:`E-mail` checkbox.
 .. image:: brazil/correction-letter.png
    :alt: Correction letter reason in Odoo.
 
+.. note::
+   Correction letters are only available for electronic invoices for goods (NF-e).
+
 Invalidate invoice number range
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -455,6 +558,10 @@ journal, and click the :menuselection:`⚙️ (gear) icon --> Invalidate Number
 .. image:: brazil/range-number-invalidation-wizard.png
    :alt: Number range invalidation wizard in Odoo.
 
+.. note::
+   Invalidate invoice number range documents are only available for electronic invoices for goods
+   (NF-e).
+
 .. note::
    The log of the canceled numbers along with the XML file are recorded in the chatter of the
    journal.
@@ -468,8 +575,8 @@ is recorded on the :ref:`customer invoices <brazil/electronic-documents>`.
 
 These Brazilian specific fields are:
 
-- :guilabel:`Payment Method: Brazil` (how the invoice is planned to be paid).
-- :guilabel:`Document Type` used by your vendor.
-- :guilabel:`Document Number` (the invoice number from your supplier).
-- :guilabel:`Freight Model` (how goods are planned to be transported - domestic).
-- :guilabel:`Transporter Brazil` (who is doing the transportation).
+- :guilabel:`Payment Method: Brazil`: how the invoice is planned to be paid
+- :guilabel:`Document Type`: used by your vendor
+- :guilabel:`Document Number`: the invoice number from your supplier
+- :guilabel:`Freight Model`: **NF-e specific** how goods are planned to be transported - domestic
+- :guilabel:`Transporter Brazil`: **NF-e specific** who is doing the transportation.

content/applications/finance/fiscal_localizations/hong_kong.rst

@@ -2,8 +2,35 @@
 Hong Kong
 =========
 
-Add FPS QR codes to invoices
-============================
+Configuration
+=============
+
+:ref:`Install <general/install>` the following modules to get the latest features of the Hong Kong
+localization:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Technical name
+     - Description
+   * - :guilabel:`Hong Kong - Accounting`
+     - `l10n_hk`
+     - The base module to manage chart of accounting and localization for Hong Kong.
+   * - :guilabel:`Hong Kong - Payroll`
+     - `l10n_hk_hr_payroll`
+     - Enables :ref:`payroll <hong_kong/payroll>` specific localization features for Odoo *Payroll*
+       app. This module also installs :guilabel:`Hong Kong - Payroll with Accounting` and
+       :guilabel:`Documents - Hong Kong Payroll`.
+   * - :guilabel:`Hong Kong - Payroll with Accounting`
+     - `l10n_hk_hr_payroll_account`
+     - Installs the link between Hong Kong payroll and accounting.
+   * - :guilabel:`Documents - Hong Kong Payroll`
+     - `documents_l10n_hk_hr_payroll`
+     - Integrates employee ir56 forms in the Odoo *Documents* app.
+
+FPS QR codes on invoices
+========================
 
 :abbr:`FPS (Faster Payment System)` is a payment service platform that allows customers to make
 instant domestic payments to individuals and merchants in Hong Kong dollars or Renminbi via online
@@ -12,23 +39,26 @@ and mobile banking.
 Activate QR codes
 -----------------
 
-Go to :menuselection:`Accounting --> Configuration --> Settings`. Under the :guilabel:`Customer
-Payments` section, activate the :guilabel:`QR Codes` feature.
+Go to :menuselection:`Accounting app --> Configuration --> Settings`. Under the :guilabel:`Customer
+Payments` section, tick the checkbox beside the :guilabel:`QR Codes` feature. Then, click
+:guilabel:`Save`.
 
 FPS bank account configuration
 ------------------------------
 
-Go to :menuselection:`Contacts --> Configuration --> Bank Accounts` and select the bank account for
-which you want to activate FPS. Set the :guilabel:`Proxy Type` and fill in the :guilabel:`Proxy
-Value` field depending on the type you chose.
+Go to :menuselection:`Contacts app --> Configuration --> Bank Accounts section --> Bank Accounts`.
+Then select the bank account for FPS activation. Proceed to set the :guilabel:`Proxy Type` and fill
+in the :guilabel:`Proxy Value` field, depending on the type chosen.
 
-.. important::
-   - The account holder's country must be set to Hong Kong on its contact form.
-   - You could also include the invoice number in the QR code by checking the :guilabel:`Include
-     Reference` checkbox.
+Remember to include the invoice number in the QR code, by ticking the :guilabel:`Include Reference`
+checkbox.
 
 .. image:: hong_kong/hk-fps-bank-setting.png
-   :alt: FPS bank account configuration
+   :align: center
+   :alt: FPS bank account configuration.
+
+.. important::
+   The account holder's country **must** be set to `Hong Kong` on their contact form.
 
 .. seealso::
    :doc:`../accounting/bank`
@@ -36,20 +66,475 @@ Value` field depending on the type you chose.
 Bank journal configuration
 --------------------------
 
-Go to :menuselection:`Accounting --> Configuration --> Journals`, open the bank journal, then fill
-out the :guilabel:`Account Number` and :guilabel:`Bank` under the :guilabel:`Journal Entries` tab.
+Go to :menuselection:`Accounting app --> Configuration --> Journals` and open the bank journal.
+Then, fill out the :guilabel:`Account Number` and :guilabel:`Bank` fields, located in the
+:guilabel:`Journal Entries` tab.
 
 .. image:: hong_kong/hk-bank-account-journal-setting.png
-   :alt: Bank Account's journal configuration
+   :align: center
+   :alt: Bank Account's journal configuration.
 
 Issue invoices with FPS QR codes
 --------------------------------
 
 When creating a new invoice, open the :guilabel:`Other Info` tab and set the :guilabel:`Payment
-QR-code` option to *EMV Merchant-Presented QR-code*.
+QR-code` option to :guilabel:`EMV Merchant-Presented QR-code`.
 
 .. image:: hong_kong/hk-qr-code-invoice-setting.png
-   :alt: Select EMV Merchant-Presented QR-code option
+   :align: center
+   :alt: Select EMV Merchant-Presented QR-code option.
 
-Ensure that the :guilabel:`Recipient Bank` is the one you configured, as Odoo uses this field to
-generate the FPS QR code.
+Ensure that the :guilabel:`Recipient Bank` is configured, as Odoo uses this field to generate the
+FPS QR code.
+
+.. _hong_kong/payroll:
+
+Payroll
+=======
+
+.. important::
+   Ensure the :guilabel:`Hong Kong - Payroll` (`l10n_hk_hr_payroll`) module is installed before
+   proceeding.
+
+Create employees
+----------------
+
+Go to the :menuselection:`Employees` app and click :guilabel:`New`. Then, configure the following
+fields:
+
+- Under the :guilabel:`Work Information` tab
+
+  - :guilabel:`Working Hours`: :guilabel:`HK Standard 40 hours/week` option **must** be selected.
+
+- Under the :guilabel:`Private Information` tab
+
+  - :guilabel:`Surname, Given Name, Name in Chinese`: name of the employee.
+  - :guilabel:`Private Address`: address of the employee.
+  - :guilabel:`Bank Account Number`: employee's bank account number.
+  - :guilabel:`Current Rental`: employee's rental records (if rental allowance is applicable).
+  - :guilabel:`Autopay Type`: :guilabel:`BBAN`, :guilabel:`SVID`, :guilabel:`EMAL`, etc.
+  - :guilabel:`Autopay Reference`: autopay reference number.
+  - :guilabel:`Identification No`: HKID of the employee.
+  - :guilabel:`Gender`: gender of the employee.
+
+  .. important::
+     For the :guilabel:`Bank Account Number`, this account should be set as :guilabel:`Trusted`
+     before further processing.
+
+     To achieve this, click on the right-arrow button next to :guilabel:`Bank Account Number` field.
+     Set the :guilabel:`Send Money` to :guilabel:`Trusted` by clicking on the toggle.
+
+  .. note::
+     To populate the :guilabel:`Current Rental`, click on the :guilabel:`History` button.
+     Then, click on :guilabel:`New`. Fill in the relevant details and save the rental record. Upon
+     saving the record, the rental contract :guilabel:`state` will be visible (at the top-right
+     corner) and can be set to :guilabel:`Running`.
+
+- Under the :guilabel:`HR Settings` tab:
+
+  - :guilabel:`Volunteer Contribution Option`: select either :guilabel:`Only Mandatory
+    Contribution`, :guilabel:`With Fixed %VC`, or :guilabel:`Cap 5% VC`.
+  - :guilabel:`MPF Manulife Account`: account number, if applicable.
+
+.. _hong_kong/manage_contracts:
+
+Manage contracts
+----------------
+
+Once the new employee has been created, click the :guilabel:`Contracts` smart button on the
+employee record, or navigate to :menuselection:`Employees app --> Employees --> Contracts`.
+
+.. note::
+   Only **one** contract can be active simultaneously per employee, but an employee can be assigned
+   consecutive contracts during their employment.
+
+The following are critical for setting up a contract:
+
+- :guilabel:`Salary Structure Type`: set as :guilabel:`CAP57: Hong Kong Employee`.
+- :guilabel:`Contract Start Date`: start date of employment.
+- :guilabel:`Working Schedule`: set as :guilabel:`HK Standard 40 hours/week` (from employee record).
+- :guilabel:`Work Entry Source`: select either :guilabel:`Working Schedule`, :guilabel:`Attendances`
+  or :guilabel:`Planning`. This field determines how the work entries are accounted for in the
+  payslip.
+
+  - :guilabel:`Working Schedule`: the work entries are generated automatically based on the
+    employee's working schedule.
+  - :guilabel:`Attendances`: the work entries are generated based on the check-in/out period logged
+    in the *Attendances*.
+  - :guilabel:`Planning`: the work entries are generated from planning shifts only.
+
+- Under the :guilabel:`Salary Information` tab
+
+  - :guilabel:`Wage Type`: select :guilabel:`Fixed Wage` for Full-time or Part-time employees, or
+    :guilabel:`Hourly Wage` for employees who are paid hourly.
+  - :guilabel:`Schedule Pay`: the frequency of payslip issuance.
+  - :guilabel:`Wage`: :guilabel:`Monthly` or :guilabel:`Hourly` depending on the :guilabel:`Wage
+    Type`.
+  - :guilabel:`Internet Subscription`: this is an **optional** field to provide additional internet
+    allowance on top of the current salary package.
+
+.. important::
+   Timesheets do **not** impact work entries in Odoo.
+
+Once all information has been setup, set the contract status to :guilabel:`Running` by clicking the
+:guilabel:`Running` button in the top-right of the page.
+
+.. image:: hong_kong/hk-contract.png
+   :align: center
+   :alt: Hong Kong employment contract.
+
+.. _hong_kong/running_payslips:
+
+Generate payslips
+-----------------
+
+Once the employees, and their contracts, are configured, payslips can be generated in the *Payroll*
+app.
+
+Odoo provides **four** different salary structures under CAP57 regulation:
+
+#. :guilabel:`CAP57: Employees Monthly Pay`: to process the monthly employee salary.
+#. :guilabel:`CAP57: Payment in Lieu of Notice`: to process final payment upon contract termination
+   using :abbr:`ADW (Average Daily Wage)`.
+#. :guilabel:`CAP57: Long Service Payment`: applicable to employees with more than five years of
+   service upon contract termination.
+#. :guilabel:`CAP57: Severance Payment`: applicable to employees with more than two years of service
+   upon contract termination.
+
+Before running the payslips, the accounts used in the salary rule can be adjusted by navigating to
+:menuselection:`Payroll app --> Configuration --> Rules`.
+
+.. image:: hong_kong/hk-salary-rules.png
+   :align: center
+   :alt: Hong Kong Salary Rules.
+
+Odoo can create pay runs in two ways: via :ref:`batch <hong_kong/batch_payslips>` or
+:ref:`individual <hong_kong/individual_payslips>` payslips.
+
+.. _hong_kong/batch_payslips:
+
+Batch payslips
+~~~~~~~~~~~~~~
+
+This method of payslip generation is used for recurring payments, since multiple employee payslips
+can be managed at once. Go to :menuselection:`Payroll app --> Payslips --> Batches`.
+
+#. Click on :guilabel:`New`.
+#. Enter a :guilabel:`Batch Name` (e.g. `2024 - Jan`) and :guilabel:`Period` (e.g. `01/01/2024` -
+   `01/31/2024`).
+#. Click on :guilabel:`Generate Payslips`.
+#. Choose which :guilabel:`Salary Structure` to use for this batch. The department filter allows the
+   batch to only apply to a specific group of employees.
+#. Click on :guilabel:`Generate`.
+#. A :guilabel:`Payslips` smart button is created automatically.
+
+Next, click :guilabel:`Create Draft Entry` to generate a draft journal entry found in the
+:guilabel:`Other Info` tab of each payslip. A :guilabel:`Confirmation` pop-up window appears asking
+:guilabel:`Are you sure you want to proceed?`. Click :guilabel:`Ok` to create the journal entries.
+
+.. _hong_kong/individual_payslips:
+
+Individual payslips
+~~~~~~~~~~~~~~~~~~~
+
+Go to :menuselection:`Payroll app --> Payslips --> All Payslips`.
+
+This method of payslip generation is commonly used to handle non-recurring payments (e.g.
+:guilabel:`CAP57: Payment in Lieu of Notice`, :guilabel:`CAP57: Long Service Payment` or
+:guilabel:`CAP57: Severance Payment`).
+
+#. Click on :guilabel:`New`.
+#. Select an :guilabel:`Employee`. When selected, the :guilabel:`Contract` is filled out
+   automatically.
+#. Add a pay :guilabel:`Period`.
+#. Select a salary :guilabel:`Structure` (e.g. :guilabel:`CAP57: Employees Monthly Pay`).
+#. The :guilabel:`Worked Days & Inputs` tab automatically compute the worked days/hours and time off
+   leaves that are applicable.
+#. Additional payslip items can be added at this time (e.g. :guilabel:`Commissions`,
+   :guilabel:`Deductions`) under the :guilabel:`Other Inputs` section.
+#. Click on :guilabel:`Compute Sheet` button to generate the payslip lines. This button updates
+   the :guilabel:`Salary Computation` tab.
+
+.. note::
+   If the work entry for an employee was amended, click the :icon:`fa-cog` :guilabel:`(gear)` icon,
+   then click :guilabel:`Recompute Whole Sheet` to refresh the payslip's :guilabel:`Worked Days &
+   Inputs` tab.
+
+The :guilabel:`Salary Computation` tab shows the detailed breakdown of the computation, based on
+the salary rules configured for each structure type.
+
+#. :guilabel:`Rent Allowance`: amount derived from the employee's active rental record.
+#. :guilabel:`Basic Salary`: amount of base salary provided (after rent allowance deduction).
+#. :guilabel:`713 Gross`: net payable amount considering *Commission*, *Internet Allowance*,
+   *Reimbursements*, *Back-pay*, *Deduction*, etc.
+#. :guilabel:`MPF Gross`: net payable amount from 713 gross after consideration of additional
+   allowances, deductions, and end-of-year payment.
+#. :guilabel:`Employee Mandatory Contribution`: employee MPF Contribution.
+#. :guilabel:`Employer Mandatory Contribution`: employer MPF Contribution.
+#. :guilabel:`Gross`: net payable amount from MPF gross after consideration of MPF deductions.
+#. :guilabel:`Net Salary`: final payable amount to be paid to the employee.
+
+.. important::
+   There are no MPF contributions for the first month. Both employee and employer contribution
+   starts on second month.
+
+.. image:: hong_kong/hk-salary-computation.png
+   :align: center
+   :alt: Hong Kong Salary computation.
+
+Under the :guilabel:`Other Inputs` section in :guilabel:`Worked Days & Inputs` tab, there are
+additional manual input types:
+
+- :guilabel:`Back Pay`: additional salary payout can be included under this category.
+- :guilabel:`Commission`: the commission earned during the period can be manually entered here.
+- :guilabel:`Global Deduction`: a lump-sum deduction from the entire payslip.
+- :guilabel:`Global Reimbursement`: a lump-sum reimbursement to the entire payslip.
+- :guilabel:`Referral Fee`: the additional bonus offered for any form of business-related referral.
+- :guilabel:`Moving Daily Wage`: to override the :abbr:`ADW (Average Daily Wage)` value used for
+  leaves computation.
+- :guilabel:`Skip Rent Allowance`: if set, the rental allowance is excluded from the current
+  payslip.
+- :guilabel:`Custom Average Monthly Salary`: to override the average monthly salary used for
+  end-of-year payment (rule is only applicable to payslips generated in December).
+- :guilabel:`Lieu of Notice Period (Months)`: only applicable to :guilabel:`CAP57: Payment in Lieu
+  of Notice` salary structure. By default, the final payout is set as 1-month. Use the
+  :guilabel:`Count` field under the :guilabel:`Other Inputs` section to set a different notice
+  period duration.
+
+Once the payslips are ready, click on :guilabel:`Compute Sheet`, followed by :guilabel:`Create Draft
+entry` to generate a draft journal entry found in the :guilabel:`Other Info` tab of the payslip.
+
+Pay employees
+-------------
+
+Once the draft journal entries have been posted, the company can now pay the employees. The user can
+choose between **two** different *payment methods*:
+
+- From the employee's payslip (:menuselection:`Payroll app --> Payslips --> All Payslips`), once the
+  payslip's journal entry has been posted, click :guilabel:`Register Payment`. The process is the
+  same as :doc:`paying vendor bills <../accounting/payments>`. Select the desired bank journal and
+  payment method, then later reconcile the payment with the corresponding bank statement.
+- For batch payments (:menuselection:`Payroll app --> Payslips --> Batches`), once all draft journal
+  entries from the batch are confirmed, click :guilabel:`Mark as Paid` to post the payment journal
+  entry. Then :doc:`create a payment <../accounting/payments>` in the *Accounting* app, and
+  reconcile accordingly.
+
+Attendances and hourly wage
+---------------------------
+
+To configure the contract for an employee paid hourly using the *Attendances* app for hours
+tracking, navigate to :menuselection:`Payroll app --> Contracts --> Contracts`.
+Create a new :ref:`contract <hong_kong/manage_contracts>`. It is important to remember to set the
+:guilabel:`Work Entry Source` as :guilabel:`Attendances`, and :guilabel:`Wage Type` as
+:guilabel:`Hourly Wage`.
+
+To record the hours logged by the employee using *Attendances* app:
+
+#. Go to :menuselection:`Attendances app`.
+#. The employee can check-in/out, via the kiosk mode and the time will be logged automatically.
+#. In the :menuselection:`Payroll app`, review the attendance work entries generated from
+   :menuselection:`Payroll app --> Work Entries --> Work Entries`.
+#. Next, generate the :ref:`payslips <hong_kong/running_payslips>` and process the payment.
+
+.. image:: hong_kong/hk-attendance-work-entry.png
+   :align: center
+   :alt: Hong Kong Attendance Work Entry.
+
+.. image:: hong_kong/hk-attendance-payslip.png
+   :align: center
+   :alt: Hong Kong Attendance Payslip.
+
+Time Off with Payroll
+---------------------
+
+The work entry types and time off types are fully integrated between the *Time Off* and
+*Payroll* apps. There are several default time off types and work entry types specific to
+Hong Kong which are installed automatically along with the *Hong Kong - Payroll* module.
+
+Go to :menuselection:`Payroll app --> Configuration --> Work Entry Types` and click :guilabel:`New`.
+
+There are two checkboxes to be considered when setting up the work entry type:
+
+- :guilabel:`Use 713`: Include this leave type as part of 713 computation.
+- :guilabel:`Non-full pay`: 80% of the :abbr:`ADW (Average Daily Wage)`.
+
+.. image:: hong_kong/hk-work-entry-type.png
+   :align: center
+   :alt: Hong Kong Work Entry Type.
+
+.. seealso::
+   :ref:`Creating and configuring work entry types <payroll/work-entries>`
+
+Understanding 713 Ordinance
+---------------------------
+
+The *Hong Kong - Payroll* module is compliant with 713 Ordinance which relates to the
+:abbr:`ADW (Average Daily Wage)` computation to ensure fair compensation for employees.
+
+The ADW computation is as follows:
+
+.. figure:: hong_kong/hk-adw.png
+   :alt: Hong Kong ADW Formula.
+
+   :abbr:`ADW (Average Daily Wage)` equals the total wage in a 12-month period, minus the wages of
+   non-full pay, divided by the total days in a 12-month period minus the days of non-full pay.
+
+.. note::
+   For 418 compliance, there is no automated allocation of the *Statutory Holiday* entitlement to
+   the employees. As soon as 418 requirements are met, manually allocate the leaves, via the *Time
+   Off* app.
+
+.. note::
+   Before generating payslips, ensure the statuses are :guilabel:`Done` to validate the outcome.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Period
+     - Days
+     - Wage
+     - Commission
+     - Total
+     - ADW
+     - Leave Value
+   * - Jan
+     - 31
+     - $20200
+     - $0
+     - $20200
+     - $651.61 ($20200/31)
+     - N/A
+   * - Feb
+     - 28
+     - $20200
+     - $5000
+     - $25200
+     - $769.49 ($45400/59)
+     - N/A
+   * - Mar (One Day Annual Leave)
+     - 31
+     - $20324.33
+     - $0
+     - $20324.33
+     - $730.27 ($65724.33/90)
+     - $769.49
+   * - Apr (One Day 80% Sick Leave)
+     - 30
+     - $20117.56
+     - $0
+     -
+     -
+     - $584.22 ($730.27*0.8)
+
+.. example::
+   Here is an example demonstrating the 713 logic:
+
+   - **Jan**: Generate a payslip with a monthly wage of $20200. The :abbr:`ADW (Average Daily Wage)`
+     is always computed on a cumulative basis of the trailing 12-months.
+   - **Feb**: Generate a similar payslip, but add an :guilabel:`Other Input Type` for the
+     :guilabel:`Commission`.
+   - **Mar**: Apply for **one** full-paid annual leave in March. The salary compensation for the
+     leave taken is based on :abbr:`ADW (Average Daily Wage)` thus far.
+
+     .. image:: hong_kong/hk-march-713.png
+        :align: center
+        :alt: Hong Kong March 713.
+
+   - **Apr**: Apply for a 1-day non-full pay leave in April. Since this is a non-full pay leave, the
+     :abbr:`ADW (Average Daily Wage)` is computed accordingly.
+
+     .. image:: hong_kong/hk-apr-713.png
+        :align: center
+        :alt: Hong Kong April 713.
+
+.. note::
+   The value of :abbr:`ADW (Average Daily Wage)` is computed in the backend, and not be visible to
+   the user.
+
+.. seealso::
+   - `HK 713 Ordinance <https://www.labour.gov.hk/eng/public/wcp/ConciseGuide/Appendix1.pdf>`_
+   - `HK 418 Ordinance <https://www.workstem.com/hk/en/blog/418-regulations/>`_
+
+Generate reports
+----------------
+
+Before generating the below reports, setup the following in :menuselection:`Settings app -->
+Payroll`.
+
+Configure the following in the :guilabel:`Accounting` section:
+
+- Tick the :guilabel:`Payroll HSBC Autopay` checkbox.
+
+  - :guilabel:`Autopay Type`: Set as :guilabel:`H2H Submission`.
+  - Select the :guilabel:`Bank Account` to use.
+
+Configure the following in the :guilabel:`HK Localization` section:
+
+- :guilabel:`Employer's Name shows on reports`
+- :guilabel:`Employer's File Number`
+- :guilabel:`Manulife MPF Scheme`
+
+.. image:: hong_kong/hk-report-setup.png
+   :align: center
+   :alt: Hong Kong Payroll Settings.
+
+IRD report
+~~~~~~~~~~
+
+There are a total of **four** IRD reports available:
+
+- :guilabel:`IR56B`: employer's Return of Remuneration and Pensions.
+- :guilabel:`IR56E`: notification of Commencement of Employment.
+- :guilabel:`IR56F`: notification of Ceasation of Employment (remaining in HK).
+- :guilabel:`IR56G`: notification of Ceasation of Employment (departing from HK permanently).
+
+Go to :menuselection:`Payroll app --> Reporting`, and select one of the :guilabel:`IR56B/E/F/G
+Sheet` options:
+
+#. Click on :guilabel:`New`.
+#. Fill in the relevant information for the IRD report.
+#. Click on :guilabel:`Populate`, and the :guilabel:`Eligible Employees` smart button appears.
+#. The :guilabel:`Employee Declarations` status is :guilabel:`Draft` and changed to
+   :guilabel:`Generated PDF` status once the schedule runs.
+#. Once the PDF is generated, the IRD form may be downloaded.
+
+.. image:: hong_kong/hk-ir56b.png
+   :align: center
+   :alt: Hong Kong IR56B report.
+
+.. note::
+   The scheduled action called *Payroll: Generate pdfs* can be manually triggered. It is set by
+   default to run the PDF generation monthly.
+
+Manulife MPF sheet
+~~~~~~~~~~~~~~~~~~
+
+Go to :menuselection:`Payroll app --> Reporting --> Manulife MPF Sheet`.
+
+#. Click on :guilabel:`New`.
+#. Select the relevant :guilabel:`Year`, :guilabel:`Month`, and :guilabel:`Sequence No.`.
+#. Click on :guilabel:`Create XLSX`.
+#. The *Manulife MPF XLSX* file is then generated, and available for download.
+
+.. image:: hong_kong/hk-manulife-sheet.png
+   :align: center
+   :alt: Hong Kong Manulife Sheet.
+
+.. note::
+   Odoo will not be developing further reports for other MPF trustee as there will soon be an
+   eMPF platform setup by the local government.
+
+.. seealso::
+   `eMPF <https://www.mpfa.org.hk/en/empf/overview>`_
+
+HSBC autopay report
+~~~~~~~~~~~~~~~~~~~
+
+If *HSBC Autopay* is selected as the batch payment method, click on :guilabel:`Create HSBC Autopay
+Report`, and fill in the mandatory fields:
+
+.. image:: hong_kong/hk-generate-autopay.png
+   :align: center
+   :alt: Hong Kong HSBC Autopay wizard.
+
+This creates an :file:`.apc` file format which can be uploaded to the HSCB portal for processing.

content/applications/general/developer_mode.rst

@@ -1,102 +1,68 @@
 .. _developer-mode:
 
 ===========================
-Developer Mode (debug mode)
+Developer mode (debug mode)
 ===========================
 
-The developer mode (or debug mode) unlocks access to extra and advanced tools in Odoo. There are
-several ways to activate the developer mode: through the
-:ref:`settings <general/developer_mode/settings>`, the
-:ref:`browser extension <general/developer_mode/browser-extension>`, through
-the :ref:`command palette <general/developer_mode/command-palette>`  or the
-:ref:`URL <general/developer_mode/url>`.
+The developer mode, also known as debug mode, unlocks access to advanced :ref:`tools and settings
+<developer-mode/tools>` in Odoo.
 
-.. _general/developer_mode/settings:
-
-Activate through the Settings
-=============================
-
-The debug mode can be activated in the Odoo database settings. Go to :menuselection:`Settings -->
-General Settings --> Developer Tools` and click on :guilabel:`Activate the developer mode`. At
-least one application needs to be installed for the :guilabel:`Developer Tools` section to appear
-in the :guilabel:`Settings` module.
-
-.. image:: developer_mode/settings.png
-   :align: center
-   :alt: Overview of the debug options under settings in Odoo.
+.. warning::
+   Proceed with caution, as some developer tools and technical settings are considered advanced and
+   may have associated risks. Only use them if you understand the implications and are confident in
+   your actions.
 
 .. note::
-   :guilabel:`Activate the developer mode (with assets)` is used by developers; :guilabel:`Activate
-   the developer mode (with tests assets)` is used by developers and testers.
+   The developer mode is also available with :ref:`assets <frontend/framework/assets_debug_mode>`,
+   which are used to debug JavaScript code, and with :ref:`tests assets
+   <frontend/framework/tests_debug_mode>`, which are used to run test tours.
+
+.. _developer-mode/activation:
+
+Activation
+==========
+
+To activate it, open the :guilabel:`Settings` app, scroll down to the :guilabel:`Developer Tools`
+section, and click :guilabel:`Activate the developer mode`.
 
 Once activated, the :guilabel:`Deactivate the developer mode` option becomes available.
 
-.. _general/developer_mode/browser-extension:
+.. image:: developer_mode/settings.png
+   :alt: Activating the developer mode in the Settings app
 
-Activate through the browser extension
-======================================
+To activate the developer mode **from anywhere in the database**, add `?debug=1` to the URL after
+`/web` (e.g., `https://example.odoo.com/web?debug=1#action=menu&cids=1`). To deactivate it, use
+`?debug=0` instead.
 
-Within a web browser, navigate to the browser settings and extensions and search for the `Odoo
-Debug` extension. Once the extension is installed, a new icon will be shown on the browser's
-toolbar.
-
-For the *Odoo Debug* extension, a single click enables a normal version of the mode, while a
-double click enables it with assets. To deactivate it, use a single click.
-
-.. image:: developer_mode/developer-mode-monkey.png
-   :align: center
-   :alt: View of Odoo's debug icon in a Google Chrome toolbar.
-
-.. _general/developer_mode/command-palette:
-
-Activate through the command palette
-====================================
-
-In Odoo, the command palette tool has a command to activate the debug mode. First, open the command
-palette tool with the keyboard shortcut `ctrl+k` and then type `debug`. A command will show up to
-activate the debug mode.
-
-.. image:: developer_mode/command-palette.png
-   :align: center
-   :alt: Command palette with debug command.
-
-.. _general/developer_mode/url:
-
-.. _developer-mode/url:
-
-Activate through the URL
-========================
-
-The debug mode can also be activated by adding an extra query string to the database's URL. In the
-URL, add `?debug=1` or `?debug=true` after `/web`. To deactivate the debug mode, change the
-value to `?debug=0` instead.
-
-.. image:: developer_mode/url.png
-   :align: center
-   :alt: Overview of a URL with the debug mode command added.
+Use `?debug=assets` to activate the developer mode with assets and `?debug=tests` to activate it
+with tests assets.
 
 .. tip::
-   Additional modes are available for developers: `?debug=assets` enables the
-   :ref:`assets mode <frontend/framework/assets_debug_mode>`, and `?debug=tests` enables
-   the :ref:`tests mode <frontend/framework/tests_debug_mode>`.
+   Open the **command palette** by pressing `Ctrl + K` or `Cmd ⌘ + K`, then type `debug` to
+   activate the developer mode with assets or deactivate it.
 
-.. _developer-mode/mode-tools:
+.. admonition:: Browser extension
 
-Locate the developer mode tools
-===============================
+   The `Odoo Debug <https://github.com/Droggol/OdooDebug>`_ browser extension adds an icon to toggle
+   developer mode on or off from the browser's toolbar. It is available on the `Chrome Web Store
+   <https://chromewebstore.google.com/detail/odoo-debug/hmdmhilocobgohohpdpolmibjklfgkbi>`_ and
+   `Firefox Add-ons <https://addons.mozilla.org/firefox/addon/odoo-debug/>`_.
 
-Once developer mode is activated, the developer mode tools can be accessed from the :guilabel:`Open
-Developer Tools` button, the bug icon located in the header of the Odoo database.
+.. _developer-mode/tools:
 
-.. image:: developer_mode/button-location.png
-   :align: center
-   :alt: Overview of a console page and the debug icon being shown in Odoo.
+Developer tools and technical menu
+==================================
 
-This menu contains additional tools that are useful to understand or edit technical data, such as
-the views or actions of a page. On a page that has filters, actions, and view options, the
-developer mode tools contain some useful menu items such as:
+Once the developer mode is activated, the developer tools can be accessed by clicking the
+:icon:`fa-bug` :guilabel:`(bug)` icon. The menu contains tools useful for understanding or editing
+technical data, such as a view's field, filters, or actions. The options available depend on where
+the menu is accessed from.
 
-- :guilabel:`Edit Action`
-- :guilabel:`Manage Filters`
-- Edit the current view (e.g. Kanban, List, Graph, etc.)
-- See the :guilabel:`Fields View Get`
+.. image:: developer_mode/tools.png
+   :alt: Accessing the developer tools
+
+Database administrators can access the technical menu from the :guilabel:`Settings` app. It contains
+advanced database settings, such as ones related to the database structure, security, actions, etc.
+
+.. image:: developer_mode/technical.png
+   :alt: Accessing the technical menu

content/applications/general/email_communication/email_domain.rst

@@ -96,6 +96,8 @@ the :abbr:`DNS (Domain Name System)` zone of the domain name. The most common pr
 Check if the :abbr:`DKIM (DomainKeys Identified Mail)` record is valid with a free tool like `DKIM
 Core <https://dkimcore.org/tools/>`_. If a selector is asked, enter `odoo`.
 
+.. _email_communication/DMARC_compliant:
+
 Check the DMARC policy
 ======================
 

content/applications/general/iot/config/windows_iot.rst

@@ -38,10 +38,10 @@ installing the Windows virtual IoT software for the first time.
 Download and initial installation
 ---------------------------------
 
-To begin the installation, navigate to the Odoo 16 or higher installation package for Enterprise or
-Community - Windows edition at `Odoo's download page <https://odoo.com/download>`_. Next, install
-and setup the Odoo :file:`.exe` file. After the instructions screen, click :guilabel:`Next` to start
-the installation and agree to the :abbr:`TOS (Terms of Service)`.
+To begin the installation, navigate to the Odoo 16 or higher installation package for Community -
+Windows edition at `Odoo's download page <https://odoo.com/download>`_. Next, install and setup the
+Odoo :file:`.exe` file. After the instructions screen, click :guilabel:`Next` to start the
+installation and agree to the :abbr:`TOS (Terms of Service)`.
 
 During the next step of the installation, select :guilabel:`Odoo IoT` from the :guilabel:`Select the
 type of install` drop-down menu.

content/applications/general/iot/devices.rst

@@ -1,4 +1,6 @@
 :nosearch:
+:show-content:
+:show-toc:
 
 =======
 Devices
@@ -14,3 +16,8 @@ Devices
    devices/footswitch
    devices/printer
    devices/scale
+
+.. seealso::
+   - :doc:`Worldline payment terminal
+     <../../sales/point_of_sale/payment_methods/terminals/worldline>`
+   - :doc:`Ingenico payment terminal <../../sales/point_of_sale/payment_methods/terminals/ingenico>`

content/applications/hr/appraisals.rst

@@ -1,3 +1,5 @@
+:show-content:
+
 ==========
 Appraisals
 ==========
@@ -168,29 +170,6 @@ document.
 .. note::
    In previous versions of Odoo, this section was referred to as :guilabel:`Surveys`.
 
-Tags
-----
-
-An additional feature of the *Appraisals* application is the ability to set :ref:`goals
-<appraisals/goals>` for employees. On each goal form, there is a field to add tags. The available
-tags are pulled from a list that is configured from the settings.
-
-To view a list of all existing goal tags, and to create new tags, go to the :guilabel:`Goal Tags`
-page, by navigating to :menuselection:`Appraisals application --> Configuration --> Tags`.
-
-All currently configured tags are presented in a list view.
-
-The *Appraisals* application does **not** have any pre-configured tags, so all tags need to be added
-from this list, or directly from the goal form.
-
-To create a new tag from the :guilabel:`Goal Tags` page, click the :guilabel:`New` button, and a
-blank line appears.
-
-Enter the name of the tag on the line. Then, press the enter key to save the tag, and create a new
-blank line. Repeat this for all tags that need to be added.
-
-The list of tags is automatically arranged in alphabetical order.
-
 Appraisals
 ==========
 
@@ -455,79 +434,7 @@ Next, click on the :guilabel:`Meeting` smart button, and the calendar loads. Fol
 directions above to create the meeting.
 
 .. note::
-   If no meetings are scheduled, the :guilabel:`Meeting` smart button says :guilabel:`No Meeting`.
-
-.. _appraisals/goals:
-
-Goals
-=====
-
-The ability to set goals for employees to work toward is an important feature of Odoo *Appraisals*.
-Goals are typically set during an appraisal, so the employee knows what they need to work toward
-before their next appraisal.
-
-To view all goals, navigate to :menuselection:`Appraisals application --> Goals`. This presents all
-the goals for every employee, in a default Kanban view.
-
-Each goal card contains the following information:
-
-- :guilabel:`Skill`: the name of the goal.
-- :guilabel:`Name`: the employee the goal is assigned to.
-- :guilabel:`Deadline`: the due date for the goal.
-- :guilabel:`Progress`: the percentage of competency set for the goal.
-- :guilabel:`Employee`: the profile icon of the employee the goal is assigned to.
-
-If a goal is completed, a :guilabel:`Done` banner appears in the top-right corner of the goal card.
-
-.. image:: appraisals/goals.png
-   :align: center
-   :alt: The goals Kanban view, with nine goal cards.
-
-.. note::
-   Every individual goal requires its own entry for each employee. If employees have the same goal,
-   a goal card for each employee appears on the list. For example, if both Bob and Sara have the
-   same goal of `Typing`, two cards appear in the Kanban view: one `Typing` goal for Bob, and
-   another `Typing` goal for Sara.
-
-New goal
---------
-
-To create a new goal, navigate to :menuselection:`Appraisals application --> Goals`, and click
-:guilabel:`New` to open a blank goal form.
-
-Enter the information on the card. The information requested is all the same information that
-appears on the :ref:`goal card <appraisals/goals>` in the Kanban view, with the addition of a
-:guilabel:`Tags` field and a :guilabel:`Description` tab.
-
-The current user populates the :guilabel:`Employee` field by default, and the :guilabel:`Manager`
-field populates with the manager set on the employee profile.
-
-Make any necessary changes to the form, and add any notes that might be useful to clarify the goal
-in the :guilabel:`Description` tab.
-
-.. image:: appraisals/new-goal.png
-   :align: center
-   :alt: A goal form filled out for a Python skill, set to 50% proficiency.
-
-Completed goals
----------------
-
-When a goal has been met, it is important to update the record. A goal can be marked as `Done` in
-one of two ways: from the main :guilabel:`Goals` dashboard, or from the individual goal card.
-
-To mark a goal as `Done` from the main :guilabel:`Goals` dashboard, click on the :guilabel:`⋮ (three
-dots)` icon in the top-right of a goal card.
-
-.. important::
-   The :guilabel:`⋮ (three dots)` icon **only** appears when the mouse hovers over the corner of a
-   goal card.
-
-Then, click :guilabel:`Mark as Done` from the resulting drop-down menu. A green :guilabel:`Done`
-banner appears in the top-right corner of the goal card.
-
-To mark a goal as `Done` from the goal card itself, click on a goal card to open that goal's form.
-Then, click the :guilabel:`Mark as Done` button in the top-left of the form. When clicked, a green
-:guilabel:`Done` banner appears in the top-right corner of the goal form.
+   If no meetings are scheduled, the :guilabel:`Meeting` smart button reads :guilabel:`No Meeting`.
 
 Reporting
 =========
@@ -589,3 +496,11 @@ Each skill has the following information listed:
 .. image:: appraisals/skills-report.png
    :align: center
    :alt: A report showing all the skills grouped by employee.
+
+.. seealso::
+   :doc:`appraisals/goals`
+
+.. toctree::
+   :titlesonly:
+
+   appraisals/goals

content/applications/hr/appraisals/goals.rst

@@ -0,0 +1,85 @@
+=====
+Goals
+=====
+
+The Odoo *Appraisals* application allows managers to set goals for their employees. That way,
+employees know what to work toward before their next review.
+
+To view all goals, navigate to :menuselection:`Appraisals app --> Goals`. This presents all the
+goals for every employee, in a default Kanban view.
+
+.. _appraisals/goal-card:
+
+Each goal card contains the following information:
+
+- :guilabel:`Goal`: the name of the goal.
+- :guilabel:`Employee`: the employee the goal is assigned to.
+- :icon:`fa-clock-o` :guilabel:`(clock)` icon: displays the corresponding :doc:`activity icon
+  <../../essentials/activities>` for the record. If no activities are scheduled, the default icon is
+  the :icon:`fa-clock-o` :guilabel:`(clock)`. If any activities have been scheduled, the icon
+  represents the activity scheduled soonest.
+- :guilabel:`Deadline`: the due date for the goal.
+- :guilabel:`Progress`: the percentage of competency set for the goal. The options are
+  :guilabel:`0%`, :guilabel:`25%`, :guilabel:`50%`, :guilabel:`75%`, or :guilabel:`100%`.
+- :guilabel:`Employee Icon`: the profile icon of the employee the goal is assigned to.
+
+If a goal is completed, a :guilabel:`Done` banner appears in the top-right corner of the goal card.
+
+.. image:: goals/goals.png
+   :align: center
+   :alt: The goals Kanban view, with nine goal cards.
+
+.. note::
+   Every individual goal requires its own record for each employee. If multiple employees have the
+   same goal, a goal card for each employee appears on the list.
+
+   For example, if Bob and Sara have the same goal of `Typing`, two cards appear in the Kanban view:
+   one `Typing` goal for Bob, and another `Typing` goal for Sara.
+
+New goal
+========
+
+To create a new goal, navigate to :menuselection:`Appraisals app --> Goals`, and click
+:guilabel:`New` top-left corner to open a blank goal form.
+
+Input the :guilabel:`Goal`, :guilabel:`Employee`, :guilabel:`Progress`, and :guilabel:`Deadline`,
+information on the goal card, as discussed in the :ref:`goal card <appraisals/goal-card>` section of
+this document.
+
+The information requested is all the same information that appears on the goal card in the Kanban
+view, with the addition of a :guilabel:`Tags` field and a :guilabel:`Description` tab.
+
+.. tip::
+   The *Appraisals* application does **not** have any pre-configured tags, so all tags need to be
+   added. To add a tag, enter the name of the tag on the line, then click :guilabel:`Create
+   "(tag)"`. Repeat this for all tags that need to be added.
+
+The current user populates the :guilabel:`Employee` field, by default, and the :guilabel:`Manager`
+field populates with the manager set on the employee profile.
+
+Make any necessary changes to the form, and add any notes that might be useful to clarify the goal
+in the :guilabel:`Description` tab.
+
+.. image:: goals/new-goal.png
+   :align: center
+   :alt: A goal form filled out for a Python skill, set to 50% proficiency.
+
+Completed goals
+===============
+
+When a goal has been met, it is important to update the record. A goal can be marked as `Done` in
+one of two ways: from the main :guilabel:`Goals` dashboard, or from the individual goal card.
+
+To mark a goal as `Done` from the main :guilabel:`Goals` dashboard, click on the
+:icon:`fa-ellipsis-v` :guilabel:`(vertical ellipsis)` icon in the top-right of a goal card.
+
+.. note::
+   The :icon:`fa-ellipsis-v` :guilabel:`(vertical ellipsis)` icon **only** appears when the mouse
+   hovers over the top-right corner of a goal card.
+
+Then, click :guilabel:`Mark as Done` from the resulting drop-down menu. A green :guilabel:`Done`
+banner appears in the top-right corner of the goal card.
+
+To mark a goal as `Done` from the goal card itself, click on a goal card to open that goal's form.
+Then, click the :guilabel:`Mark as Done` button in the top-left of the form. When clicked, a green
+:guilabel:`Done` banner appears in the top-right corner of the goal form.

content/applications/hr/employees.rst

@@ -12,3 +12,4 @@ Odoo *Employees* organizes a company's employee records, contracts, and departme
    :titlesonly:
 
    employees/new_employee
+   employees/departments

content/applications/hr/employees/departments.rst

@@ -0,0 +1,151 @@
+===========
+Departments
+===========
+
+All employees in the *Employees* app fall under specific departments within a company.
+
+Create new departments
+======================
+
+To make a new department, navigate to :menuselection:`Employees app --> Departments`, then click
+:guilabel:`New` in the top-left to reveal a blank department form. Fill out the following
+information on the department form:
+
+.. image:: departments/department-form.png
+   :align: center
+   :alt: The department for with all fields filled out.
+
+- :guilabel:`Department Name`: enter a name for the department.
+- :guilabel:`Manager`: using the drop-down menu, select the department manager.
+- :guilabel:`Parent Department`: if the new department is housed within another department (has a
+  parent department), select the parent department using the drop-down menu.
+- :guilabel:`Custom Appraisal Templates`: if employees in this department require a specific
+  appraisal form that is different from the default appraisal form, tick the checkbox. If this
+  option is activated, an :guilabel:`Appraisal Templates` tab appears below the form. This field
+  **only** appears if the *Appraisals* app is installed.
+- :guilabel:`Company`: using the drop-down menu, select the company the department is part of.
+- :guilabel:`Appraisal Survey`: using the drop-down menu, select the default survey to use for the
+  department when requesting feedback from employees. This field **only** appears if the
+  *Appraisals* app is installed, **and** the *360 Feedback* option is enabled in the settings.
+- :guilabel:`Color`: select a color for the department. Click the default white color box to display
+  all the color options. Click on a color to select it.
+- :guilabel:`Appraisal Templates` tab: this tab **only** appears if the :guilabel:`Custom Appraisal
+  Templates` options is activated on the form. Make any desired edits to the appraisal form. The
+  appraisal form is used for appraisals for all employees within this department.
+
+After the form is completed, click the :icon:`fa-cloud-upload` :guilabel:`(cloud upload)` icon to
+manually save the changes. When saved, a :guilabel:`Department Organization` chart appears in the
+top-right of the department card.
+
+.. note::
+   The form auto-saves while data is entered, however the :guilabel:`Department Organization` chart
+   does **not** appear until the form is manually saved. If the form is not saved, the
+   :guilabel:`Department Organization` chart is visible upon opening the department card from the
+   :guilabel:`Departments` dashboard.
+
+.. seealso::
+   Refer to the :doc:`../appraisals` documentation for more information.
+
+Departments dashboard
+=====================
+
+To view the currently configured departments, navigate to :menuselection:`Employees app -->
+Departments`. All departments appear in a Kanban view, by default, and are listed in alphabetical
+order.
+
+.. image:: departments/departments.png
+   :align: center
+   :alt: The departments dashboard view with all the department cards in a Kanban view.
+
+Kanban view
+-----------
+
+Each department has its own Kanban card on the main :guilabel:`Departments` :icon:`oi-view-kanban`
+:guilabel:`(Kanban)` dashboard view, that can display the following information:
+
+- Department name: the name of the department.
+- Company: the company the department is part of.
+- :guilabel:`Employees`: the number of employees within the department.
+- :guilabel:`Appraisals`: the number of appraisals scheduled for employees in the department.
+- :guilabel:`Time Off Requests`: the number of unapproved time off requests for employees in the
+  department :ref:`awaiting approval <time_off/manage-time-off>` . This **only** appears if there
+  are requests to approve.
+- :guilabel:`Allocation Requests`: the number of unapproved allocation requests for employees in the
+  department :ref:`awaiting approval <time_off/manage-allocations>`. This **only** appears if there
+  are requests to approve.
+- :guilabel:`New Applicants`: the number of :ref:`new applicants <recruitment/new>` for a position
+  in this department. This **only** appears if there are new applicants.
+- :guilabel:`Expense Reports`: the number of employees in the department with :ref:`open expense
+  reports to approve <expenses/approve>`. This **only** appears if there are any expense reports
+  waiting for approval.
+- :guilabel:`Absence`: the number of absences for the current day.
+- Color bar: the selected color for the department appears as a vertical bar on the left side of the
+  department card.
+
+.. note::
+   Click on an alert in a department card, such as :guilabel:`Time Off Requests`, to reveal a list
+   view of the requests to approve. This list includes **all** open requests to approve, not just
+   from the specific department.
+
+The default view for the :guilabel:`Departments` dashboard is a Kanban view. It is possible to view
+the departments in two other forms: a list view and a hierarchy view.
+
+List view
+---------
+
+To view the departments in a list view, click the :icon:`fa-align-justify` :guilabel:`(list)` icon
+in the top-right corner. The departments appear in a list view, which displays the
+:guilabel:`Department Name`, :guilabel:`Company`, :guilabel:`Manager`, :guilabel:`Employees`,
+:guilabel:`Parent Department`, and :guilabel:`Color` for each department.
+
+The departments are sorted alphabetically by :guilabel:`Department Name`, by default.
+
+.. image:: departments/list.png
+   :align: center
+   :alt: The departments presented in a list view.
+
+.. tip::
+   When in list view, departments can be managed in batch by selecting one or multiple record's
+   checkbox, then select the :icon:`fa-cog` :guilabel:`Actions` button to reveal a drop-down menu of
+   actions.
+
+Hierarchy view
+--------------
+
+To view the departments in a hierarchy view, click the :icon:`fa-share-alt fa-rotate-90`
+:guilabel:`(hierarchy)` icon in the top-right corner. The departments appear in an organizational
+chart format, with the highest-level department at the top (typically :guilabel:`Management`), and
+all other departments beneath it. All child departments of the first-level child departments are
+folded.
+
+Each department card displays the :guilabel:`Department Name`, the :guilabel:`Manager` (and their
+profile image), the :guilabel:`Number of Employees` in the department, and the ability to expand the
+department (:guilabel:`Unfold`) if there are child departments beneath it.
+
+Click the :guilabel:`Unfold` button on a department card to expand it. Once expanded, the
+:guilabel:`Unfold` button changes to a :guilabel:`Fold` button. To collapse the department, click
+the :guilabel:`Fold` button. Only **one** department *per row* can be unfolded at a time.
+
+Click anywhere on a department card to open the department form. Click the :guilabel:`(#) Employees`
+smart button to view a list of all the employees in that department, including all employees in the
+child departments beneath it, organized by individual department.
+
+.. example::
+   In the hierarchy view, if the :guilabel:`(2) Employees` button on the :guilabel:`Management` card
+   is clicked (the highest-level department card), **all** employees appear in a list view, grouped
+   by department. This is because **all** departments are children of the :guilabel:`Management`
+   department.
+
+   If the :guilabel:`(3) Employees` button in the :guilabel:`Sales` department card is clicked, the
+   employees from the :guilabel:`Sales` department, as well as its two child departments
+   (:guilabel:`East Coast Territory` and :guilabel:`West Coat Territory`), appear in the list.
+
+  .. image:: departments/hierarchy.png
+     :align: center
+     :alt: The departments presented in a hierarchy view.
+
+  .. image:: departments/employee-list.png
+     :align: center
+     :alt: The list view of employees for the department that was clicked, including all child
+           departments.
+

content/applications/hr/frontdesk.rst

@@ -1,3 +1,5 @@
+:show-content:
+
 =========
 Frontdesk
 =========
@@ -184,94 +186,10 @@ Station dashboard
 
    The image selected now appears in the picture field, and is set as the image for the drink.
 
+.. _frontdesk/kiosk:
 
-.. _frontdesk/visitors:
-
-Visitors
-========
-
-To access a complete list of visitors that are currently checked in, navigate to
-:menuselection:`Frontdesk app --> Visitors`.
-
-The visitors are listed in a list view, with the following details that were entered when they
-checked in:
-
-.. note::
-   By default, the :guilabel:`Planned or Checked-In` and :guilabel:`Today` filters appear in the
-   :guilabel:`Search...` bar.
-
-- :guilabel:`Name`: the guest's name.
-- :guilabel:`Visitor Company`: the company the guest represents.
-- :guilabel:`Phone`: the guest's phone number.
-- :guilabel:`Drinks`: the drink the guest requested.
-- :guilabel:`Host`: who the guest is waiting to see.
-- :guilabel:`CheckIn`: the date and time the guest checked in.
-- :guilabel:`Checkout`: the date and time the guest checked out. As mentioned, in the default view,
-  only guests with a :guilabel:`Checked-In` or :guilabel:`Planned` status are visible. Guests with
-  check-out times are only visible if the :guilabel:`Today` filter is not active.
-- :guilabel:`Duration`: the amount of time the guest has been checked in for.
-- :guilabel:`Station`: the location of where the guest checked in.
-- :guilabel:`Status`: the status of the guest. The options are :guilabel:`Checked-In`,
-  :guilabel:`Planned`, :guilabel:`Checked-Out`, or :guilabel:`Canceled`. In the default view, only
-  guests with a :guilabel:`Checked-In` or :guilabel:`Planned` status are visible.
-- :guilabel:`Email`: the guest's email address.
-
-To the far right of the titled columns on the :guilabel:`Visitors` page is an untitled column,
-where a guest's status can be updated.
-
-When a guest leaves, click the available :guilabel:`Check out` button to update the guest's record,
-and log the date and time they left.
-
-If a scheduled guest arrives, and they did not check in using the *Frontdesk* kiosk, they can be
-checked in here, by clicking the available :guilabel:`Check in` button to log the date and time they
-arrived.
-
-Beside the untitled status column a :guilabel:`Drink Served` button appears, but only if that
-particular visitor requested a drink.
-
-When their drink has been served, click the :guilabel:`Drink Served` button to indicate the drink
-has been delivered to the guest. Once clicked, that button disappears.
-
-.. image:: frontdesk/visitors.png
-   :align: center
-   :alt: The full list of currently checked in visitors, with the drinks to be served highlighted.
-
-If any column is not visible, or if a visible column is preferred to be hidden, click the
-:guilabel:`Additional Options (two horizontal lines with dots)` icon, located at the end of the
-column name list.
-
-Clicking that reveals a drop-down menu of column options to enable or disable. A :guilabel:`✅
-(checkmark)` icon indicates the column is visible.
-
-Planned visitors
-----------------
-
-If a guest is expected to arrive at a future date and time, it is possible to enter their
-information into the *Frontdesk* application in advance.
-
-To create a planned guest, navigate to :menuselection:`Frontdesk app --> Visitors --> New`. Then,
-enter the same information as any other :ref:`visitor <frontdesk/visitors>`. The only required
-fields are the visitor's :guilabel:`Name` and the :guilabel:`Station` at which they are expected to
-arrive.
-
-.. important::
-   If a guest is planned in advance, they must be checked in from the list on the
-   :guilabel:`Visitors` page in the *Frontdesk* application (:menuselection:`Frontdesk app -->
-   Visitors`). If a planned guest checks in using a kiosk, they will be checked in separately, and
-   their planned visitor entry remains listed as :guilabel:`Planned`.
-
-   Only when a planned guest is checked in inside the application's visitor list, their
-   :guilabel:`Planned` status changes to :guilabel:`Checked-In`.
-
-   If a guest does check in using a kiosk, ensure all records are current, and the list of
-   currently on-site guests is correct. Be sure to check in and/or check out the correct entries, so
-   the visitors list correctly reflects who is currently on the premises.
-
-   Ensure planned guests are informed that they should **not** check in using the kiosk if they are
-   listed as a planned guest in advance.
-
-Frontdesk flow
-==============
+Kiosk setup
+===========
 
 Set up each kiosk for use after configuring the various stations. It is recommended to use a
 dedicated device for each frontdesk kiosk, such as a tablet.
@@ -288,65 +206,6 @@ Navigate to the kiosk in one of two ways:
    It is recommended to log out of the database, and close the tab, after navigating to the kiosk.
    That way, there is no possibility of a visitor accessing the database when checking-in.
 
-Visitor flow
-------------
-
-When a visitor arrives at a facility, they approach a frontdesk kiosk, and enter their information.
-The information requested is what was configured for that specific frontdesk station. If any
-information is required, the field displays a red asterisk (*). The visitor must enter the required
-information in order to check in.
-
-Once all the information is entered, the visitor taps the :guilabel:`Check In` button.
-
-If drinks were configured for the station, after tapping :guilabel:`Check In`, a registration
-confirmation screen loads, along with the question: `Do you want something to drink?`
-
-The visitor can tap either :guilabel:`Yes, please`, or :guilabel:`No, thank you`.
-
-If they select :guilabel:`Yes, please`, a drink selection screen appears, and the pre-configured
-options are listed. The visitor then taps the desired selection, or, if they do not want anything,
-they can tap the :guilabel:`Nothing, thanks` button at the bottom of the screen.
-
-If a drink selection was made, a `Thank you for registering! Your drink is on the way.` message
-appears.
-
-At any point in the check-in process, if ten seconds pass with no selection, the kiosk returns to
-the main welcome screen.
-
-Once the visitor has checked in, the person they are visiting, and any other users who were
-configured to be notified when checks ins occur at the kiosk, are notified. The notification is
-either by email, SMS message, a *Discuss* chat, or any combination of those three options.
-
-If the visitor requested a drink, the user(s) configured as the :guilabel:`People to Notify` on the
-drink form, are notified via the *Discuss* application. The message that appears is: `(Visitor Name)
-just checked-in. They requested (Drink Name).`
-
-Once the drink has been delivered to the guest, the person who delivered the drink is responsible
-for marking the drink as delivered.
-
-To mark a drink as delivered, navigate to :menuselection:`Frontdesk app --> Stations --> (#) Drinks
-to serve` on the desired station card.
-
-This opens a list of all the visitors checked in at that station, and are waiting for a drink. Click
-the :guilabel:`Drink Served` button at the end of the line for the visitor who was served. Once they
-are marked as having their drink served, the visitor disappears from the list.
-
-Once the visitor has completed their business, and has left the premises, it is important to check
-them out for accurate record keeping.
-
-To check visitors out properly, navigate to :menuselection:`Frontdesk app --> Stations --> (#) On
-Site`. Doing so opens a list of all the visitors who are currently checked-in at that station.
-
-Click the :guilabel:`Check Out` button near the end of the line for the visitor who left. Once they
-are marked as checked-out, the visitor disappears from the list.
-
-.. important::
-   Visitors do **not** check themselves out when they leave. It is important to check out visitors
-   for accurate record keeping.
-
-   Always have an accurate list of who is on the premises at any given time. This is important for
-   security purposes, and in the case of an emergency.
-
 Reporting
 =========
 
@@ -359,3 +218,11 @@ The :guilabel:`Visitors` report displays the number of visitors by month, for th
 :guilabel:`Drinks` report shows how many total requests were made for each drink.
 
 As with all reports in Odoo, the filters and groups can be modified to show other metrics, as well.
+
+.. seealso::
+   - :doc:`frontdesk/visitors`
+
+.. toctree::
+   :titlesonly:
+
+   frontdesk/visitors

content/applications/hr/frontdesk/visitors.rst

@@ -0,0 +1,165 @@
+========
+Visitors
+========
+
+In the Odoo *Frontdesk* application, a *visitor* is defined as any non-employee (e.g., repair
+person, job candidate, etc.). These visitors can be logged upon arrival and departure for security
+purposes. This ensures an accurate list of people on the premises.
+
+.. _frontdesk/list:
+
+Visitor list
+============
+
+To access a complete list of checked-in visitors, navigate to :menuselection:`Frontdesk app -->
+Visitors`.
+
+.. note::
+   By default, the :guilabel:`Planned or Checked-In` and :guilabel:`Today` filters appear in the
+   :guilabel:`Search...` bar.
+
+All visitors are presented in a list view, with the following details that were entered upon check
+in:
+
+- :guilabel:`Name`: the guest's name.
+- :guilabel:`Visitor Company`: the company the guest represents.
+- :guilabel:`Phone`: the guest's phone number.
+- :guilabel:`Drinks`\*: the drink the guest requested.
+- :guilabel:`Host`: who the guest is waiting to see.
+- :guilabel:`CheckIn`: the date and time the guest checked in.
+- :guilabel:`Checkout`\*: the date and time the guest checked out. In the default view, only guests
+  with a :guilabel:`Checked-In` or :guilabel:`Planned` status are visible. Guests with check-out
+  times are only visible if the :guilabel:`Today` filter is not active.
+- :guilabel:`Duration`: the amount of time the guest has been checked in for.
+- :guilabel:`Station`: the location of where the guest checked in.
+- :guilabel:`Status`: the status of the guest. The options are :guilabel:`Checked-In`,
+  :guilabel:`Planned`, :guilabel:`Checked-Out`, or :guilabel:`Canceled`.
+- :guilabel:`Email`\*: the guest's email address.
+
+\* These fields are not visible in the default :guilabel:`Visitor` list. These must be enabled
+using the :icon:`oi-settings-adjust` :guilabel:`(settings adjust)` icon in the top-right of the
+list.
+
+To the far-right of the titled columns on the :guilabel:`Visitors` page, there is an untitled
+column, where a guest's status can be updated.
+
+When a guest leaves, click the available :guilabel:`Check out` button to update the guest's record,
+and log the date and time they left.
+
+If a scheduled guest arrives, and they did not check in using the *Frontdesk* kiosk, they can be
+checked in here, by clicking the available :guilabel:`Check in` button to log the date and time they
+arrived.
+
+Beside the untitled status column, a :guilabel:`Drink Served` button appears, but only if that
+particular visitor requested a drink.
+
+When their drink has been served, click the :guilabel:`Drink Served` button to indicate the drink
+has been delivered to the guest. Once clicked, that button disappears.
+
+.. image:: visitors/visitors.png
+   :align: center
+   :alt: The full list of currently checked in visitors, with the drinks to be served highlighted.
+
+If any column is not visible, or if a visible column is preferred to be hidden, click the
+:icon:`oi-settings-adjust` :guilabel:`(additional options)` icon, located at the end of the column
+name list. Doing so, reveals a reveals a drop-down menu of column options to enable or disable. A
+:icon:`fa-check` :guilabel:`(check)` icon indicates the column is visible.
+
+Planned visitors
+================
+
+Enter expected guest information in advance by creating a planned guest in the *Frontdesk* app.
+
+To create a planned guest, navigate to :menuselection:`Frontdesk app --> Visitors`, and click
+:guilabel:`New`. Then, enter the same information as any other :ref:`visitor <frontdesk/list>` on
+the guest form that appears. The only required fields are the visitor's :guilabel:`Name` and the
+:guilabel:`Station` at which they are expected to arrive.
+
+.. important::
+   If a guest is planned in advance, they must be checked in from the list on the
+   :guilabel:`Visitors` page in the *Frontdesk* application (:menuselection:`Frontdesk app -->
+   Visitors`). If a planned guest checks in using a kiosk, they will be checked in separately, and
+   their planned visitor entry remains listed as :guilabel:`Planned`.
+
+   The :guilabel:`Planned` status of a planned guest **only** changes to :guilabel:`Checked-In` when
+   they are checked in *inside* the application's :guilabel:`Visitors` list.
+
+   If a guest does check in using a kiosk, ensure all records are current, and the list of guests
+   that are currently on-site is correct. Be sure to check in and/or check out the correct entries,
+   so the visitors list correctly reflects who is currently on the premises.
+
+   Ensure planned guests are informed that they should **not** check in using the kiosk if they are
+   listed as a planned guest in advance.
+
+Visitor flow
+============
+
+Visitor check in
+----------------
+
+When a visitor arrives at a facility, they approach a :ref:`Frontdesk kiosk <frontdesk/kiosk>`, and
+click :guilabel:`Check in`. The information requested from the visitor is what was configured for
+that specific *Frontdesk* station. If any information is required, the field displays a red asterisk
+(\*). The visitor **must** enter the required information in order to check in.
+
+Once all the information is entered, the visitor taps the :guilabel:`Check In` button.
+
+.. note::
+   At any point in the check-in process, if ten seconds pass with no selection, the kiosk returns to
+   the main welcome screen.
+
+Drinks
+------
+
+If drinks were configured for the station, after tapping :guilabel:`Check In`, a registration
+confirmation screen loads, along with the question: :guilabel:`Do you want something to drink?`
+
+The visitor can tap either :guilabel:`Yes, please`, or :guilabel:`No, thank you`.
+
+If they select :guilabel:`Yes, please`, a drink selection screen appears, and the pre-configured
+options are listed. The visitor then taps the desired selection, or, if they do not want anything,
+they can tap the :guilabel:`Nothing, thanks` button at the bottom of the screen.
+
+If a drink selection was made, a :guilabel:`Thank you for registering! Your drink is on the way.`
+message appears.
+
+Notifications
+-------------
+
+Once the visitor has checked in, the person they are visiting, and any other users who were
+configured to be notified when check-ins occur at the kiosk, are notified. The notification is
+either by email, SMS message, a *Discuss* chat, or any combination of those three options.
+
+If the visitor requested a drink, the user(s) configured as the :guilabel:`People to Notify` on the
+drink form, are notified, via the *Discuss* application. The message that appears is:
+:guilabel:`(Visitor Name) just checked-in. They requested (Drink Name).`
+
+Once the drink has been delivered to the guest, the person who delivered the drink is responsible
+for marking the drink as delivered.
+
+To mark a drink as delivered, navigate to :menuselection:`Frontdesk app --> Stations`, and choose
+the desired station card displaying :guilabel:`(#) Drinks to serve`.
+
+This opens a list of all the visitors checked in at that station, and are waiting for a drink. Click
+the :guilabel:`Drink Served` button at the end of the line for the visitor who was served. Once they
+are marked as having their drink served, the visitor disappears from the list.
+
+Check out
+---------
+
+Once the visitor has completed their business, and has left the premises, it is important to check
+them out for accurate record keeping.
+
+To check visitors out properly, navigate to :menuselection:`Frontdesk app --> Stations`, and choose
+the desired station card displaying :guilabel:`(#) Drinks to serve`. Doing so opens a list of all
+the visitors who are currently checked-in at that station.
+
+Click the :guilabel:`Check out` button near the end of the line for the visitor who left. Once they
+are marked as checked-out, the visitor disappears from the list.
+
+.. important::
+   Visitors do **not** check themselves out when they leave. It is important for *Frontdesk* users
+   to check out visitors for accurate record keeping.
+
+   Always have an accurate list of who is on the premises at any given time. This is important for
+   security purposes, and in the case of an emergency.

content/applications/hr/payroll.rst

@@ -108,6 +108,10 @@ The contract template forms the basis of an offer, and can be modified for speci
 employees, when necessary. If a contract template is created or modified in the *Payroll*
 application, the changes are also reflected in the *Recruitment* application.
 
+.. important::
+   To access contract templates, the *Salary Configurator* (`hr_contract_salary`) module **must** be
+   :ref:`installed <general/install>`.
+
 To view all the current contract templates in the database, navigate to :menuselection:`Payroll app
 --> Configuration --> Contracts: Templates`.
 
@@ -383,7 +387,7 @@ by typing in the time.
    `2:00 PM` would be entered as `14:00`.
 
 If the working time should be in a two-week configuration, click the :guilabel:`Switch to 2 weeks
-calendar` button in the top left. This creates entries for an :guilabel:`Even week` and an
+calendar` button in the top-left. This creates entries for an :guilabel:`Even week` and an
 :guilabel:`Odd week`.
 
 .. image:: payroll/new-working-schedule.png
@@ -411,12 +415,13 @@ end of year bonus. Both the `Regular Pay` structure and `End of Year Bonus` stru
 within the `Employee` structure type.
 
 The different :guilabel:`Structure Types` can be seen by navigating to :menuselection:`Payroll app
---> Configuration --> Salary --> Structure Types`.
+--> Configuration --> Salary: Structure Types`.
 
-There are two default structure types configured in Odoo: :guilabel:`Employee` and
-:guilabel:`Worker`. Typically, :guilabel:`Employee` is used for salaried employees, which is why the
-wage type is :guilabel:`Monthly Fixed Wage`, and :guilabel:`Worker` is typically used for employees
-paid by the hour, so the wage type is :guilabel:`Hourly Wage`.
+Two default structure types are configured in Odoo: :guilabel:`Employee` and :guilabel:`Worker`.
+
+Typically, :guilabel:`Employee` is used for salaried employees, which is why the wage type is
+:guilabel:`Monthly Fixed Wage`, and :guilabel:`Worker` is typically used for employees paid by the
+hour, so the wage type is :guilabel:`Hourly Wage`.
 
 .. image:: payroll/structure-type.png
    :align: center

content/applications/hr/referrals.rst

@@ -1,29 +1,32 @@
+:show-content:
+
 =========
 Referrals
 =========
 
 Odoo's *Referrals* application is a centralized place where all information regarding referrals is
-housed, from points earned, coworkers hired, and rewards selected. Users can recommend people they
-know for job positions, then earn referral points as those people progress through the recruitment
-pipeline. Once enough referral points are earned, they can be exchanged for prizes. The Referrals
-application integrates with the *Employees*, *Recruitment*, and *Website* applications, all of which
-must be installed in order for the *Referrals* application to function.
+housed - from points earned, coworkers hired, and rewards selected. Users can recommend people they
+know for job positions, and then earn referral points as those people progress through the
+recruitment pipeline. Once enough referral points are earned, they can be exchanged for prizes. The
+*Referrals* application integrates with the *Employees*, *Recruitment*, and *Website* applications,
+all of which must be installed in order for the *Referrals* application to function.
 
-The only configuration needed for the Referrals application after it is installed are the
-:ref:`rewards <referrals/rewards>`; everything else is pre-configured when Odoo Referrals is
+The only configurations needed for the *Referrals* application *after* installation are related to
+the :ref:`rewards <referrals/rewards>`; everything else is pre-configured when Odoo *Referrals* is
 installed.
 
-Any user with either :guilabel:`Referral User`, :guilabel:`Officer`, or :guilabel:`Administrator`
-rights for the Recruitment application has access to the Referrals application. Only user's with
-:guilabel:`Administrator` rights for the Recruitment application have access to the :ref:`reporting
-<referrals/reporting>` and configurations menus. For more information on users and access rights,
-refer to these documents: :doc:`../general/users` and :doc:`../general/users/access_rights`.
+Users with either :guilabel:`Referral User`, :guilabel:`Officer`, or :guilabel:`Administrator`
+access rights for the *Recruitment* application have access to the *Referrals* application. Only
+users with :guilabel:`Administrator` access rights for the *Recruitment* application have access to
+the :ref:`reporting <referrals/reporting>` and configurations menus. For more information on users
+and access rights, refer to these documents: :doc:`../general/users` and
+:doc:`../general/users/access_rights`.
 
 Onboarding
 ==========
 
 When opening the *Referrals* application for the first time, a pre-configured onboarding script
-appears. This is in the form of four slides, each explaining the different parts of the Referrals
+appears. This is in the form of four slides, each explaining the different parts of the *Referrals*
 application. At the top of the dashboard, the following message is displayed throughout all the
 onboarding slides: :guilabel:`GATHER YOUR TEAM! Job Referral Program`. Behind this main message is
 an image, and beneath it some more explanatory text.
@@ -40,16 +43,16 @@ The text that appears on each slide is as follows:
 #. :guilabel:`Compete against your colleagues to build the best justice league!`
 
 .. note::
-   The onboarding slides will appear every time the Referrals application is opened, until all the
+   The onboarding slides will appear every time the *Referrals* application is opened, until all the
    slides have been viewed and the :guilabel:`Start Now` button has been clicked. If the onboarding
    is exited at any point, or if the :guilabel:`Start Now` button has *not* been clicked, the
-   onboarding slides will begin again when the Referrals application is opened. Once the
+   onboarding slides will begin again when the *Referrals* application is opened. Once the
    :guilabel:`Start Now` button has been clicked, the onboarding slides will not be seen again, and
-   the main dashboard will load when the Referrals application is opened from that point on.
+   the main dashboard will load when the *Referrals* application is opened from that point on.
 
 At any point during onboarding, the :guilabel:`Skip` button may be clicked. This exits the
-onboarding, and the main Referrals dashboard loads. If :guilabel:`Skip` is clicked, onboarding
-slides will not load anymore when opening the Referrals application.
+onboarding, and the main *Referrals* dashboard loads. If :guilabel:`Skip` is clicked, onboarding
+slides will not load anymore when opening the *Referrals* application.
 
 .. image:: referrals/onboarding.png
    :align: center
@@ -65,361 +68,37 @@ Modifying onboarding slides
 ---------------------------
 
 Onboarding slides can be modified if desired. Only users with :guilabel:`Administrator` rights for
-the Recruitment application can modify onboarding slides. To edit a slide, navigate to
+the *Recruitment* application can modify onboarding slides. To edit a slide, navigate to
 :menuselection:`Referrals app --> Configuration --> Onboarding.` Each line displays the text for the
 individual onboarding slide. To edit an onboarding slide, click on an individual slide line to open
-the slide's onboarding form, then click :guilabel:`Edit`.
+the slide's onboarding form.
 
-Make any changes to the message in the :guilabel:`Text` box. To change the order the slide appear in
-the onboarding, the :guilabel:`Sequence` can be modified. Type in the corresponding number to
-indicate the order in which the slides should be displayed. A :guilabel:`Company` may be selected,
-however, if this field is populated, that slide will only be displayed for that particular company.
+Make any changes to the message in the :guilabel:`Text` field. A :guilabel:`Company` may be
+selected, as well. However, if this field is populated, that slide is *only* displayed for that
+particular company.
 
-The image can be modified as well. Hover over the image thumbnail in the top right corner of the
+.. note::
+   The :guilabel:`Company` field only appears when in a multi-company database.
+
+The image can be modified, as well. Hover over the image thumbnail in the top-right corner of the
 form. A :guilabel:`✏️ (pencil)` icon and :guilabel:`🗑️ (garbage can)` icon appear. Click the
 :guilabel:`✏️ (pencil)` icon to change the image. A file navigator window loads. Navigate to the
 desired image, select it, then click :guilabel:`Open`. The new image appears in the thumbnail. To
 delete an image, click the :guilabel:`🗑️ (garbage can)` icon, then select a new image using the
 :guilabel:`✏️ (pencil)` icon.
 
-To save any changes, click :guilabel:`Save`, or click :guilabel:`Discard` to delete any changes and
-revert to the original content.
-
 .. image:: referrals/edit-onboarding.png
    :align: center
    :alt: An onboarding slide in edit mode, with the main fields highlighted.
 
-The order of the slides can also be changed directly in the Onboarding dashboard, without having to
-edit an individual onboarding slide. Click the up and down arrow symbol that appears after the
-checkbox and before the slide text, and drag the slide to the desired position. The
-:guilabel:`Sequence` automatically changes on all the slide's onboarding forms, reflecting the new
-sequence.
+The sequence in which the slides appear can be changed from the *Onboarding* dashboard. Click the
+:guilabel:`(six small gray boxes)` icon to the left of the the slide text, and drag the slide to the
+desired position.
 
 .. image:: referrals/onboarding-reorder.png
    :align: center
    :alt: The onboarding slides in a list, with the drag and drop arrows highlighted.
 
-Share job positions
-===================
-
-In order to earn referral points, a user must first share a job position so the applicant can apply
-for the position. There are several ways to share job positions within the Referrals application,
-through the :ref:`View Jobs <referrals/view-jobs>` button and the :ref:`Email A Friend
-<referrals/email-jobs>` button.
-
-.. _referrals/view-jobs:
-
-View Jobs
----------
-
-To see all job positions that are actively recruiting candidates, click the :guilabel:`View Jobs`
-button on the main Referrals dashboard. This presents all job positions, with each individual job
-presented in its own card.
-
-.. image:: referrals/jobs.png
-   :align: center
-   :alt: The 'View Jobs' screen, displaying all current open job positions. All information is
-         displayed on the card.
-
-Each job position card contains the following information:
-
-- The title of the job position. This information is taken from the :guilabel:`Job Position` field
-  of the job form.
-- The number of positions being recruited. This information is taken from the :guilabel:`Expected
-  New Employees` field of the :guilabel:`Recruitment` tab of the job form.
-- The points a user will earn when an applicant applies for the position.
-- The job description detailing the job position. This information is taken from the :guilabel:`Job
-  Position` tab of the job form.
-
-To see all the details for a job position, click the :guilabel:`More Info` button on the specific
-card. This opens the job position webpage in a new browser tab. This is what an applicant sees
-before applying for a position.
-
-.. note::
-   Only published job positions will be visible in the Referrals app. To check which job positions
-   are published or not, refer to the :doc:`recruitment/new_job` documentation.
-
-Refer friends
--------------
-
-To share a job position with someone, click the :guilabel:`Refer Friend` button on the specific job
-position card. A pre-configured :guilabel:`Send Job Offer by Mail` email pop-up window appears.
-Enter the recipient's email address in the :guilabel:`Email` field.
-
-The subject and body are populated using a default template. The subject `Job for you` appears, and
-can be modified if desired.
-
-The specific title of the job position will populate the :guilabel:`Job Position` placeholder in the
-email body. The `See Job Offer` text in the email body is an individualized tracking link to the
-specific job position listed on the website. When the prospective employee receives the email, the
-link will send them to the job position page, where they can apply for the position, and the person
-who referred them is tracked in the Referrals application.
-
-If desired, add any text or closing salutation to the email body. When all edits have been made,
-click :guilabel:`Send Email` to send the email, or click :guilabel:`Cancel` to close the email
-pop-up window.
-
-.. image:: referrals/email.png
-   :align: center
-   :alt: Referral email pop-up window with the email message inside it.
-
-Share a job
------------
-
-There are several other ways to share a job position aside from sending an email, via social media
-platforms and tracking links to the job position. At the bottom of each job position card are four
-icons and corresponding tracking links that can be used to share the job position, keeping track of
-applicants in the Referrals application.
-
-.. image:: referrals/share.png
-   :align: center
-   :alt: The various sharing icons that appear for each job.
-
-Link
-~~~~
-
-To share the job position with a customized tracking link, click the :guilabel:`Share Now` button
-with the :guilabel:`🔗 (chain)` icon inside it. A :guilabel:`Link to Share` pop-up window appears
-with the tracking link. Click :guilabel:`Copy` to copy the link. After the link is copied, click the
-:guilabel:`Close` button to close the pop-up. Next, share the link with the prospective employee
-however desired.
-
-Facebook
-~~~~~~~~
-
-To share the job position using Facebook, click the :guilabel:`Share Now` button with the
-:guilabel:`f (Facebook icon)` inside it. If the user is already logged into Facebook, when the
-:guilabel:`f (Facebook icon)` is clicked, a :guilabel:`Share on Facebook` page loads in a new tab,
-with the link populated in the main body of the new post. If the user is *not* already logged in, a
-log-in screen loads instead, prompting the user to log-in to Facebook first.
-
-Type in any additional information to add to the post, in the space directly below your name. If
-desired, :guilabel:`tag` users, :guilabel:`check-in` at a location, or add a :guilabel:`status` to
-the post. To tag a user, click the :guilabel:`Tag Friends` icon and select the people to tag to the
-post. To add a check-in location, click the :guilabel:`Check in` icon, and select the location from
-the pop-up of predetermined locations based on your current location. To add a :guilabel:`status`,
-click the :guilabel:`Feeling/Activity` icon, then select either the feeling or the activity type,
-and lastly, if an activity type was selected, select the specific activity.
-
-There are five methods to share the job position, :guilabel:`Your Story`, :guilabel:`Share on a
-Friend's Timeline`, :guilabel:`Share in a Group`, :guilabel:`Share in an Event`, and
-:guilabel:`Share in a Private Message`. To select the sharing method, click the drop-down menu
-located at the top of the page, directly beneath the :guilabel:`Share on Facebook` banner.
-
-.. image:: referrals/facebook.png
-   :align: center
-   :alt: The view on Facebook when sharing a job description. All the various ways to share are
-         highlighted, as are all the required settings.
-
-.. tabs::
-
-   .. tab:: Share to news feed or story
-
-      The default sharing method is through the :guilabel:`News Feed`, :guilabel:`Story`, or both.
-      At the lower portion of the form are radio buttons next to the two options, :guilabel:`Feed`
-      (for the News Feed) and :guilabel:`Your Story` for stories. When :guilabel:`Share to News Feed
-      or Story` is selected, these buttons are active, if another option is selected, these radio
-      buttons are greyed out. Activate the radio button(s) to indicate how the job position should
-      be shared, either in the news feed, the story, or both.
-
-      The :guilabel:`Share to news feed or story` option allows for specific privacy settings to be
-      selected. In the lower right corner of the screen, there are two drop-down menu options, one
-      for the :guilabel:`Feed` option, the other for the :guilabel:`Your story` option. Select the
-      posting parameters from the drop-down menus. The :guilabel:`Feed` ad :guilabel:`Your story`
-      options appear different from user to user, depending on what privacy settings have been
-      created in Facebook. :guilabel:`Public` and :guilabel:`Friends` are default options, but other
-      options that the user may have configured will appear as well, such as custom groups.
-
-      When the post and/or story is ready to be shared, click the blue :guilabel:`Post to Facebook`
-      button at the bottom of the screen.
-
-   .. tab:: Share on a friend's timeline
-
-      Instead of making a public post on the user's on Facebook page, the job position can be shared
-      directly on a friend's timeline. Click the :guilabel:`Share to News Feed or Story` drop-down
-      menu near the top of the page, and select :guilabel:`Share on a Fried's Timeline`.
-
-      When selected, a :guilabel:`Friend` field appears below the selection. Begin to type in the
-      friend's name. As the name is typed, a list appears, populated with names that match what is
-      entered. Select the friend from the list. **Only** one friend can be selected.
-
-      When the post is ready to be shared, click the blue :guilabel:`Post to Facebook` button at the
-      bottom of the screen.
-
-   .. tab:: Share in a group
-
-      To reach a specific audience and not share the job position publicly with everyone, a job can
-      be shared in a group. Click the :guilabel:`Share to News Feed or Story` drop-down menu near
-      the top of the page, and select :guilabel:`Share in a Group`.
-
-      When selected, a :guilabel:`Group` field appears below the selection. The available groups
-      that can be posted to are groups the user is currently a member of. Job positions cannot be
-      shared with groups the user has not joined. Begin to type in the name of the group. As the
-      group name is typed, a list appears, populated with the group names that match what is
-      entered. Select the group from the list. Only one group can be selected.
-
-      When the post is ready to be shared, click the blue :guilabel:`Post to Facebook` button at the
-      bottom of the screen.
-
-   .. tab:: Share in an event
-
-      A job position can also be shared on an event page. Click the :guilabel:`Share to News Feed or
-      Story` drop-down menu near the top of the page, and select :guilabel:`Share in an Event`.
-
-      When selected, an :guilabel:`Event` field appears below the selection. The available events
-      that can be posted to are events the user is invited to. This includes events that the user
-      has not responded to yet, and events that have occurred in the past. Begin to type in the name
-      of the event. As the event name is typed, a list appears, populated with the events that match
-      what is entered. Select the event from the list. Only one event can be selected.
-
-      When the post is ready to be shared, click the blue :guilabel:`Post to Facebook` button at the
-      bottom of the screen.
-
-   .. tab:: Share in a private message
-
-      The last option is to share a job position privately instead of publicly, in a Facebook
-      message. Click the :guilabel:`Share to News Feed or Story` drop-down menu near the top of the
-      page, and select :guilabel:`Share in an Private Message`.
-
-      When selected, a :guilabel:`To` field appears below the selection. Begin to type in the
-      friend's name. As the name is typed, a list appears, populated with names that match what is
-      entered. Select the friend from the list. Multiple friends can be selected and added to a
-      single message. Repeat this process for each friend to be added.
-
-      When the message is ready to be sent, click the blue :guilabel:`Send message` button at the
-      bottom of the screen.
-
-X/Twitter
-~~~~~~~~~
-
-A job position can also be shared on X/Twitter. Click the :guilabel:`Share Now` button with the bird
-icon inside it. If the user is already signed in to X/Twitter, when the :guilabel:`Share Now` icon
-is clicked, an X/Twitter page loads in a new tab with a pre-populated message ready to post, in a
-draft pop-up. If the user is *not* already signed in, a sign-in screen loads instead, prompting the
-user to sign in to X/Twitter.
-
-The default message is:
-
-:guilabel:`Amazing job offer for (Job Position)! Check it live: (link to Job Position)`
-
-Type in any additional information or make any edits to the message. If desired, click the
-:guilabel:`X` in the top left corner of the thumbnail preview of the webpage to remove it. To adjust
-the audience for the message, click the drop-down button labeled :guilabel:`Everyone`. Select the
-preferred audience from the drop-down menu. The default option is :guilabel:`Everyone`, and the
-other options is :guilabel:`Circle`. The :guilabel:`Circle` is a group of people that the user has
-selected in X/Twitter.
-
-The default setting is :guilabel:`🌎 (globe) Everyone can reply`, an allows everyone on X/Twitter to
-reply to the message. To change this, click the :guilabel:`🌎 (globe) Everyone can reply` button in
-the lower left section of the message. There are four options presented: :guilabel:`Everyone`,
-:guilabel:`Accounts you follow`, :guilabel:`Verified accounts`, and :guilabel:`Only accounts you
-mention`. Selecting one of the other options restricts who can reply to the message.
-
-There are various other items that can be added to the message. Media (photos, videos, etc), GIF's,
-polls, emojis, and a location may all be added. Click the corresponding icon in the bottom left of
-the message and follow the prompts to add the desired additional elements.
-
-To have the message posted at a future date and time, click the :guilabel:`Schedule` icon in the
-lower left of the message window. It is the fifth icon from the left. Enter the date and time that
-the message should be posted using the date and time selector presented. Click :guilabel:`Confirm`
-to add the scheduled time to the message.
-
-To post the message, click :guilabel:`Post`. The message will be immediately posted, or, if it was
-scheduled, will be posted at the scheduled date and time.
-
-.. image:: referrals/twitter.png
-   :align: center
-   :alt: The X/Twitter pop-up when sharing a job description. All the other items than can be added
-         to the message are highlighted, as is the visibility setting and the post button.
-
-LinkedIn
-~~~~~~~~
-
-To share a job position on LinkedIn, click the :guilabel:`Share Now` button with the :guilabel:`in
-(LinkedIn logo)` inside it. If the user is already logged into LinkedIn, when the :guilabel:`Share
-Now` button is clicked, a new tab loads in LinkedIn, with a link to the job position at the top. If
-the user is *not* already logged in, a log-in screen loads instead, prompting the user to log-in to
-LinkedIn first.
-
-The job position can be shared either in a public post, or in a private message to an individual or
-group of individuals.
-
-Share in a post
-***************
-
-To share the job position in a public post, click the :guilabel:`✏️ (pencil) Share in a post` button
-in the lower-left corner of the screen. A :guilabel:`Create a post` window loads, with the job
-position link populated. Enter any other information to the post in the field.
-
-To change the audience that will see the post, click the :guilabel:`🌎 (globe) Anyone` drop-down,
-located directly beneath the account name. Click on the desired selection, then click the
-:guilabel:`Save` button on the far right side of the screen, beneath the last listed option.
-
-:guilabel:`Anyone` allows anyone on LinkedIn to see the post. :guilabel:`Connections only` will
-only share the post with people who are connected with the user, and will be hidden from everyone
-else. :guilabel:`Group` shares the post with a specific group the user is a member of. The post can
-only be shared with one group; posting to multiple groups at once is not available. If
-:guilabel:`Group` is selected, a page loads with a list of all the groups the user is currently a
-member of. Click on a group to select it, then click the :guilabel:`Save` button in the lower right
-corner.
-
-Next, select who can comment on the post. To change this setting, click on the :guilabel:`💬 (speech
-bubble) Anyone` button located beneath the body of the post. A page loads with the various options.
-Click on one of the three options to select it. The three options are :guilabel:`Anyone`,
-:guilabel:`Connections only`, and :guilabel:`No one`. The default option is :guilabel:`Anyone`,
-which allows anyone with a LinkedIn account to comment on the post. :guilabel:`Connections only`
-will only allow people who are connected with the user to comment on the post. :guilabel:`No one`
-turns off commenting. After making a selection, click the :guilabel:`Save` button in the far lower
-right corner.
-
-Finally, once the post is edited and the settings have been selected, click :guilabel:`Post` to
-share the job position.
-
-.. image:: referrals/linkedin.png
-   :align: center
-   :alt: A linkedIn post to share a job. The job position is highlighted as is the post button.
-
-Send as private message
-***********************
-
-Instead of making a public post, the post can be sent to a connection in a private message. To do
-so, click the :guilabel:`Send as private message` button in the lower left corner. A message window
-loads with the link to the job description in the bottom of the window. First, select the
-recipient(s) for the message. Type the name in the :guilabel:`Search for message recipients` field.
-As the name is typed in, any matching connections appear. Click on a connection to add them. Repeat
-this for all the recipients to send the message to. There is no limit on the number of connections
-that can be messaged. Next, enter any additional text in the message body. Click :guilabel:`Send` in
-the lower right corner to send the message. A :guilabel:`Message successfully sent!` screen loads.
-Two options are presented, :guilabel:`View Message` and :guilabel:`Continue to LinkedIn`. Click on
-the desired selection to navigate to that choice, or close the browser tab to exit.
-
-.. _referrals/email-jobs:
-
-Email a friend
---------------
-
-Another way to share job opportunities is to share the entire current list of open job positions
-instead of one job position at a time. To do this, navigate to the main *Referrals* app dashboard.
-Click the :guilabel:`Email a friend` button at the bottom of the screen. A :guilabel:`Send Job Offer
-by Mail` pop-up window appears.
-
-Enter the email address(es) in the :guilabel:`Email` line. The email can be sent to multiple
-recipients, simply enter a comma followed by a single space after each email address. The
-:guilabel:`Subject` is pre-configured with `Job for you`, but can be edited.
-
-The email body is also populated with pre-configured text. The text that appears is:
-
-`Hello,`
-
-`There are some amazing job offers in my company! Have a look, they can be interesting for you`
-
-`See Job Offers`
-
-The `See Job Offers` text is a tracking link to a complete list of all job positions currently being
-recruited for, that are live on the company's website (published). Add any additional text and/or
-make any edits to the message body, then click :guilabel:`Send Mail` to send the email. The message
-will be sent and the window will close.
-
 .. _referrals/hired:
 
 Hired referrals
@@ -433,10 +112,10 @@ dashboard, a hired page loads. The text :guilabel:`(Referral Name) has been hire
 for your new friend!` appears.
 
 Below this message are five avatar thumbnails to choose from. If an avatar has already been assigned
-to a referral, the thumbnail is greyed out, and the name the avatar has been chosen for appears
+to a referral, the thumbnail is grayed out, and the name that the avatar has been chosen for appears
 beneath the avatar. Click on an available avatar to select it.
 
-If more than one referral was hired since opening the Referrals application, after selecting the
+If more than one referral was hired since opening the *Referrals* application, after selecting the
 first avatar, the user is prompted to select another avatar for the subsequent hired referral. Once
 all avatars have been selected, the dashboard loads and all the avatars are now visible. Mouse over
 each avatar and their name is displayed above them.
@@ -450,8 +129,8 @@ Modify friends
 --------------
 
 Friend avatars are able to be modified in the same manner that :ref:`levels <referrals/levels>` are
-modified. Only users with :guilabel:`Administrator` rights for the Recruitment application can make
-modifications to friends. The pre-configured friends can be seen and modified by navigating to
+modified. Only users with :guilabel:`Administrator` rights for the *Recruitment* application can
+make modifications to friends. The pre-configured friends can be seen and modified by navigating to
 :menuselection:`Referrals app --> Configuration --> Friends`. Each friend avatar appears in the
 :guilabel:`Dashboard Image` column, and the corresponding name appears in the :guilabel:`Friend
 Name` column. The default images are a motley group of hero characters, ranging from robots to dogs.
@@ -459,7 +138,7 @@ Name` column. The default images are a motley group of hero characters, ranging
 To modify a friend's dashboard image, thumbnail, name, or position, click on an individual friend to
 open the referral friend form. Click :guilabel:`Edit` to make modifications. Type the name in the
 :guilabel:`Friend Name` field. The name is solely to differentiate the friends in the configuration
-menu; the friend's name is not visible anywhere else in the Referrals application.
+menu; the friend's name is not visible anywhere else in the *Referrals* application.
 
 The :guilabel:`Position` can be set to either :guilabel:`Front` or :guilabel:`Back`. This determines
 the position of the friend in relation to the user's super hero avatar. Click the radio button next
@@ -468,11 +147,13 @@ when activated.
 
 If desired, both the thumbnail :guilabel:`Image` and the :guilabel:`Dashboard Image` can be
 modified. Hover over the image being replaced to reveal a :guilabel:`✏️ (pencil)` icon and
-:guilabel:`🗑️ (garbage can)` icon. Click the :guilabel:`✏️ (pencil)` icon and a file explorer
-window appears. Navigate to the desired image file then click :guilabel:`Open` to select it.
+:guilabel:`🗑️ (garbage can)` icon. Click the :guilabel:`✏️ (pencil)` icon, and a file explorer
+window appears. Navigate to the desired image file, then click :guilabel:`Open` to select it.
 
-Once all changes have been made, click the :guilabel:`Save` button to save the changes, or click the
-:guilabel:`Discard` button to revert to the original information.
+The referral friend form automatically saves, but can be saved manually at any time by clicking the
+*Save manually* option, represented by a :guilabel:`(cloud upload)` icon, located in the top-left
+corner. To cancel any changes made, click the :guilabel:`✖️ (Discard all changes)` icon to delete
+any changes, and revert to the original content.
 
 .. image:: referrals/edit-friend.png
    :align: center
@@ -481,17 +162,17 @@ Once all changes have been made, click the :guilabel:`Save` button to save the c
 .. warning::
    It is not advised to edit the images. An image file must have a transparent background in order
    for it to render properly. Only users with knowledge about transparent images should attempt
-   adjusting any images in the Referrals application.
+   adjusting any images in the *Referrals* application.
 
    Once an image is changed and the friend is saved, it is **not possible** to revert to the
-   original image. To revert to the original image, the Referrals application must be *uninstalled
+   original image. To revert to the original image, the *Referrals* application must be *uninstalled
    then reinstalled.*
 
 Referral points
 ===============
 
 The referral program is based on earning points that are then exchanged for rewards. On the main
-Referrals application dashboard, the top displays a summary of the user's current points. The left
+*Referrals* application dashboard, the top displays a summary of the user's current points. The left
 side of the summary displays the total points earned, and the right side displays the points that
 are available to spend.
 
@@ -516,12 +197,18 @@ To see all the referrals (both ongoing and successful) click the :guilabel:`Refe
 :guilabel:`My Referral` window loads. This screen displays all the referrals, with each referral in
 its own referral card.
 
-A successful referral has a green line down the left side of the card, and displays a
-:guilabel:`✓ Hired` image in the top right corner of the card. Referrals that are in process display
-an :guilabel:`In Progress` image in the top right corner.
+A successful referral displays a green :guilabel:`Hired` banner in the top-right corner of the card.
+Referrals that are in process display a purple :guilabel:`In Progress` banner in the top-right
+corner.
 
-Each referral card lists the name of the applicant, the department the job position is in, the name
-of the job position, the person responsible for filling the role (recruiter), and the points earned.
+Each referral card lists the name of the applicant, the subject/application title (as it appears on
+the applicant card in the *Recruitment* app), the name of the job position, the person responsible
+for filling the role (recruiter), and the points earned. For referrals that have been hired, the
+selected avatar also appears on the card.
+
+.. image:: referrals/referrals.png
+   :align: center
+   :alt: Two referral cards, one hired and one in-progress.
 
 Points
 ~~~~~~
@@ -548,7 +235,7 @@ check mark appears next to the stage.
    - :guilabel:`Contract Signed`: 50 points
 
    The total points earned for a referral that is hired is 85 points. Modifications of the points
-   earned for each stage is done in the Recruitment application. Refer to the
+   earned for each stage are done in the *Recruitment* application. Refer to the
    :ref:`Recruitment <recruitment/modify-stages>` documentation to modify the points for each stage.
 
 .. _referrals/rewards:
@@ -559,27 +246,28 @@ Rewards
 Create rewards
 --------------
 
-The rewards are the only configurations needed when setting up the Referrals application. Only users
-with :guilabel:`Administrator` rights for the Recruitment application can create or modify rewards.
-To add rewards, navigate to :menuselection:`Referrals app --> Configuration --> Rewards`. Click
-:guilabel:`Create` and a reward form loads. Enter the following information on the form:
+The rewards are the only configurations needed when setting up the *Referrals* application. Only
+users with :guilabel:`Administrator` rights for the *Recruitment* application can create or modify
+rewards. To add rewards, navigate to :menuselection:`Referrals app --> Configuration --> Rewards`.
+Click :guilabel:`New`, and a reward form loads. Enter the following information on the form:
 
-- :guilabel:`Product Name`: Enter the name as it should appear for the reward.
-- :guilabel:`Cost`: Enter the amount of points required to redeem the reward.
-- :guilabel:`Company`: Using the drop-down menu, select the company the reward will appear for. If a
+- :guilabel:`Product Name`: enter the name as it should appear for the reward.
+- :guilabel:`Cost`: enter the amount of points required to redeem the reward.
+- :guilabel:`Company`: using the drop-down menu, select the company the reward appears for. If a
   reward is to be used for several companies, each company needs to have a record of the reward,
-  with the company listed on the form.
-- :guilabel:`Gift Responsible`: Select the person who will be responsible for procuring and
+  with the company listed on the form. This field only appears if in a multi-company environment.
+- :guilabel:`Gift Responsible`: select the person who will be responsible for procuring and
   delivering the reward to the recipient, using the drop-down menu. This person is alerted when the
-  reward is purchased, so they know when to deliver the reward to the recipient.
-- :guilabel:`Description`: Type in the description for the reward. This will be visible on the
+  reward is bought in the *Referrals* application, so they know when to deliver the reward to the
+  recipient.
+- :guilabel:`Description`: type in the description for the reward. This will be visible on the
   reward card, beneath the title.
-- :guilabel:`Photo`: Add a photo of the reward, which appears on the rewards page. Hover over the
+- :guilabel:`Photo`: add a photo of the reward, which appears on the rewards page. Hover over the
   image square, and two icons appear, a :guilabel:`✏️ (pencil)` and a :guilabel:`🗑️ (garbage can)`.
-  Click the :guilabel:`✏️ (pencil)` icon and a file explorer appears. Navigate to the photo file,
+  Click the :guilabel:`✏️ (pencil)` icon, and a file explorer appears. Navigate to the photo file,
   then click :guilabel:`Open` to select it.
 
-The only required fields are the :guilabel:`Product Name`, :guilabel:`Company`, and
+The only required fields are the :guilabel:`Product Name`, :guilabel:`Company` (if applicable), and
 :guilabel:`Description`.
 
 .. image:: referrals/rewards.png
@@ -596,14 +284,15 @@ Redeem rewards
 
 To redeem points for a reward, click the :guilabel:`Rewards` button on the main Referrals dashboard.
 All the configured rewards are listed in individual reward cards. The points required to purchase
-the reward is listed in the top right corner of the card. If the user has enough points to purchase
+the reward is listed in the top-right corner of the card. If the user has enough points to purchase
 a reward, a :guilabel:`🧺 (basket) Buy` button appears at the bottom of the reward card. If they do
 not have enough points for a reward, the reward card displays :guilabel:`You need another (x) points
 to buy this` instead of a buy button.
 
-Click the :guilabel:`🧺 (basket) Buy` button on a reward to purchase it. A confirmation pop-up
-appears, asking if the user is sure they want to purchase the reward. Click :guilabel:`OK` to
-purchase the item, or :guilabel:`Cancel` to close the window and cancel the purchase.
+Click the :guilabel:`🧺 (basket) Buy` button on a reward to purchase it. A :guilabel:`Confirmation`
+pop-up window appears, asking if the user is sure they want to purchase the reward. Click
+:guilabel:`OK` to purchase the item, or :guilabel:`Cancel` to close the window and cancel the
+purchase.
 
 After :guilabel:`OK` is clicked, the pop-up window closes, and the points used to purchase the
 reward are subtracted from the user's available points. The rewards presented are now updated to
@@ -619,14 +308,14 @@ reflect the user's current available points.
 Levels
 ======
 
-The referrals application has pre-configured levels that are reflected in the user's avatar on the
+The *Referrals* application has pre-configured levels that are reflected in the user's avatar on the
 Referrals dashboard. As a user refers potential employees and earns points, they can *level up*,
 much like in a video game.
 
 Levels have no functional impact on the performance of the application. They are solely used for the
 purpose of adding achievement tiers for participants to aim for, gamifying referrals for the user.
 
-The user's current level is displayed at the top of the main Referrals application dashboard,
+The user's current level is displayed at the top of the main *Referrals* application dashboard,
 directly beneath their photo, in a :guilabel:`Level: X` format. In addition, a colored ring appears
 around the user's photo, indicating how many points the user currently has, and how many additional
 points they need to level up. The cyan colored portion of the ring represents points earned, while
@@ -635,17 +324,17 @@ the white colored portion represents the points still needed before they can lev
 Modify levels
 -------------
 
-Only users with :guilabel:`Administrator` rights for the Recruitment application can modify levels.
-The pre-configured levels can be seen and modified by navigating to :menuselection:`Referrals app
---> Configuration --> Levels`. Each avatar appears in the :guilabel:`Image` column, and the
-corresponding level number appears in the :guilabel:`Level Name` column. The default images are of
-Odoo superheroes, and each level adds an additional element to their avatar, such as capes and
-shields.
+Only users with :guilabel:`Administrator` rights for the *Recruitment* application can modify
+levels. The pre-configured levels can be seen and modified by navigating to
+:menuselection:`Referrals app --> Configuration --> Levels`. Each avatar appears in the
+:guilabel:`Image` column, and the corresponding level number appears in the :guilabel:`Level Name`
+column. The default images are of Odoo superheroes, and each level adds an additional element to
+their avatar, such as capes and shields.
 
 To modify a level's image, name, or points required to reach the level, click on an individual level
-in the list to open the level form. Click :guilabel:`Edit` to make modifications.
+in the list to open the level form, then make modifications.
 
-Type in the name or number of the level in the :guilabel:`Level Name` field. What is entered is
+Type in the name (or number) of the level in the :guilabel:`Level Name` field. What is entered is
 displayed beneath the user's photo on the main dashboard when they reach that level. Enter the
 number of referral points needed to reach that level in the :guilabel:`Requirements` field. The
 points needed to level up are the total accumulated points earned over the lifetime of the employee,
@@ -653,11 +342,13 @@ not additional points from the previous level that must be earned.
 
 If desired, the :guilabel:`Image` can also be modified. Hover over the image to reveal a
 :guilabel:`✏️ (pencil)` icon and :guilabel:`🗑️ (garbage can)` icon. Click the :guilabel:`✏️
-(pencil)` icon and a file explorer window appears. Navigate to the desired image file then click
+(pencil)` icon, and a file explorer window appears. Navigate to the desired image file, then click
 :guilabel:`Open` to select it.
 
-Once all changes have been made, click the :guilabel:`Save` button to save the changes, or click the
-:guilabel:`Discard` button to revert to the original information.
+The level form saves automatically, but can be saved manually at any time by clicking the *save
+manually* option, represented by a :guilabel:`(cloud upload)` icon, located in the top-left corner.
+To cancel any changes made, click the :guilabel:`✖️ (Discard all changes)` icon to delete any
+changes, and revert to the original content.
 
 .. image:: referrals/levels.png
    :align: center
@@ -666,10 +357,10 @@ Once all changes have been made, click the :guilabel:`Save` button to save the c
 .. warning::
    It is not advised to edit the images. An image file must have a transparent background in order
    for it to render properly. Only users with knowledge about transparent images should attempt
-   adjusting any images in the Referrals application.
+   adjusting any images in the *Referrals* application.
 
    Once an image is changed and the level is saved, it is **not possible** to revert to the original
-   image. To revert to the original image, the Referrals application must be *uninstalled then
+   image. To revert to the original image, the *Referrals* application must be *uninstalled then
    reinstalled.*
 
 Level up
@@ -700,7 +391,7 @@ points required.
 Alerts
 ======
 
-In the Referrals application, it is possible to post a message, also referred to as an *alert*, at
+In the *Referrals* application, it is possible to post a message, also referred to as an *alert*, at
 the top of the dashboard to share important information with users. These alerts appear as a thin
 semi-transparent banner, with the word :guilabel:`New!` appearing on the far left. The text for the
 alert is in the center of the banner, and on the far right side is an :guilabel:`X`.
@@ -708,7 +399,7 @@ alert is in the center of the banner, and on the far right side is an :guilabel:
 Alerts appear on the main dashboard for the specified time configured on the individual alert. If a
 user does not wish to see a specific alert again, click the :guilabel:`X` in the far right side of
 the alert. This removes the alert from the dashboard and will not appear again, even when opening
-the Referrals application for the first time in a new session.
+the *Referrals* application for the first time in a new session.
 
 .. image:: referrals/alerts.png
    :align: center
@@ -717,29 +408,29 @@ the Referrals application for the first time in a new session.
 Create an alert
 ---------------
 
-Only users with :guilabel:`Administrator` rights for the Recruitment application can create alerts.
-To add a new alert, navigate to the :menuselection:`Referrals application --> Configuration -->
-Alerts`.
+Only users with :guilabel:`Administrator` rights for the *Recruitment* application can create
+alerts. To add a new alert, navigate to the :menuselection:`Referrals application --> Configuration
+--> Alerts`.
 
 Click :guilabel:`Create` and a blank alert form loads. Enter the following information on the form:
 
-- :guilabel:`Date From`: The date the alert starts. On this date, the alert will be visible on the
+- :guilabel:`Date From`: the date the alert starts. On this date, the alert will be visible on the
   dashboard.
-- :guilabel:`Date To`: The date the alert ends. After this date, the alert will be hidden from view.
-- :guilabel:`Company`: The current company populates this field by default. To modify the company
+- :guilabel:`Date To`: the date the alert ends. After this date, the alert will be hidden from view.
+- :guilabel:`Company`: the current company populates this field by default. To modify the company
   the alert should be displayed for, select the company from the drop-down menu. If this field
-  remains blank, the alert is visible to everyone with access to the Referrals application. If a
-  company is specified, only user's within that company (who also have access to the Referrals
-  application) will see the alert.
-- :guilabel:`Alert`: Enter the text for the alert. This message appears inside the alert banner on
+  remains blank, the alert is visible to everyone with access to the *Referrals* application. If a
+  company is specified, only user's within that company (who also have access to the *Referrals*
+  application) will see the alert. This field only appears when in a multi-company database.
+- :guilabel:`Alert`: enter the text for the alert. This message appears inside the alert banner on
   the main dashboard.
-- :guilabel:`On Click`: There are three options for the alert. Click the radio button next to the
+- :guilabel:`On Click`: there are three options for the alert. Click the radio button next to the
   desired selection. The options are:
 
-  - :guilabel:`Not Clickable`: The alert only displays text, there is no link to click.
-  - :guilabel:`Go to All Jobs`: The alert contains a link that when clicked, navigates to the
+  - :guilabel:`Not Clickable`: the alert only displays text, there is no link to click.
+  - :guilabel:`Go to All Jobs`: the alert contains a link that when clicked, navigates to the
     website with all the currently posted job positions.
-  - :guilabel:`Specify URL`: The alert contains a link to a specific URL, that when clicked,
+  - :guilabel:`Specify URL`: the alert contains a link to a specific URL, that when clicked,
     navigates to that URL. When selected, a :guilabel:`URL` field appears below the :guilabel:`On
     Click` section. Enter the URL in the field.
 
@@ -752,9 +443,10 @@ Click :guilabel:`Create` and a blank alert form loads. Enter the following infor
 Reporting
 =========
 
-Only users with :guilabel:`Administrator` rights for the Recruitment application have access to the
-Reporting feature in Referrals. To access the reports, click :menuselection:`Referrals application
---> Reporting`. The main view is the Reporting Dashboard view, which contains three sections.
+Only users with :guilabel:`Administrator` rights for the *Recruitment* application have access to
+the Reporting feature in *Referrals*. To access the reports, click :menuselection:`Referrals
+application --> Reporting`. The main view is the Reporting Dashboard view, which contains three
+sections.
 
 In the top portion of the window, the report displays a bar chart of how many referred candidates
 are hired, and how many are still in the hiring pipeline. The candidates are further divided by
@@ -775,4 +467,11 @@ spreadsheet from the drop-down menu, or select :guilabel:`New Spreadsheet`. Clic
 
 .. note::
    The spreadsheet is stored in the *Documents* application. This application needs to be installed
-   in order to use the :guilabel:`Insert in Spreadsheet` option.
+   to use the :guilabel:`Insert in Spreadsheet` option.
+
+.. seealso::
+   :doc:`referrals/share_jobs`
+
+.. toctree::
+
+   referrals/share_jobs