diff --git a/docs/outlook/autolaunch.md b/docs/outlook/autolaunch.md index b0a5db1bf..aed9995f2 100644 --- a/docs/outlook/autolaunch.md +++ b/docs/outlook/autolaunch.md @@ -1,7 +1,7 @@ --- title: Configure your Outlook add-in for event-based activation description: Learn how to configure your Outlook add-in for event-based activation. -ms.date: 03/11/2025 +ms.date: 04/07/2025 ms.topic: concept-article ms.localizationpriority: medium --- @@ -67,7 +67,7 @@ Because event-based add-ins are deployed by admins, any change you make to the m ## Event-based activation behavior and limitations -Add-in launch-event handlers are expected to be short-running, lightweight, and as noninvasive as possible. After activation, your add-in will time out within approximately 300 seconds, the maximum length of time allowed for running event-based add-ins. To signal that your add-in has completed processing a launch event, your associated event handler must call the [event.completed](/javascript/api/outlook/office.mailboxevent#outlook-office-mailboxevent-completed-member(1)) method. (Note that code included after the `event.completed` statement isn't guaranteed to run.) Each time an event that your add-in handles is triggered, the add-in is reactivated and runs the associated event handler, and the timeout window is reset. The add-in ends after it times out, or the user closes the compose window or sends the item. +Event-based add-ins require an internet connection to be able to launch when a specific event occurs. Add-in event handlers are expected to be short-running, lightweight, and as noninvasive as possible. After activation, your add-in will time out within approximately 300 seconds, the maximum length of time allowed for running event-based add-ins. To signal that your add-in has completed processing a launch event, your associated event handler must call the [event.completed](/javascript/api/outlook/office.mailboxevent#outlook-office-mailboxevent-completed-member(1)) method. (Note that code included after the `event.completed` statement isn't guaranteed to run.) Each time an event that your add-in handles is triggered, the add-in is reactivated and runs the associated event handler, and the timeout window is reset. The add-in ends after it times out, or the user closes the compose window or sends the item. If the user has multiple add-ins that subscribe to the same event, the Outlook platform launches the add-ins in no particular order. Currently, only five event-based add-ins can be actively running. diff --git a/docs/outlook/one-outlook.md b/docs/outlook/one-outlook.md index 2148511c4..f2ca1b7b0 100644 --- a/docs/outlook/one-outlook.md +++ b/docs/outlook/one-outlook.md @@ -1,7 +1,7 @@ --- title: Develop Outlook add-ins for the new Outlook on Windows description: Learn how to develop add-ins that are compatible with the new Outlook on Windows. -ms.date: 03/11/2025 +ms.date: 03/31/2025 ms.localizationpriority: medium --- @@ -92,6 +92,17 @@ To debug an add-in installed in the new Outlook on Windows desktop client, perfo 1. [Sideload the add-in to Outlook on the web](sideload-outlook-add-ins-for-testing.md). 1. Use Microsoft Edge DevTools to debug your add-in. +## Add-in availability when offline + +When you turn on the [offline setting](https://support.microsoft.com/office/2460e4a8-16c7-47fc-b204-b1549275aac9) in the new Outlook on Windows, you can continue to access your emails and calendar if you lose internet connection. While some functionalities remain available, Outlook add-ins and the Microsoft 365 and Copilot store aren't available when offline. The following table describes the behavior of certain types of add-ins when your machine is offline or has an intermittent connection. + +| Scenario | Task pane and function command add-ins | Event-based add-ins | +| ----- | ----- | ----- | +| No internet connection when Outlook is launched | Installed add-ins don't appear on the ribbon or action bar. | Because Outlook can't determine which add-ins are installed while offline, event-based add-ins can't activate when the event they handle occurs.

In this scenario, to ensure that Smart Alerts add-ins still check mail items for compliance before they're sent, administrators can configure the **OnSendAddinsEnabled** mailbox policy in Exchange Online PowerShell. When configured, outgoing items are saved to the **Drafts** folder instead of the **Outbox** folder to prevent them from being automatically sent when the machine reconnects to the internet. For more information, see the "Offline when Outlook launches" section of [Handle OnMessageSend and OnAppointmentSend events in your Outlook add-in with Smart Alerts](onmessagesend-onappointmentsend-events.md#offline-when-outlook-launches). | +| A connection is established after launching Outlook while offline | Installed add-ins appear on the ribbon and action bar. | Outlook will be able to identify which event-based add-ins are installed. Installed add-ins can then activate when the event they handle occurs.

