Share via

extensionRuntimesActionsItem object

  • Article

Specifies the set of actions supported by this runtime. An action is either running a JavaScript function or opening a view such as a task pane.

Properties that reference this object type:

Syntax

{
  "id": "{string}",
  "type": "executeFunction | openPage | executeDataFunction",
  "displayName": "{string}",
  "pinnable": {boolean},
  "view": "{string}",
  "multiselect": {boolean},
  "supportsNoItemContext": {boolean}
}

{
  "id": "{string}",
  "type": "executeFunction | openPage",
  "displayName": "{string}",
  "pinnable": {boolean},
  "view": "{string}",
  "multiselect": {boolean},
  "supportsNoItemContext": {boolean}
}

Properties

id

Specifies the ID for the action.

Tip

When the type value is executeFunction or executeDataFunction, the ID used here is is passed to the code file. In that file, the ID is mapped to a specific JavaScript function by a call of Office.action.associate in the code file. In most cases, you can just use the same string as the actual name of the function. But the code file can also have branching logic that maps different functions onto the action ID depending on which branch is taken. In that case, consider using a more generic action ID, but be as descriptive as possible. If possible, avoid uninformative action IDs such as "action".

Type
string

Required
✅

Constraints
Maximum string length: 64.

Supported values

type

Specifies the type of action. The following are the possible values.

  • openPage: Opens a page in a task pane.
  • executeFunction: Runs a JavaScript function, usually invoked by a button, menu item, or keyboard shortcut. For more information, see Create add-in commands.
  • executeDataFunction: Runs a JavaScript function that is invoked by a Copilot agent.

Note

  • Once the user starts an action of type executeFunction, the runtime in which it executes times out after five minutes if the function hasn't completed by then.
  • Once the user starts an action of type executeDataFunction, the runtime in which it executes times out after two minutes if the function hasn't completed by then.
  • Outlook Mailbox and Item event handlers can't be registered in executeFunction or executeDataFunction actions. Only functions invoked from a task pane can do this.

Type
string

Required
✅

Constraints

Supported values
Allowed values: executeFunction, openPage, executeDataFunction.

type

Specifies the type of action. The following are the possible values.

  • openPage: Opens a page in a task pane.
  • executeFunction: Runs a JavaScript function, usually invoked by a button, menu item, or keyboard shortcut. For more information, see Create add-in commands.

Note

  • Once the user starts an action of type executeFunction, the runtime in which it executes times out after five minutes if the function hasn't completed by then.
  • Outlook Mailbox and Item event handlers can't be registered in executeFunction actions. Only functions invoked from a task pane can do this.

Type
string

Required
✅

Constraints

Supported values
Allowed values: executeFunction, openPage.

displayName

If the add-in includes a custom keyboard shortcut to invoke the action, this property specifies a description of a shortcut in a dialog that reports a conflict between the custom shortcut and a shortcut built into Office or installed with another add-in. This property is not the label of a button or a menu item that invokes the action (which is configured with tabs.groups.controls.label).

This property is localizable. For more information, see the localization schema.

Type
string

Required
—

Constraints
Maximum string length: 64.

Supported values

pinnable

Specifies that a task pane supports pinning, which keeps the task pane open when the user changes the selection.

This property is used only when actions.type is openPage. For more information, see Implement a pinnable task pane in Outlook.

Important

Pinning a task pane is 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)

Type
boolean

Required
—

Constraints

Supported values

view

Specifies a descriptive name for the task pane container; for example, "MainAppDashboard".

This property is used only when actions.type is openPage. When you have multiple openPage actions, use a different view if you want an independent pane for each. Use the same view for different pages that share the same pane. When users choose an action of type openPage that shares the same view, the pane container will remain open, but the contents of the pane will be replaced with the corresponding runtimes.code.page.

Note

The view property isn't supported in Outlook.

Type
string

Required
—

Constraints
Maximum string length: 64.

Supported values

multiselect

Specifies whether the end user can select multiple email messages, and apply the action to all of them.

This property is only supported in Outlook add-ins, and only when the extensions.ribbons.contexts array includes mailRead or mailCompose. To learn more about item multi-select, see Activate your Outlook add-in on multiple messages.

Type
boolean

Required
—

Constraints

Supported values
Default value: False.

supportsNoItemContext

Enables task pane add-ins to activate without the reading pane enabled or a message selected.

This property is only supported in Outlook add-ins, and only when the extensions.ribbons.contexts array includes mailRead. To learn more, see Activate your Outlook add-in without the Reading Pane enabled or a message selected.

Note

In Outlook on the web and new Outlook on Windows, 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.

Type
boolean

Required
—

Constraints

Supported values
Default value: False.

Examples

{
    "extensions": [
        {
          "runtimes": [
            {
              "actions": [
                {
                  "id": "ShowTaskPane",
                  "type": "openPage",
                  "view": "MainAppDashboard"
                },
                {
                  "id": "InsertText",
                  "type": "executeFunction"
                },
                {
                  "id": "DeleteTableHeader",
                  "type": "executeFunction"
                }
              ]
            }
          ],
        }
    ]
}