[IMP] productivity: microsoft calendar rewrite

closes odoo/documentation#8780

Signed-off-by: Samuel Lieber (sali) <sali@odoo.com>

content/applications/productivity/calendar/outlook.rst

@@ -2,76 +2,142 @@
 Outlook Calendar synchronization
 ================================
 
-Synchronizing a user's Outlook Calendar with Odoo is useful for keeping track of their tasks and
+Synchronizing a user's *Outlook Calendar* with Odoo is useful for keeping track of tasks and
 appointments across all related applications.
 
 .. seealso::
-   - :doc:`/applications/general/users/azure`
-   - :doc:`/applications/general/email_communication/azure_oauth`
+   - :doc:`../../general/users/azure`
+   - :doc:`../../general/email_communication/azure_oauth`
 
-Register the application with Microsoft Azure
-=============================================
+Microsoft Azure setup
+=====================
 
-To sync the Outlook Calendar with Odoo's Calendar, a Microsoft Azure account is needed. Creating an
-account is free for users who have never tried or paid for Azure. For more information, `click here
+To sync the *Outlook Calendar* with Odoo's *Calendar*, a Microsoft *Azure* account is required.
+Creating an account is free for users who have never tried, or paid for, *Azure*. For more
+information, view the account options on the `Azure website
 <https://azure.microsoft.com/en-us/free/?WT.mc_id=A261C142F>`_.
 
 Refer to `Microsoft's documentation <https://docs.microsoft.com/en-us/azure/active-directory/
-develop/quickstart-create-new-tenant>`_ on how to set up an Microsoft Entra ID (formally called
-*Microsoft Azure Active Directory (Azure AD)*), which is a representation of an organization to
-manage and register apps.
+develop/quickstart-create-new-tenant>`_ on how to set up a Microsoft *Entra ID* (formally called
+Microsoft *Azure Active Directory (Azure AD)*). This is an API console to manage and register
+Microsoft applications.
 
-Then, `Register an Application <https://docs.microsoft.com/en-us/azure/active-directory/develop/
-quickstart-register-app>`_, choosing the appropriate :guilabel:`Supported account type`. Users who
-wish to connect their Outlook calendar to Odoo should select the :guilabel:`Accounts in any
-organizational directory (Any Microsoft Entra ID directory - Multitenant) and personal Microsoft
-accounts (e.g. Skype, Xbox)` option for :guilabel:`Supported account types`.
+Existing Microsoft *Entra ID* users should log in at the `Microsoft Azure developer portal
+<https://portal.azure.com/#home>`_. Next, select :guilabel:`View` under the section labeled
+:guilabel:`Manage Microsoft Entra ID`.
 
-When configuring the :guilabel:`Redirect URI`, choose :guilabel:`Web` and copy the Odoo database
-URI (URL) followed by `/microsoft_account/authentication`.
+Register application
+--------------------
+
+After logging in with the Microsoft *Entra ID*, `register an application
+<https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app>`_.
+
+To create an application, click :guilabel:`+ Add` in the top menu. From the resulting drop-down
+menu, select :guilabel:`App Registration`.
+
+.. image:: outlook/app-register.png
+   :align: center
+   :alt: Microsoft Azure management page with + Add and App Registration menu highlighted.
+
+Enter a unique :guilabel:`Name` for the connected application.
+
+Choosing the appropriate :guilabel:`Supported account type` is essential, or else the connected
+application will not work. Users who wish to connect their *Outlook Calendar* to Odoo should select
+the :guilabel:`Accounts in any organizational directory (Any Microsoft Entra ID directory -
+Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)` option for :guilabel:`Supported
+account types`.
+
+When configuring the :guilabel:`Redirect URI`, choose the :guilabel:`Web` option from the first
+drop-down menu. Then, enter the Odoo database URI (URL) followed by
+`/microsoft_account/authentication`.
 
 .. example::
-   Enter `https://www.companyname.odoo.com/microsoft_account/authentication` for the
-   :guilabel:`Redirect URI`.
+   Enter `https://yourdbname.odoo.com/microsoft_account/authentication` for the :guilabel:`Redirect
+   URI`. Replace `yourdbname.odoo.com` with the :abbr:`URL (Uniform Resource Locator)`.
+
+.. tip::
+   Ensure the database's :abbr:`URL (Uniform Resource Locator)` (domain) used in the URI is the
+   exact same domain as the one configured on the `web.base.url` system parameter.
+
+   Access the `web.base.url` by activating :ref:`developer mode <developer-mode>`, and navigating to
+   :menuselection:`Settings app --> Technical header menu --> Parameters section --> System
+   Parameters`. Then, select it from the :guilabel:`Key` list on the :guilabel:`System Parameters`
+   page.
 
 .. image:: outlook/azure-register-application.png
    :align: center
    :alt: The "Supported account type" and "Redirect URI" settings in the Microsoft Entra ID portal.
 
-For more information on the restrictions and limitations of URIs, `check this page <https://docs.
-microsoft.com/en-us/azure/active-directory/develop/reply-url>`_.
+For more information on the restrictions and limitations of URIs, check Microsoft's `Redirect URI
+(reply URL) restrictions and limitations
+<https://docs.microsoft.com/en-us/azure/active-directory/develop/reply-url>`_ page.
 
-Regarding the application credentials, the user *must* add a client secret, which allows Odoo to
-authenticate itself, requiring no interaction from the user's side. :guilabel:`Certificates` are
-optional.
+Finally, on the application registration page, click :guilabel:`Register` button to complete the
+application registration. The :guilabel:`Application (client) ID` is produced. Copy this value, as
+it is needed later, in the :ref:`outlook_calendar/odoo_setup`.
 