When you select **Send** on a mail item that was blocked by the **OnSendAddinsEnabled** mailbox policy, the Smart Alerts add-in runs to check for compliance. | +| Machine loses connection while Outlook is in use | If you lose connection while using Outlook, the installed add-ins remain visible, but the add-in can't run. A dialog or notification is shown to notify that you're offline. //TODO - Insert screenshots for task pane and function command. | If you lose connection when an event occurs, the behavior differs depending on the type of event-based add-in. | +| A connection is reestablished | Add-ins that were already visible on the ribbon or action bar can run operations again. | Installed add-ins resume handling events when they occur. Mail items that were moved to the **Outbox** folder are sent. When items in the **Drafts** folder are sent, Smart Alerts add-ins are activated to ensure that the mail items are compliant. | + ## Development experience feedback As you test your Outlook web add-in in the new Outlook on Windows, share feedback on your experience with the developer community through [GitHub](https://github.com/OfficeDev/office-js/issues/new/choose). diff --git a/docs/outlook/onmessagesend-onappointmentsend-events.md b/docs/outlook/onmessagesend-onappointmentsend-events.md index 9f90c5a27..77b486f8f 100644 --- a/docs/outlook/onmessagesend-onappointmentsend-events.md +++ b/docs/outlook/onmessagesend-onappointmentsend-events.md @@ -1,7 +1,7 @@ --- title: Handle OnMessageSend and OnAppointmentSend events in your Outlook add-in with Smart Alerts description: Learn about the Smart Alerts implementation and how it handles the OnMessageSend and OnAppointmentSend events in your event-based Outlook add-in. -ms.date: 03/11/2025 +ms.date: 03/31/2025 ms.topic: concept-article ms.localizationpriority: medium --- @@ -137,7 +137,87 @@ If the **soft block** or **block** option is used, the user can't send the item ![Dialog that alerts the user that the add-in process has timed out. The user must attempt to send the item again to activate the add-in before they can send the message or appointment.](../images/outlook-soft-hard-block-timeout.png) -### Outlook client in Work Offline mode +### Intermittent or no internet connection + +Event-based add-ins, including Smart Alerts add-ins, require an internet connection to launch. This section describes how an add-in behaves when Outlook is launched without connectivity, when Outlook experiences intermittent connectivity, and when the Work Offline mode, if applicable to the Outlook client, is turned on. + +#### Offline when Outlook launches + +When Outlook launches without internet connectivity, it's unable to determine which add-ins are installed. Because of this, Smart Alerts add-ins can't activate when the `OnMessageSend` or `OnAppointmentSend` events occur. In this scenario, to ensure that all mail items are checked for compliance before they're sent, administrators can configure policies in their organization. The policy to be set varies depending on the Outlook client. + +# [Web/Windows (new)](#tab/web-new-windows) + +For Outlook on the web and new Outlook on Windows, configure the **OnSendAddinsEnabled** mailbox policy in Exchange Online PowerShell. + +1. [Connect to Exchange Online PowerShell](/powershell/exchange/connect-to-exchange-online-powershell). +1. Create a new mailbox policy. + + ```powershell + New-OWAMailboxPolicy OWAOnSendAddinAllUserPolicy + ``` + + > [!NOTE] + > Administrators can also use an existing policy. + +1. Set the **OnSendAddinsEnabled** flag to `true`. + + ```powershell + Get-OWAMailboxPolicy OWAOnSendAddinAllUserPolicy | Set-OWAMailboxPolicy –OnSendAddinsEnabled:$true + ``` + +1. Assign the policy to user mailboxes. + + ```powershell + Get-User -Filter {RecipientTypeDetails -eq 'UserMailbox'} | Set-CASMailbox -OwaMailboxPolicy OWAOnSendAddinAllUserPolicy + ``` + +# [Windows (classic)](#tab/windows) + +Configure the **Block send when web add-ins can't load** Group Policy setting. When the setting is turned on, mail items are moved to the **Drafts** folder when the **Send** button is selected. This way, when Outlook is able to load add-ins, any installed Smart Alerts add-ins can run checks on the items before they're sent. + +To turn on the setting, perform the following: + +1. Download the latest [Administrative Templates tool](https://www.microsoft.com/download/details.aspx?id=49030). +1. Open the **Local Group Policy Editor** (**gpedit.msc**). +1. Navigate to **User Configuration** > **Administrative Templates** > **Microsoft Outlook 2016** > **Security** > **Trust Center**. +1. Open the **Block send when web add-ins can't load** setting. +1. In the dialog that appears, select **Enabled**. +1. Select **OK** or **Apply** to save your change. + +# [Mac](#tab/mac) + +For Outlook on Mac, the **OnSendAddinsWaitForLoad** mailbox key must be configured on each user's machine. This key ensures that add-ins are loaded from Exchange and are available to run checks on outgoing items. As the **OnSendAddinsWaitForLoad** key is CFPreference-compatible, it can be set by any enterprise management software for Mac, such as Jamf Pro. The following table provides details about the key. + +|Field|Value| +|:---|:---| +|**Domain**|com.microsoft.outlook| +|**Key**|OnSendAddinsWaitForLoad| +|**DataType**|Boolean| +|**Possible values**|**false** (default): The currently downloaded manifests of the Smart Alerts add-ins (not necessarily the latest versions) run on outgoing mail items.

