Office.SmartAlertsEventCompletedOptions interface
Specifies the behavior of a Smart Alerts add-in when it completes processing an OnMessageSend or OnAppointmentSend event.
Remarks
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
| allow |
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 |
| cancel |
When you use the completed method to signal completion of an event handler and set its For an example, see the Smart Alerts walkthrough. |
| command |
When you use the completed method to signal completion of an event handler and set its For an example, see the Smart Alerts walkthrough. |
| context |
When you use the completed method to signal completion of an event handler and set its |
| error |
When you use the completed method to signal completion of an event handler and set its |
| error |
When you use the completed method to signal completion of an event handler and set its |
| send |
When you use the completed method to signal completion of an event handler and set its 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
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 the Don't Send 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
Minimum permission level (Outlook): restricted
Applicable Outlook mode: Compose
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 when the Don't Send button is selected from the Smart Alerts dialog.
For an example, see the Smart Alerts walkthrough.
commandId?: string;Property Value
string
Remarks
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
idattribute 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.
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.
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 Don't Send button is selected from the Smart Alerts dialog.
contextData?: any;Property Value
any
Remarks
Minimum permission level (Outlook): restricted
Applicable Outlook mode: Compose
Important:
In Outlook on Windows, the
anytype is supported starting in Version 2402 (Build 17308.20000). In earlier versions of Outlook on Windows, only thestringtype is supported.If you specify the
contextDataoption in yourevent.completedcall, you must also assign a task pane ID to thecommandIdoption. Otherwise, the JSON data assigned tocontextDatais ignored.To retrieve the value of the
contextDataproperty, you must callOffice.context.mailbox.item.getInitializationContextAsyncin the JavaScript implementation of your task pane. If you create a JSON string usingJSON.stringify()and assign it to thecontextDataproperty, you must parse the string usingJSON.parse()once you retrieve it.
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 displayed to the user. For an example, see the Smart Alerts walkthrough.
errorMessage?: string;Property Value
string
Remarks
Minimum permission level (Outlook): restricted
Applicable Outlook mode: Compose
errorMessageMarkdown
Note
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
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
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
errorMessageMarkdownproperty, we recommend you also add a plaintext version of the message using theerrorMessageproperty. 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
Minimum permission level (Outlook): restricted
Applicable Outlook mode: Compose
Important: Currently, sendModeOverride can only be set to the prompt user option.
Office Add-ins