Fixes #740 - Reworked M365 IMAP channel

Author: ralf401

channels/email/accounts/archive-mode.rst

@@ -2,7 +2,7 @@
 .. figure:: /images/channels/email/account-setup-archive-import.png
    :alt: Archive Mode dialog during email account setup
    :align: center
-   :scale: 100%
+   :scale: 80%
 
    How should old emails be imported?
 

channels/microsoft365-graph/accounts.rst

@@ -146,6 +146,20 @@ Now your channel is ready and can be used! If something doesn't work, have
 a look at the :doc:`common errors section <common-errors>`, where you can
 find common errors related to the M365 configuration.
 
+.. note:: 🤔 **How do I use my Microsoft 365 account for outgoing system notifications?**
+
+   On **subscription/cloud-hosted instances**, you can't.
+   Notifications will always come from
+   “Notification Master <noreply\@your.zammad.domain>”.
+
+   On **self-hosted instances**, we still don't recommend it.
+   Using a Microsoft account for automated, outgoing messages is risky:
+   users who exceed Microsoft's
+   `email sending limits <https://docs.microsoft.com/en-us/office365/servicedescriptions/exchange-online-service-description/exchange-online-limits#receiving-and-sending-limits>`_
+   can have their accounts suspended.
+
+   Set up a generic :doc:`email channel </channels/email/index>` instead,
+   then use the :ref:`Email Notification <email-notification>` setting.
 
 Re-Authenticate
 ^^^^^^^^^^^^^^^

channels/microsoft365/accounts.rst

@@ -10,53 +10,32 @@ Accounts
    accounts/secondary-addresses
    accounts/managing-accounts
 
+Use the links below to step through the process of adding an M365 IMAP channel
+to Zammad.
+
 :doc:`accounts/register-app`
    Use the **Connect Microsoft 365 App** dialog to register Zammad as an
    OAuth app on Microsoft.
 
-   (This step is **required**; read on to learn why.)
-
-   .. figure:: /images/channels/microsoft365/accounts/register-app/04-add-oauth-credentials.gif
-      :alt: Registering Zammad as a Microsoft OAuth app
-      :scale: 60%
-      :align: center
+   This step is **required** before adding an account to Zammad.
 
 :doc:`accounts/account-setup`
    Use the **Add Account** dialog to connect your account.
 
-   You're migrating existing email channels? Look below!
-
-   .. figure:: /images/channels/microsoft365/accounts/account-setup/add-microsoft365-account-to-zammad.gif
-      :alt: Adding your gmail account to Zammad
-      :scale: 60%
-      :align: center
+   If you want to migrate an existing email channel, see next section.
 
 :doc:`accounts/migrate-from-email-channel`
-   Use the *Migrate now!* button within your email channels to quickly move
-   your mailboxes to Microsoft 365. You can roll back if things hit the fan!
-
-   .. figure:: /images/channels/microsoft365/accounts/migrate-email-channel-to-microsoft365.gif
-      :alt: Migrate an existing email channel to Microsoft 365
-      :scale: 60%
-      :align: center
+   Migrate your existing email channels from standard IMAP to the dedicated
+   M365 IMAP channel in Zammad to quickly move your mailboxes. You can roll
+   back if something goes wrong!
 
 :doc:`accounts/secondary-addresses`
    Send and receive email at **additional email addresses**,
    all through the same mailbox/account.
 
-   .. figure:: /images/channels/microsoft365/accounts/add-microsoft365-alias.gif
-      :alt: Adding new aliases to your Microsoft account in Zammad
-      :scale: 60%
-      :align: center
-
 :doc:`accounts/managing-accounts`
    Edit the configuration of existing accounts in the **Accounts Panel**.
 
-   .. figure:: /images/channels/microsoft365/panel.png
-      :alt: Existing accounts can be edited from the Accounts panel.
-      :scale: 60%
-      :align: center
-
 .. note:: 🤔 **How do I use my Microsoft 365 account for outgoing system notifications?**
 
    On **subscription/cloud-hosted instances**, you can't.

channels/microsoft365/accounts/account-setup.rst

@@ -2,7 +2,8 @@ Account Setup
 =============
 
 After you've :doc:`registered Zammad as an OAuth app <register-app>`
-in your Azure Portal, you can begin connecting Microsoft accounts to Zammad.
+in your Entra admin center, you can begin connecting Microsoft accounts to
+Zammad.
 
 ☠️ **But first, a word of warning!**
 The import process does things you might not expect:
@@ -12,9 +13,9 @@ The import process does things you might not expect:
      import process. Use the *Keep Messages on Server* setting to
      :ref:`disable this behavior <microsoft365-keep-messages-on-server>`.
    * Zammad will **send an auto-reply message to every email it imports**
-     (including the old ones!). Make sure to :doc:`disable this behavior </manage/trigger>`
-     prior adding an email account, and to turn it back on once all your
-     messages have been imported.
+     (including the old ones!). Make sure to
+     :doc:`disable this behavior </manage/trigger>` prior adding an email
+     account, and to turn it back on once all your messages have been imported.
 
 .. tip:: 🤓 **Shared mailboxes are possible...**
 
@@ -47,64 +48,33 @@ Requesting the consent
    If your admin already provided consent, you'll be automatically
    authenticated, if this happens, continue with `Add a New Account`_.
 
