Edit

Share via

Action element

  • Article

Specifies the action to perform when the user selects a Button or Menu control.

Valid only in these VersionOverrides schemas:

  • Task pane 1.0
  • Mail 1.0
  • Mail 1.1

For more information, see Version overrides in the add-in only manifest.

Associated with these requirement sets:

  • AddinCommands 1.1 when the parent <VersionOverrides> is type Taskpane 1.0.
  • Mailbox 1.3 when the parent <VersionOverrides> is type Mail 1.0.
  • Mailbox 1.5 when the parent <VersionOverrides> is type Mail 1.1.

Attributes

Attribute Required Description
xsi:type Yes Action type to take

xsi:type

This attribute specifies the kind of action performed when the user selects the button. It can be one of the following:

  • ExecuteFunction
  • ShowTaskpane

Once the user selects a button that kicks off the ExecuteFunction action, the add-in times out after 5 minutes if it hasn't completed by then.

Important

Outlook: Registering Mailbox and Item events is not available when xsi:type is ExecuteFunction.

Child elements

The valid child elements very depending on the value of the xsi:type parameter.

xsi:type is ExecuteFunction

Element Description
FunctionName Specifies the name of the function to execute.

FunctionName

Required element when xsi:type is ExecuteFunction. Specifies the name of the function to execute. The function is contained in the file specified in the FunctionFile element.

<Action xsi:type="ExecuteFunction">
  <FunctionName>getSubject</FunctionName>
</Action>

xsi:type is ShowTaskpane

Element Description
SourceLocation Specifies the source file location for this action.
 TaskpaneId Specifies the ID of the task pane container. Not supported in Outlook add-ins.
 Title Specifies the custom title for the task pane. Not supported in Outlook add-ins.
 SupportsPinning Specifies that a task pane supports pinning, which keeps the task pane open when the user changes the selection. Supported in Outlook only.
SupportsMultiselect Specifies that an Outlook add-in can activate on multiple selected messages. Supported in Outlook only.
SupportsNoItemContext Specifies that an Outlook add-in can activate without the Reading Pane enabled or a message selected. Supported in Outlook desktop clients only.

SourceLocation

Required element when xsi:type is ShowTaskpane. Specifies the source file location for this action. The resid attribute can be no more than 32 characters and must be set to the value of the id attribute of a <Url> element in the <Urls> element in the Resources element.

<Action xsi:type="ShowTaskpane">
  <SourceLocation resid="readTaskPaneUrl" />
</Action>

TaskpaneId

Optional element when  xsi:type is ShowTaskpane. Specifies the ID of the task pane container. When you have multiple ShowTaskpane actions, use a different <TaskpaneId> if you want an independent pane for each. Use the same <TaskpaneId> for different actions that share the same pane. When users choose commands that share the same <TaskpaneId>, the pane container will remain open but the contents of the pane will be replaced with the corresponding Action SourceLocation.

Add-in type: Task pane

Valid only in these VersionOverrides schemas:

  • Task pane 1.0

For more information, see Version overrides in the add-in only manifest.

Associated with these requirement sets:

Note

This element is not supported in Outlook.

The following example shows two actions that share the same <TaskpaneId>.

<Action xsi:type="ShowTaskpane">
  <TaskpaneId>MyPane</TaskpaneId>
  <SourceLocation resid="aTaskPaneUrl" />
</Action>

<Action xsi:type="ShowTaskpane">
  <TaskpaneId>MyPane</TaskpaneId>
  <SourceLocation resid="anotherTaskPaneUrl" />
</Action>

The following examples show two actions that use a different <TaskpaneId>. To see these examples in context, see Simple Add-in Commands Sample.

<Action xsi:type="ShowTaskpane">
   <TaskpaneId>MyTaskPaneID1</TaskpaneId>
   <SourceLocation resid="Contoso.Taskpane1.Url" />
</Action>

<Action xsi:type="ShowTaskpane">
   <TaskpaneId>MyTaskPaneID2</TaskpaneId>
   <SourceLocation resid="Contoso.Taskpane2.Url" />
</Action>

<bt:Urls>
   <bt:Url id="Contoso.Taskpane1.Url" DefaultValue="https://commandsimple.azurewebsites.net/Taskpane.html" />
   <bt:Url id="Contoso.Taskpane2.Url" DefaultValue="https://commandsimple.azurewebsites.net/Taskpane2.html" />
