diff --git a/content/applications/productivity/calendar/outlook.rst b/content/applications/productivity/calendar/outlook.rst index 5d376d9a5..054d7a6f6 100644 --- a/content/applications/productivity/calendar/outlook.rst +++ b/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 `_. Refer to `Microsoft's documentation `_ 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 `_, 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 +`_. 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 +`_. + +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 `, 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 `_. +For more information on the restrictions and limitations of URIs, check Microsoft's `Redirect URI +(reply URL) restrictions and limitations +`_ 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 app --> Calendar` in the left menu 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 `. 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 `. 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 diff --git a/content/applications/productivity/calendar/outlook/accept-terms.png b/content/applications/productivity/calendar/outlook/accept-terms.png new file mode 100644 index 000000000..4ba15c3b4 Binary files /dev/null and b/content/applications/productivity/calendar/outlook/accept-terms.png differ diff --git a/content/applications/productivity/calendar/outlook/app-client-id.png b/content/applications/productivity/calendar/outlook/app-client-id.png new file mode 100644 index 000000000..833938284 Binary files /dev/null and b/content/applications/productivity/calendar/outlook/app-client-id.png differ diff --git a/content/applications/productivity/calendar/outlook/app-register.png b/content/applications/productivity/calendar/outlook/app-register.png new file mode 100644 index 000000000..727172943 Binary files /dev/null and b/content/applications/productivity/calendar/outlook/app-register.png differ diff --git a/content/applications/productivity/calendar/outlook/client-secret.png b/content/applications/productivity/calendar/outlook/client-secret.png new file mode 100644 index 000000000..3777b1b5e Binary files /dev/null and b/content/applications/productivity/calendar/outlook/client-secret.png differ diff --git a/content/applications/productivity/calendar/outlook/redirect-uri.png b/content/applications/productivity/calendar/outlook/redirect-uri.png deleted file mode 100644 index 093133c5e..000000000 Binary files a/content/applications/productivity/calendar/outlook/redirect-uri.png and /dev/null differ