-   After authenticating against Microsoft and providing a reason for your request,
-   you'll be redirect to the Zammad app. Zammad will then tell you to wait for
-   your administrators consent. The consent grant or denial will be sent by mail.
-
-   .. figure:: /images/channels/microsoft365/accounts/account-setup/request-admin-consent-if-not-granted.gif
-      :alt: Click on Request Admin Consent if your administrator did not yet grant
-            the Zammad app for your tenant.
-      :scale: 50%
-      :align: center
+   After authenticating against Microsoft and providing a reason for your
+   request, you'll be redirect to the Zammad app. Zammad will then tell you to
+   wait for your administrators consent. The consent grant or denial will be
+   sent by mail.
 
 Granting the consent (admin users)
-   Within **Enterprise applications** go to **Admin consent requests**.
-   You'll find all your user grant requests here.
+   Within **Enterprise applications** in the Entra admin center, go to
+   **Admin consent requests**. You'll find all your user grant requests here.
 
    Clicking on a request allows you to review which user requested the consent
    for what app. Click on **Review permissions and consent** to start the
    grant process. You'll be asked for credentials - these credentials are the
    administrator credentials *not* the ones of the mailbox user to add.
 
-   After you've granted the request, continue with `Add a New Account`_.
-   (As mentioned in
-   :ref:`Step 3.1 of the App registration <register_ms_app_stepbystep>`)
-
-   .. figure:: /images/channels/microsoft365/accounts/account-setup/granting-consent-request-of-user.gif
-      :alt: Within Enterprise applications grant requests within admin consent
-            requests
-      :scale: 50%
-      :align: center
+   After you've granted the request, continue with "Add a New Account" below.
 
 Add a New Account
 -----------------
 
-.. note::
-
-   .. container:: cfloat-left
-
-      Below shown screencast shows the authentication process with enabled admin
-      consent and already tenant wide granted permission.
-
-      If you're not using admin consent in your organization or you're
-      authenticating a personal microsoft account, you'll see an additional
-      permission dialogue you'll have to approve.
-
-   .. container:: cfloat-right
-
-      .. figure:: /images/channels/microsoft365/accounts/account-setup/app-permission-dialogue.png
-         :alt: Authentication dialogue for non admin consented users
-         :scale: 40%
-         :align: center
-
-.. figure:: /images/channels/microsoft365/accounts/account-setup/add-microsoft365-account-to-zammad.gif
-   :alt: Click on Add Account to add your Microsoft account to Zammad
+.. figure:: /images/channels/microsoft365/accounts/account-setup/add-account.png
+   :alt: Click on Add Account to add your Microsoft 365 account to Zammad
    :scale: 60%
    :align: center
 
-Click **Add Account** to connect your Microsoft 365 / Outlook accounts to Zammad.
-You will be redirected to a Microsoft sign-in and confirmation page.
-
+Click **Add Account** to connect your Microsoft 365 accounts to Zammad.
+You will be redirected to a Microsoft sign-in and confirmation page. Enter
+your credentials and confirm it by clicking the **Accept** button.
 
 .. note:: 🕵️ **Aliases are not imported automatically.**
 
@@ -114,7 +84,7 @@ Channel
 ^^^^^^^
 
 .. figure:: /images/channels/microsoft365/accounts/account-setup/microsoft365-account-settings.png
-   :alt: Click on Add Account to add your Microsoft 365 account to Zammad
+   :alt: Screenshot showing channel configuration during adding account for M365
    :scale: 50%
    :align: center
 
@@ -156,7 +126,8 @@ Archive Mode
 
 After adding the account
    After successfully adding the Microsoft 365 mail account, you can adjust
-   the default group Zammad is going to assign incoming new tickets to.
+   the default group Zammad is going to assign incoming new tickets to by
+   clicking the group name under "Destination Group":
 
    .. figure:: /images/channels/microsoft365/accounts/account-setup/change-destination-group.png
       :alt: Location of "Destination Group" setting for existing accounts
@@ -185,3 +156,6 @@ My mailbox was working fine but suddenly it fails with ``EXPUNGE FAILED``
 
    As soon as the issue has been fixed, the Zammad channel will recover
    automatically.
+
+Have a look at the :doc:`common errors section <../common-errors>` if you still
+face issues with your M365 account.

channels/microsoft365/accounts/migrate-from-email-channel.rst

@@ -1,6 +1,9 @@
 Migrate From Email Channel to Microsoft 365 Channel
 ===================================================
 
+Migrate
+-------
+
 Zammad provides a migration logic that allows you to migrate existing Microsoft
 365 accounts from the Email channel to the Microsoft 365 channel.
 
@@ -19,14 +22,9 @@ banner of the email channel in question. Zammad will redirect you to
 Microsoft and request you to authenticate and consent to said account.
 
 After you pressed next you'll be redirect to Zammad's Microsoft 365 channel
-overview. Your channel, if successful, is now migrated to an Microsoft 365
+overview. Your channel, if successful, is now migrated to a Microsoft 365 IMAP
 channel.
 
-   .. figure:: /images/channels/microsoft365/accounts/migrate-email-channel-to-microsoft365.gif
-      :alt: Migrate an existing email channel to Microsoft 365
-      :scale: 90%
-      :align: center
-
 Rolling Back the Migration
 --------------------------