[Outlook] (spam reporting) Document improvements

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: 12/19/2024
 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 **\<FunctionName\>** 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 **\<MoreInfoText\>** element appears before the URL that's provided in the **\<MoreInfoUrl\>** 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 **\<VersionOverrides\>** 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 (preview)](#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 is currently in preview in classic Outlook on Windows starting in Version 2411 (Build 18227.20034).
+
+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?view=common-js-preview&preserve-view=true#child-elements) element in your manifest and set it to `true`. The following code is an example.
+
+```xml
+...
+    <PreProcessingDialog>
+      <Title resid="PreProcessingDialog.Label"/>
+      <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 is currently in preview in classic Outlook on Windows starting in Version 2411 (Build 18227.20034).
+
+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-preview&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-preview&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