-To do add a client secret, click :guilabel:`Add a certificate or secret` and then click
-:guilabel:`New client secret`. Next, type a :guilabel:`Description` and select when the client
-secret :guilabel:`Expires`.
+.. image:: outlook/app-client-id.png
+   :align: center
+   :alt: Application client ID highlighted in the essentials section of the newly created
+         application.
 
-Since resetting the synchronization can be tricky, Odoo recommends setting the maximum allowed
-expiration date for the client secret (24 months), so there is no need to re-synchronize soon.
-Finally, click :guilabel:`Add` to generate the client secret (:guilabel:`Secret ID`).
+Create client secret
+--------------------
+
+The second credential needed to complete the synchronization of the Microsoft *Outlook Calendar* is
+the *Client Secret*. The user **must** add a client secret, as this allows Odoo to authenticate
+itself, requiring no interaction from the user's side. *Certificates* are optional.
+
+To add a client secret, click :menuselection:`Certificates & secrets` in the left menu. Then click
+:guilabel:`+ New client secret` to create the client secret.
+
+.. image:: outlook/client-secret.png
+   :align: center
+   :alt: New client secret page with certificates and secrets menu and new client secret option
+         highlighted.
+
+Next, type a :guilabel:`Description`, and select when the client secret :guilabel:`Expires`.
+Available options include: :guilabel:`90 days (3 months)`, :guilabel:`365 days (12 months)`,
+:guilabel:`545 days (18 months)`, :guilabel:`730 days (24 months)` or :guilabel:`Custom`. The
+:guilabel:`Custom` option allows the administrator to set a :guilabel:`Start` and :guilabel:`End`
+date.
+
+Finally, click :guilabel:`Add` to :guilabel:`Add a client secret`.
+
+.. tip::
+   Since resetting the synchronization can be tricky, Odoo recommends setting the maximum allowed
+   expiration date for the client secret (24 months or custom), so there is no need to
+   re-synchronize soon.
+
+Copy the :guilabel:`Value` for use in the next section.
+
+.. warning::
+   Client secret values cannot be viewed, except immediately after creation. Be sure to save the
+   secret when created *before* leaving the page.
+
+.. _outlook_calendar/odoo_setup:
 
 Configuration in Odoo
 =====================
 
-In the Odoo database, go to :menuselection:`Settings --> General Settings --> Integrations` and
-activate the :guilabel:`Outlook Calendar` setting.
+In the Odoo database, go to :menuselection:`Settings app --> Integrations section`, and tick the
+checkbox beside the :guilabel:`Outlook Calendar` setting. Remember to click :guilabel:`Save` to
+implement the changes.
 
 .. image:: outlook/outlook-calendar-setting.png
    :align: center
    :alt: The "Outlook Calendar" setting activated in Odoo.
 
-From the Microsoft Azure portal, under the :guilabel:`Overview` section of the application, copy
-the :guilabel:`Application (Client) ID`, and paste it into the :guilabel:`Client ID` field in Odoo.
+From the Microsoft *Azure* portal, under the :guilabel:`Overview` section of the application, copy
+the :guilabel:`Application (Client) ID`, if it has not already been copied, and paste it into the
+:guilabel:`Client ID` field in Odoo.
 
 .. image:: outlook/client-id.png
    :align: center
    :alt: The "Client ID" in the Microsoft Azure portal.
 
-In the Microsoft Azure portal, under the :guilabel:`Certificates & secrets` section, copy the
-:guilabel:`Client Secret Value` and paste it into the :guilabel:`Client Secret` field in Odoo.
+Copy the previously-acquired :guilabel:`Value` (Client Secret Value), and paste it into the
+:guilabel:`Client Secret` field in Odoo.
 
 .. image:: outlook/client-secret-value.png
    :align: center
@@ -115,26 +181,30 @@ Sync with Outlook
 Sync Odoo Calendar and Outlook
 ------------------------------
 
-In the Odoo database, go to the :guilabel:`Calendar` module and click the :guilabel:`Outlook` sync
-button. The page will redirect to a Microsoft login page, and the user is asked to log in to their
-account, if they are not already, and grant the required permissions.
+In the Odoo database, open to the *Calendar* module, and click the :guilabel:`Outlook` sync button
+on the right-side of the page, beneath the monthly calendar.
 
 .. image:: outlook/outlook-sync-button.png
    :align: center
    :alt: The "Outlook" sync button in Odoo Calendar.
 
 The synchronization is a two-way process, meaning that events are reconciled in both accounts
-(Outlook and Odoo).
+(*Outlook* and Odoo). The page redirects to a Microsoft login page, and the user is asked to log in
+to their account, if they are not already. Finally, grant the required permissions by clicking
+:guilabel:`Accept`.
+
+.. image:: outlook/accept-terms.png
+   :align: center
+   :alt: Authentication process on Microsoft Outlook OAuth page.
 
 .. note::
    All users that want to use the synchronization simply need to :ref:`sync their calendar with
-   Outlook <outlook/sync>`. The configuration of Microsoft's Azure account is only done once, as
-   Microsoft Entra ID tenants' Client IDs and Client Secrets are unique, and represent an
-   organization that helps the user to manage a specific instance of Microsoft cloud services for
-   their internal and external users.
+   Outlook <outlook/sync>`. The configuration of Microsoft's *Azure* account is only done once, as
+   Microsoft *Entra ID* tenants' client IDs and client secrets are unique, and help the user manage
+   a specific instance of Microsoft cloud services for internal and external users.
 
 .. seealso::
-   - :doc:`/applications/general/integrations/mail_plugins/outlook`
+   - :doc:`../../general/integrations/mail_plugins/outlook`
    - :doc:`google`
 
 Troubleshoot sync