diff --git a/docs/images/spam-reporting-progress-notification.png b/docs/images/spam-reporting-progress-notification.png new file mode 100644 index 0000000000..dc83235de2 Binary files /dev/null and b/docs/images/spam-reporting-progress-notification.png differ diff --git a/docs/images/spam-reporting-suppress-dialog.png b/docs/images/spam-reporting-suppress-dialog.png new file mode 100644 index 0000000000..5f144e2b62 Binary files /dev/null and b/docs/images/spam-reporting-suppress-dialog.png differ diff --git a/docs/outlook/spam-reporting.md b/docs/outlook/spam-reporting.md index 98d17ee326..49be7554f5 100644 --- a/docs/outlook/spam-reporting.md +++ b/docs/outlook/spam-reporting.md @@ -1,7 +1,7 @@ --- title: Implement an integrated spam-reporting add-in description: Learn how to implement an integrated spam-reporting add-in in Outlook. -ms.date: 09/12/2024 +ms.date: 01/16/2025 ms.topic: how-to ms.localizationpriority: medium --- @@ -51,7 +51,8 @@ To implement the integrated spam-reporting feature in your add-in, you must conf - The button of the spam-reporting add-in that always appears in a prominent spot on the Outlook ribbon. The following is an example of how the button of a spam-reporting add-in appears on the ribbon of the classic Outlook client on Windows. The ribbon UI may vary depending on the platform the user's Outlook client is running on. :::image type="content" source="../images/outlook-spam-ribbon-button.png" alt-text="A sample ribbon button of a spam-reporting add-in."::: -- The preprocessing dialog. This dialog is shown to the user when they select the add-in button. In this dialog, a user can provide additional information about the message they're reporting. When a user selects **Report** from the dialog, the [SpamReporting](/javascript/api/office/office.eventtype) event is activated and is then handled by the JavaScript event handler. The following is an example of a preprocessing dialog in Outlook on Windows. Note that the appearance of the dialog may vary depending on the platform the user's Outlook client is running on. + +- The preprocessing dialog. When a user selects the add-in button, a dialog appears with **Report** and **Don't Report** options. In this dialog, you can share information about the reporting process or implement input options to get information about a reported message. Input options include checkboxes, radio buttons, and a text box. When a user selects **Report** from the dialog, the [SpamReporting](/javascript/api/office/office.eventtype) event is activated and is then handled by the JavaScript event handler. The following is an example of a preprocessing dialog in Outlook on Windows. Note that the appearance of the dialog may vary depending on the platform the user's Outlook client is running on. :::image type="content" source="../images/outlook-spam-processing-dialog.png" alt-text="A sample preprocessing dialog of a spam-reporting add-in."::: @@ -169,12 +170,13 @@ Configure the [VersionOverridesV1_1](/javascript/api/manifest/versionoverrides-1 - To customize the ribbon button and preprocessing dialog, you must define the [ReportPhishingCustomization](/javascript/api/manifest/reportphishingcustomization) node. - To configure the ribbon button, set the `xsi:type` attribute of the [Control](/javascript/api/manifest/control-button) element to `Button`. Then, set the `xsi:type` attribute of the [Action](/javascript/api/manifest/action) child element to `ExecuteFunction` and specify the name of the spam-reporting event handler in its **\** child element. - To customize the preprocessing dialog, configure the [PreProcessingDialog](/javascript/api/manifest/preprocessingdialog) element of your manifest. While the dialog must have a title and description, you can optionally include the following elements. - - A multiple-selection list of choices to help a user identify the type of message they're reporting. To learn how to configure these reporting options, see [ReportingOptions element](/javascript/api/manifest/reportingoptions). + - A multiple-selection list of choices to help a user identify the type of message they're reporting. To learn about other input types and how to configure these options, see [ReportingOptions element](/javascript/api/manifest/reportingoptions). - A text box for the user to provide additional information about the message they're reporting. To learn how to implement a text box, see [FreeTextLabel element](/javascript/api/manifest/preprocessingdialog#child-elements). - Custom text and URL to provide informational resources to the user. To learn how to personalize these elements, see [MoreInfo element](/javascript/api/manifest/moreinfo). > [!NOTE] > Depending on the Outlook client, the custom text specified in the **\** element appears before the URL that's provided in the **\** element or as link text for the URL. For more information, see [MoreInfoText](/javascript/api/manifest/moreinfo#moreinfotext). + - A "Don't show me this message again" checkbox to prevent the preprocessing dialog from appearing again. To learn how to implement this option, see [Suppress the preprocessing dialog](#suppress-the-preprocessing-dialog). The following is an example of a **\** node configured for spam reporting. @@ -349,7 +351,13 @@ The following is an example of a spam-reporting event handler that calls the `ge ### Signal when the event has been processed -Once the event handler has completed processing the message, it must call the [event.completed](/javascript/api/outlook/office.mailboxevent#outlook-office-mailboxevent-completed-member(1)) method. In addition to signaling to the add-in that the spam-reporting event has been processed, `event.completed` can also be used to customize a post-processing dialog to show to the user or perform additional operations on the message, such as deleting it from the inbox. For a list of properties you can include in a JSON object to pass as a parameter to the `event.completed` method, see [Office.SpamReportingEventCompletedOptions](/javascript/api/outlook/office.spamreportingeventcompletedoptions). +Once the event handler has completed processing the message, it must call the [event.completed](/javascript/api/outlook/office.mailboxevent#outlook-office-mailboxevent-completed-member(1)) method. In addition to signaling to the add-in that the spam-reporting event has been processed, `event.completed` can also be used to do the following: + +- Customize a post-processing dialog to show to the user. +- Perform additional operations on the message, such as deleting it from the inbox. +- [Open a task pane and pass information to it](#open-a-task-pane-after-reporting-a-message). + +For a list of properties you can include in a JSON object to pass as a parameter to the `event.completed` method, see [Office.SpamReportingEventCompletedOptions](/javascript/api/outlook/office.spamreportingeventcompletedoptions). > [!NOTE] > Code added after the `event.completed` call isn't guaranteed to run. @@ -456,6 +464,83 @@ The following is a sample post-processing dialog shown to the user once the add- 1. In the preprocessing dialog, choose a reason for reporting the message and add information about the message, if configured. Then, select **Report**. 1. (Optional) In the post-processing dialog, select **OK**. +## Suppress the preprocessing dialog + +> [!NOTE] +> The "Don't show me this message again" option was introduced in [requirement set 1.15](/javascript/api/requirement-sets/outlook/requirement-set-1.15/outlook-requirement-set-1.15). Learn more about its [supported clients and platforms](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets#outlook-client-support). This option isn't currently supported in a spam-reporting add-in that uses the unified manifest. + +Depending on your scenario, you might not need a user to provide additional information about a message they're reporting. If the preprocessing dialog of your spam-reporting add-in only provides information to the user, you can choose to include a "Don't show me this message again" option in the dialog. + +:::image type="content" source="../images/spam-reporting-suppress-dialog.png" alt-text="The 'Don't show me this message again' option in the preprocessing dialog."::: + +To implement this in your add-in, you must specify the [NeverShowAgainOption](/javascript/api/manifest/preprocessingdialog#child-elements) element in your manifest and set it to `true`. The following code is an example. + +```xml +... + + + <Description resid="PreProcessingDialog.Text"/> + <NeverShowAgainOption>true</NeverShowAgainOption> + <MoreInfo> + <MoreInfoText resid="MoreInfo.Label"/> + <MoreInfoUrl resid="MoreInfo.Url"/> + </MoreInfo> + </PreProcessingDialog> +... +``` + +Note the following behaviors when implementing this option in your add-in. + +- The "Don't show me this message again" option appears in the preprocessing dialog only if there are no user input options configured, such as reporting options or a text box. If your manifest also specifies user input options, they'll be shown in the dialog instead. +- The option to suppress the preprocessing dialog is applied on a per-machine and per-platform basis. +- After suppressing the preprocessing dialog, if a user reports a message and has the [Reading Pane](https://support.microsoft.com/office/2fd687ed-7fc4-4ae3-8eab-9f9b8c6d53f0) turned on, a progress notification is shown on the message while it's being processed. If the Reading Pane is turned off, no progress notification is shown. + + :::image type="content" source="../images/spam-reporting-progress-notification.png" alt-text="The progress notification shown after reporting a message while the Reading Pane is turned on."::: + + > [!NOTE] + > If you implement the "Don't show me this message again" option without configuring a post-processing dialog, a dialog with the following generic message is shown to the user after processing: "Thank you for reporting this message." It's good practice to configure a post-processing dialog to appear after a reported message is processed. + +### Reenable the preprocessing dialog + +To reenable the preprocessing dialog in classic Outlook on Windows after selecting the "Don't show me this message again" option, perform the following steps. + +1. Open the **Registry Editor** as an administrator. +1. Navigate to **HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Outlook\Options\WebExt\SpamDialog**. +1. Locate your spam-reporting add-in using its ID specified in the manifest. +1. Delete the entry of your add-in from the registry. + +The preprocessing dialog will appear the next time a message is reported. + +## Open a task pane after reporting a message + +> [!NOTE] +> The option to implement a task pane from the `event.completed` method was introduced in [requirement set 1.15](/javascript/api/requirement-sets/outlook/requirement-set-1.15/outlook-requirement-set-1.15). Learn more about its [supported clients and platforms](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets#outlook-client-support). + +Instead of a post-processing dialog, you can implement a task pane to open after a user reports a message. For example, you can use the task pane to show additional information based on the user's input in the preprocessing dialog. Similar to the post-processing dialog, the task pane is implemented through the add-in's `event.completed` call. + +> [!NOTE] +> If both the post-processing dialog and task pane capabilities are configured in the `event.completed` call, the task pane is shown instead of the dialog. + +To configure a task pane to open after a message is reported, you must specify the ID of the task pane in the [commandId](/javascript/api/outlook/office.spamreportingeventcompletedoptions?view=outlook-js-1.15&preserve-view=true#outlook-office-spamreportingeventcompletedoptions-commandid-member) option of the `event.completed` call. The ID must match the value specified in the `id` attribute of the [Control](/javascript/api/manifest/control) element that represents the task pane in the manifest. + +If you need to pass information to the task pane, specify any JSON data in the [contextData](/javascript/api/outlook/office.spamreportingeventcompletedoptions?view=outlook-js-1.15&preserve-view=true#outlook-office-spamreportingeventcompletedoptions-contextdata-member) option of the `event.completed` call. To retrieve the value of the `contextData` option, you must call [Office.context.mailbox.item.getInitializationContextAsync](/javascript/api/outlook/office.messageread#outlook-office-messageread-getinitializationcontextasync-member(1)) in the JavaScript implementation of your task pane. + +> [!IMPORTANT] +> To ensure that the task pane of the spam-reporting add-in opens and receives context data after a message is reported, you must set the `moveItemTo` option of the `event.completed` call to `Office.MailboxEnums.MoveSpamItemTo.NoMove`. + +The following code is an example. + +```javascript +... + event.completed({ + commandId: "msgReadOpenPaneButton", + contextData: JSON.stringify({ a: "aValue", b: "bValue" }), + moveItemTo: Office.MailboxEnums.MoveSpamItemTo.NoMove + }); +``` + +If another task pane is open or pinned at the time a message is reported, the open task pane is closed then the task pane of the spam-reporting add-in is shown. + ## Review feature behavior and limitations As you develop and test the integrated spam-reporting feature in your add-in, be mindful of its characteristics and limitations. @@ -487,7 +572,7 @@ As you develop and test the integrated spam-reporting feature in your add-in, be ## Troubleshoot your add-in -As you develop your spam-reporting add-in, you may need to troubleshoot issues, such as your add-in not loading. For guidance on how to troubleshoot a spam-reporting add-in, see [Troubleshoot event-based and spam-reporting add-ins](troubleshoot-event-based-and-spam-reporting-add-ins.md). +As you develop your spam-reporting add-in, you might need to troubleshoot issues, such as your add-in not loading. For guidance on how to troubleshoot a spam-reporting add-in, see [Troubleshoot event-based and spam-reporting add-ins](troubleshoot-event-based-and-spam-reporting-add-ins.md). ## See also