Office.SmartAlertsEventCompletedOptions interface

Package:

outlook

Specifies the behavior of a Smart Alerts add-in when it completes processing an OnMessageSend or OnAppointmentSend event.

Remarks

[ API set: Mailbox 1.12 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

Examples

// The following example checks whether a location is specified in an appointment before it's sent.
function onAppointmentSendHandler(event) {
    Office.context.mailbox.item.location.getAsync({ asyncContext: event }, asyncResult => {
        const event = asyncResult.asyncContext;
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log(asyncResult.error.message);
            // If the add-in is unable to retrieve the appointment's location, the appointment isn't sent.
            event.completed({ allowEvent: false, errorMessage: "Failed to get the appointment's location." });
            return;
        }

        if (asyncResult.value === "") {
            // If no location is specified, the appointment isn't sent and the user is alerted to include a location.
            event.completed(
                {
                    allowEvent: false,
                    cancelLabel: "Add a location",
                    commandId: "msgComposeOpenPaneButton",
                    contextData: JSON.stringify({ a: "aValue", b: "bValue" }),
                    errorMessage: "Don't forget to add a meeting location.",
                    errorMessageMarkdown: `
                        Don't forget to add a meeting location.\n\n
                        **Tip**: For a list of locations,
                        see [Meeting Locations]("https://www.contoso.com/meeting-locations).`,
                    sendModeOverride: Office.MailboxEnums.SendModeOverride.PromptUser
                }
            );
        } else {
            // If a location is specified, the appointment is sent.
            event.completed({ allowEvent: true });
        }
    });
}

Properties

allowEvent	When you use the completed method to signal completion of an event handler, this value indicates if the handled event should continue execution or be canceled. For example, an add-in that handles the OnMessageSend or OnAppointmentSend event can set allowEvent to false to cancel the sending of an item. For a complete sample, see the Smart Alerts walkthrough.
cancelLabel	When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property customizes the text of a button in the Smart Alerts dialog. Custom text must be 20 characters or less. For an example, see the Smart Alerts walkthrough.
commandId	When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property specifies the ID of the task pane or function that runs from a button in the Smart Alerts dialog. For an example, see the Smart Alerts walkthrough.
contextData	When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property specifies any JSON data passed to the add-in for processing when the applicable button is selected from the Smart Alerts dialog.
errorMessage	When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property sets the error message that will be displayed to the user. For an example, see the Smart Alerts walkthrough.
errorMessageMarkdown	When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property sets the error message displayed to the user. The error message is formatted using Markdown. For an example, see the Smart Alerts walkthrough.
sendModeOverride	When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property overrides the send mode option specified in the manifest at runtime. For an example, see the Smart Alerts walkthrough.

Property Details

allowEvent

When you use the completed method to signal completion of an event handler, this value indicates if the handled event should continue execution or be canceled. For example, an add-in that handles the OnMessageSend or OnAppointmentSend event can set allowEvent to false to cancel the sending of an item. For a complete sample, see the Smart Alerts walkthrough.

allowEvent?: boolean;

Property Value

boolean

Remarks

