Office.SmartAlertsEventCompletedOptions interface
Specifies the behavior of a Smart Alerts add-in when it completes processing an OnMessageSend or OnAppointmentSend event.
Remarks
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.",
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 |
| 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
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 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
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 specifies the ID of the task pane that opens 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 ID specified in the manifest of your add-in. The markup depends on the type of manifest your add-in uses.
XML manifest: The
idattribute of the Control element representing the task pane.Unified manifest for Microsoft 365: The "id" property of the task pane command in the "extensions.ribbons.tabs.groups.controls" array.
If you specify the contextData option in your event.completed call, you must also assign a task pane ID to the commandId option. Otherwise, the JSON data assigned to contextData is ignored.
contextData
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 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
sendModeOverride
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 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
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for