</bt:Urls>

Title

Optional element when  xsi:type is ShowTaskpane. Specifies the custom title for the task pane for this action.

Add-in type: Task pane

Valid only in these VersionOverrides schemas:

  • Task pane 1.0

For more information, see Version overrides in the add-in only manifest.

Associated with these requirement sets:

Note

This child element is not supported in Outlook add-ins.

The following example shows an action that uses the <Title> element. Note that you don't assign the <Title> to a string directly. Instead, you assign it a resource ID (resid), that is defined in the <Resources> section of the manifest and can be no more than 32 characters.

<Action xsi:type="ShowTaskpane">
    <TaskpaneId>Office.AutoShowTaskpaneWithDocument</TaskpaneId>
    <SourceLocation resid="PG.Code.Url" />
    <Title resid="PG.CodeCommand.Title" />
</Action>

 ... Other markup omitted ...
<Resources>
    <bt:Images> ...
    </bt:Images>
    <bt:Urls>
        <bt:Url id="PG.Code.Url" DefaultValue="https://localhost:3000?commands=1" />
    </bt:Urls>
    <bt:ShortStrings>
        <bt:String id="PG.CodeCommand.Title" DefaultValue="Code" />
    </bt:ShortStrings>
 ... Other markup omitted ...
</Resources>

SupportsPinning

Optional element when xsi:type is ShowTaskpane. The containing VersionOverrides elements must have an xsi:type attribute value of VersionOverridesV1_1. Include this element with a value of true to support task pane pinning. The user will be able to "pin" the task pane, causing it to stay open when changing the selection. For more information, see Implement a pinnable task pane in Outlook.

Add-in type: Mail

Valid only in these VersionOverrides schemas:

  • Mail 1.1

For more information, see Version overrides in the add-in only manifest.

Associated with these requirement sets:

Important

Although the SupportsPinning element was introduced in requirement set 1.5, it's currently only supported for Microsoft 365 subscribers using the following:

  • Modern Outlook on the web
  • new Outlook on Windows
  • Outlook 2016 or later on Windows (Version 1612 (Build 7628.1000) or later)
  • Outlook on Mac (Version 16.13 (18050300) or later)
<Action xsi:type="ShowTaskpane">
  <SourceLocation resid="readTaskPaneUrl" />
  <SupportsPinning>true</SupportsPinning>
</Action>

SupportsMultiselect

Optional element in Outlook add-ins when xsi:type is ShowTaskpane. Include a value of true to allow an add-in to activate and perform specific operations on multiple selected messages. Because item multi-select only applies to messages, the ExtensionPoint element's xsi:type attribute value must be set to MessageReadCommandSurface or MessageComposeCommandSurface. To learn more about item multi-select, see Activate your Outlook add-in on multiple messages.

Add-in type: Mail

Valid only in these VersionOverrides schemas:

  • Mail 1.1

For more information, see Version overrides in the add-in only manifest.

Associated with these requirement sets:

<Action xsi:type="ShowTaskpane">
    <SourceLocation resid="readTaskpaneUrl" />
    <SupportsMultiSelect>true</SupportsMultiSelect>
</Action>

SupportsNoItemContext

Optional element in Outlook add-ins when xsi:type is ShowTaskpane. Include a value of true to allow an add-in to activate without the Reading Pane enabled or a message selected. If <SupportsNoItemContext> is set to true, the ExtensionPoint element's xsi:type attribute value must be set to MessageReadCommandSurface. To learn more, see Activate your Outlook add-in without the Reading Pane enabled or a message selected.

Add-in type: Mail

Valid only in these VersionOverrides schemas:

  • Mail 1.1

For more information, see Version overrides in the add-in only manifest.

Associated with these requirement sets:

Note

Although Outlook on the web and new Outlook on Windows support Mailbox requirement set 1.13, an add-in won't activate if the Reading Pane is hidden or a message isn't first selected. To learn more, see Feature support in Outlook on the web and new Outlook on Windows.

<Action xsi:type="ShowTaskpane">
    <SourceLocation resid="Taskpane.Url"/>
    <SupportsNoItemContext>true</SupportsNoItemContext>
</Action>