[ API set: Mailbox 1.12 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

cancelLabel

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property customizes the text of a button in the Smart Alerts dialog. Custom text must be 20 characters or less.

For an example, see the Smart Alerts walkthrough.

cancelLabel?: string;

Property Value

string

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

Important:

The customizable button in the Smart Alerts dialog varies depending on the Outlook client and its version.

• In Outlook on the web, new Outlook on Windows, and classic Outlook on Windows starting in Version 2412 (Build 18324.20000), the cancelLabel property customizes the text of the Take Action button. The Take Action button only appears on the Smart Alerts dialog if the commandId option is configured in the event.completed call. The option must be configured if you want to customize the text of the dialog button. In this implementation, the Don't Send button cancels the item being sent. Its text and functionality can't be customized. If you previously customized the text of the Don't Send button without assigning it a task pane or function command, your custom text won't take effect in the latest Outlook client versions. If you previously assigned a task pane or function command to the Don't Send button, no additional action is needed to implement the Take Action button in the latest versions. The default or customized Take Action button will automatically appear the next time a user receives a Smart Alerts dialog. Although no implementation changes are needed, we recommend notifying users of this updated experience.

• In earlier supported versions of classic Outlook on Windows (versions prior to Version 2412 (Build 18324.20000) that support Mailbox requirement set 1.14), and Outlook on Mac (preview), the cancelLabel property customizes the text of the Don't Send button. The Don't Send button cancels the item being sent.

commandId

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property specifies the ID of the task pane or function that runs from a button in the Smart Alerts dialog.

For an example, see the Smart Alerts walkthrough.

commandId?: string;

Property Value

string

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

Important:

The commandId value must match the task pane or function ID specified in the manifest of your add-in. The markup depends on the type of manifest your add-in uses.

• Add-in only manifest: The id attribute of the Control element representing the task pane or function.

• Unified manifest for Microsoft 365: The "id" property of the task pane or function command in the "controls" array.

The button in the Smart Alerts dialog that opens a task pane or runs a function varies depending on the Outlook client and version. In Outlook on the web, new Outlook on Windows, and classic Outlook on Windows starting in Version 2412 (Build 18324.20000), the Take Action button opens a task pane or runs a function. In this implementation, the Don't Send button cancels the item being sent. Its text and functionality can't be customized. In earlier supported versions of classic Outlook on Windows (versions prior to Version 2412 (Build 18324.20000) that support Mailbox requirement set 1.14), and Outlook on Mac (preview), the Don't Send button opens a task pane or runs a function.

If you customized the text and functionality of the Don't Send button in your Smart Alerts add-in prior to Version 2412 (Build 18324.20000) of classic Outlook on Windows, no additional action is needed to implement the Take Action button in the latest supported versions. The default or customized Take Action button will automatically appear the next time a user receives a Smart Alerts dialog. Although no implementation changes are needed, we recommend notifying users of this updated experience.

If you specify a command ID that doesn't exist, depending on your Outlook client, the Take Action or Don't Send button simply cancels the item being sent.

If you specify the contextData option in your event.completed call, you must also assign a task pane or function ID to the commandId option. Otherwise, the JSON data assigned to contextData is ignored.

When you configure a button in the Smart Alerts dialog to run a function, a button for the function is also added to the ribbon or action bar of the Outlook client. Use the contextData option to distinguish when a user runs the function from the Smart Alerts dialog.

contextData

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property specifies any JSON data passed to the add-in for processing when the applicable button is selected from the Smart Alerts dialog.

contextData?: any;

Property Value

any

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

Important:

• In Outlook on Windows, the any type is supported starting in Version 2402 (Build 17308.20000). In earlier versions of Outlook on Windows, only the string type is supported.

• If you specify the contextData option in your event.completed call, you must also assign a task pane or function ID to the commandId option. Otherwise, the JSON data assigned to contextData is ignored.

• The dialog button that passes the contextData value to the add-in varies depending on the Outlook client and its version. For more information, see Customize the text and functionality of a button in the dialog.

• To retrieve the value of the contextData property, you must call Office.context.mailbox.item.getInitializationContextAsync in the JavaScript implementation of your task pane. If you create a JSON string using JSON.stringify() and assign it to the contextData property, you must parse the string using JSON.parse() once you retrieve it.

• When you configure a button in the Smart Alerts dialog to run a function, a button for the function is also added to the ribbon or action bar of the Outlook client. Use the contextData option to distinguish when a user runs the function from the Smart Alerts dialog.

errorMessage

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property sets the error message that will be displayed to the user. For an example, see the Smart Alerts walkthrough.

errorMessage?: string;

Property Value

string

Remarks

[ API set: Mailbox 1.12 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

Important: The error message must be 500 characters or less.

errorMessageMarkdown

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property sets the error message displayed to the user. The error message is formatted using Markdown. For an example, see the Smart Alerts walkthrough.

errorMessageMarkdown?: string;

Property Value

string

Remarks

[ API set: Mailbox 1.15 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

Important

• The formatted error message must be 500 characters or less.

• For guidance on supported Markdown elements, see Limitations to formatting the dialog message using Markdown.

• If you format the dialog message using the errorMessageMarkdown property, we recommend you also add a plaintext version of the message using the errorMessage property. This ensures that the message is displayed properly in Outlook clients that don't support Markdown.

sendModeOverride

When you use the completed method to signal completion of an event handler and set its allowEvent property to false, this property overrides the send mode option specified in the manifest at runtime.

For an example, see the Smart Alerts walkthrough.

sendModeOverride?: MailboxEnums.SendModeOverride | string;

Property Value

Office.MailboxEnums.SendModeOverride | string

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level (Outlook): restricted

Applicable Outlook mode: Compose

Important: Currently, sendModeOverride can only be set to the prompt user option.