**true**: After the latest manifests of the Smart Alerts add-ins are downloaded from Exchange, the add-ins run on outgoing mail items. Otherwise, the item is blocked from being sent and the **Send** button becomes unavailable.| +|**Availability**|16.27| +|**Comments**|This key creates a policy to ensure that outgoing mail items are checked for compliance before they're sent.| + +--- + +#### Intermittent connection + +> [!NOTE] +> In classic Outlook on Windows and on Mac, the behavior of a Smart Alerts add-in is different while in [Work Offline mode](https://support.microsoft.com/office/f3a1251c-6dd5-4208-aef9-7c8c9522d633). For more information, see [Outlook client in Work Offline mode](#outlook-client-in-work-offline-mode). + +If Outlook was able to load any Smart Alerts add-ins that are installed, but loses connection when an `OnMessageSend` or `OnAppointmentSend` event occurs, the behavior differs depending on the send mode option implemented by the add-in. + +If the **prompt user** or **soft block** option is used, the following behavior applies. + +- **Send Anyway** option is selected: The mail item is moved to the **Outbox** folder. When a connection is reestablished, the item is automatically sent. +- **Don't Send** option is selected: The mail item is saved to the **Drafts** folder. This prevents the item from being automatically sent when a connection is reestablished. When Outlook is back online and the user selects **Send**, the Smart Alerts add-in is activated. + +//TODO - Add screenshot if a non-customizable message is shown. + +If the **block** option is used, the mail item is saved to the **Drafts** folder and a dialog is shown to the user notifying them to reconnect. This prevents the item from being automatically sent when a connection is reestablished. When Outlook is back online and the user selects **Send**, the Smart Alerts add-in is activated. + +//TODO - Add screenshot of reconnection dialog. + +#### Outlook client in Work Offline mode In Outlook on Windows (classic client starting in Version 2310 (Build 16913.10000)) and on Mac (starting in Version 16.80 (23121017)), a Smart Alerts add-in that implements the **soft block** or **block** option can only process a mail item while the Outlook client is online. If [Work Offline mode](https://support.microsoft.com/office/f3a1251c-6dd5-4208-aef9-7c8c9522d633) is turned on in the Outlook client when a mail item is sent, the item isn't saved to the **Outbox** folder and the user is alerted that they must deactivate Work Offline mode before they can attempt to send their item. @@ -149,7 +229,7 @@ If the Smart Alerts add-in implements the **prompt user** option, it doesn't pro When a user navigates away from the message they're sending (for example, to read a message in their inbox), the behavior of a Smart Alerts add-in differs between Outlook clients. Select the tab for the Outlook client on which the add-in is running. -# [Web/New Outlook on Windows](#tab/web) +# [Web/Windows (new)](#tab/web-new-windows) In Outlook on the web or in [new Outlook on Windows](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627), a user must remain on the message being sent until the Smart Alerts add-in completes processing it. Otherwise, once the user navigates away from the item, the add-in terminates the Smart Alerts operation and saves a draft to the mailbox's **Drafts** folder. The user is then alerted that they must resend the message from the **Drafts** folder and remain on the message until the add-in completes processing it. diff --git a/docs/outlook/outlook-add-ins-overview.md b/docs/outlook/outlook-add-ins-overview.md index 4dd8a5c78..e7321cc25 100644 --- a/docs/outlook/outlook-add-ins-overview.md +++ b/docs/outlook/outlook-add-ins-overview.md @@ -1,7 +1,7 @@ --- title: Outlook add-ins overview description: Outlook add-ins extend or customize the Outlook UI and are developed by Microsoft and partners using our web-based platform. -ms.date: 02/19/2025 +ms.date: 03/31/2025 ms.topic: overview ms.custom: scenarios:getting-started ms.localizationpriority: high @@ -9,11 +9,12 @@ ms.localizationpriority: high # Outlook add-ins overview -Outlook add-ins are solutions that extend the functionality of the Outlook client through a web-based platform. Outlook add-ins have three key aspects. +Outlook add-ins are solutions that extend the functionality of the Outlook client through a web-based platform. Outlook add-ins have the following key aspects. -- The same add-in and business logic works across web (Microsoft 365 and Outlook.com), desktop (Outlook on Windows (classic) and on Mac), and mobile. -- Outlook add-ins consist of a manifest, which describes how the add-in integrates into Outlook (for example, a button or a task pane), and JavaScript/HTML code, which makes up the UI and business logic of the add-in. -- Outlook add-ins can be acquired from [AppSource](https://appsource.microsoft.com) or [sideloaded](sideload-outlook-add-ins-for-testing.md) by end-users or administrators. +- The same add-in and business logic works across web (Microsoft 365 and Outlook.com), desktop (Outlook on Windows ([new](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627) and classic) and on Mac), and mobile. +- Outlook add-ins consist of a manifest, which describes how the add-in integrates into Outlook (for example, a button, task pane, or event). It also includes JavaScript and HTML code, which make up the UI and business logic of the add-in. +- Outlook add-ins can be acquired from [AppSource](https://appsource.microsoft.com) or [sideloaded](sideload-outlook-add-ins-for-testing.md) by end users or administrators. +- Outlook add-ins require a network connection to run. Outlook add-ins are different from COM or VSTO add-ins, which are older integrations specific to Outlook running on Windows. Unlike COM add-ins, Outlook add-ins don't have any code physically installed on the user's device or Outlook client. For an Outlook add-in, Outlook reads the manifest and hooks up the specified controls in the UI, and then loads the JavaScript and HTML. The web components all run in the context of a browser or webview control in a sandbox. @@ -89,7 +90,7 @@ However, add-ins won't activate on IRM-protected items when: ## Supported clients -Outlook add-ins are supported in Outlook on the web, Outlook on Windows ([new](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627) and classic), Outlook on Mac, Outlook on iOS, Outlook on Android, and Outlook.com. Not all of the newest features are supported in all clients at the same time. For details about feature support on clients and servers, see [Requirement sets supported by Exchange servers and Outlook clients](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets#requirement-sets-supported-by-exchange-servers-and-outlook-clients) and articles specific to those features. +Outlook add-ins are supported in Outlook on the web, Outlook on Windows (new and classic), Outlook on Mac, Outlook on iOS, Outlook on Android, and Outlook.com. Not all of the newest features are supported in all clients at the same time. For details about feature support on clients and servers, see [Requirement sets supported by Exchange servers and Outlook clients](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets#requirement-sets-supported-by-exchange-servers-and-outlook-clients) and articles specific to those features. ## Get started building Outlook add-ins diff --git a/docs/outlook/outlook-on-send-addins.md b/docs/outlook/outlook-on-send-addins.md index d98ac281f..5f4130066 100644 --- a/docs/outlook/outlook-on-send-addins.md +++ b/docs/outlook/outlook-on-send-addins.md @@ -393,6 +393,17 @@ The on-send add-ins will run during send if the Exchange server is online and re > [!NOTE] > On Mac in any offline state, the **Send** button (or the **Send Update** button for existing meetings) is disabled and a notification displayed that their organization doesn't allow send when the user is offline. +## Add-in availability when offline in new Outlook on Windows + +When a user turns on the [offline setting](https://support.microsoft.com/office/2460e4a8-16c7-47fc-b204-b1549275aac9) in the new Outlook on Windows, they can continue to access their emails and calendar if they lose internet connection. While some functionalities remain available, Outlook add-ins and the Microsoft 365 and Copilot store aren't available when offline. The following table describes the behavior of on-send add-ins when a machine is offline or has an intermittent connection. + +| Scenario | On-send add-in behavior | +| ----- | ----- | +| No internet connection when Outlook is launched | Because Outlook can't determine which add-ins are installed while offline, on-send add-ins can't activate when the `ItemSend` event occurs. To ensure that mail items are still checked for compliance before they're sent, administrators can configure the **OnSendAddinsEnabled** mailbox policy in Exchange Online PowerShell. When configured, outgoing items are saved to the **Drafts** folder instead of the **Outbox** folder to prevent them from being automatically sent when the machine reconnects to the internet. For more information, see [Install Outlook add-ins that use on-send](#install-outlook-add-ins-that-use-on-send). | +| A connection is established after launching Outlook while offline | Outlook will be able to identify which on-send add-ins are installed. When a user selects **Send** on a mail item that was blocked by the **OnSendAddinsEnabled** mailbox policy, the on-send add-in runs to check for compliance. | +| Machine loses connection while Outlook is in use | If a user loses connection as they select **Send**, the following dialog is displayed and the mail item is saved to the **Drafts** folder to prevent it from being automatically sent when the machine reconnects to the internet. //TODO - Add screenshot of dialog. | +| A connection is reestablished | Installed on-send add-ins resume handling the `ItemSend` event when it occurs. Mail items that were moved to the **Outbox** folder are sent. When items in the **Drafts** folder are sent, on-send add-ins are activated to ensure that the mail items are compliant. | + ### User can edit item while on-send add-ins are working on it While on-send add-ins are processing an item, the user can edit the item by adding, for example, inappropriate text or attachments. If you want to prevent the user from editing the item while your add-in is processing on send, you can implement a workaround using a dialog. This workaround can be used in Outlook on the web (classic), Windows (classic), and Mac.