October 26th, 2016

Use commands to make your add-ins available in the Office ribbon

In March 2016, we released add-in commands for Word, Excel, and PowerPoint for Office desktop and Office Online. Add-in commands were made available in Outlook in November 2015  . Commands enable you to extend the Office UI across multiple platforms. We have seen that users are more likely to continue to use add-ins that have command entry points in the Office ribbon, so using add-in commands can increase the retention rate for your add-ins.    

In this post, we highlight some of the important benefits that commands introduce, as well changes we are making to Office Store policies to require the use of commands in Word, Excel, and PowerPoint add-ins. We are also announcing the deprecation of the custom pane extension point in Outlook add-ins. 

Benefit: Integration with the Office UI

Add-in commands allow you to extend the Office UI to add custom buttons to the Office ribbon. You can extend existing tabs, create your own custom tab, or extend contextual menus. To see add-in commands in action, watch the Add-in commands in the Office ribbon video.

The following are some examples of add-ins that use commands.

Figure 1. Boomerang  add-in extending the Message tab in Outlook

Figure 2. Pickit add-in command in the Office ribbon

Figure 3. XLSTAT add-in custom tab

Benefit: Increased discoverability and retention

Users expect to be able to find all the tools and actions that they need on the Office ribbon. When you adopt commands, you make it easier for users to access and use your add-in. By using commands, you can:

  • Make your add-in more discoverable by placing add-in buttons with relevant user flows.
  • Make your add-in more efficient to use by making specific actions accessible on the ribbon.
  • Provide a familiar experience for users, and increase user retention, by extending the Office suite. Users will be more likely to come back to use your add-in again.

To give you an example of the positive impact that we’ve seen so far, several Outlook add-ins had doubled retention rates after they were updated to use commands.   We are seeing a similar positive impact across add-ins for other applications.

Benefit: Teaching UI

The teaching UI feature is currently rolling out and will be fully deployed in a couple of weeks. You can use teaching UI to show users where an add-in is installed and how to get started using an add-in when they install it from the Office Store. The following is an example of an add-in that uses teaching UI.

Benefit: Support across multiple platforms

Add-in commands for Outlook are already supported for Outlook 2013 and Outlook 2016 desktop, and will be supported in Outlook for Mac and Office Online within the next two months. Add-in commands for Word, Excel, and PowerPoint are currently supported   in Word, Excel, and PowerPoint in Office 2016 desktop clients and Office Online, and will soon be supported in Office for Mac. For the latest support information for this and other features, see Office Add-in host and platform availability.  

Does that mean that you need to wait until commands are supported everywhere to use them in your add-in? Not at all. Today you can create an add-in, with a single manifest and a single submission to the Office Store (if you are distributing via the Store), that targets all the Office platforms that support Office Add-ins. Clients that do not support commands, such as Office 2013, will run your add-in as a task pane.

Benefit: Creating commands is easy

It only takes a few minutes to add commands to your add-in.

If you are creating a new add-in, you can start from one of our existing samples. If you are a Visual Studio developer, you can use the Office Developer Tools. The Office Web Add-in templates include a sample command.

If you have an existing Outlook or task pane   add-in, add a VersionOverrides node to your manifest. You can start by adding a button to launch your task pane. You can also go a step further and re-envision your add-in to take advantage of ribbon integration. For more information, see best practices for using add-in commands.

If you run into issues, see our FAQs for help with troubleshooting. You can also post questions to StackOverflow and tag with [office-js].  

Requirement: New Office store policies and deprecated features

Word, Excel, and PowerPoint add-ins

Effective February 1, 2017, Word, Excel, and PowerPoint add-ins that use the taskpane manifest must use add-in commands in order to pass Office Store validation. This policy will apply to both new submissions and updates to existing Office Store add-ins.

If you need to request an exception to this requirement, indicate the reason for the exception in the testing notes field when you submit your add-in.

Outlook add-ins

Add-in commands are already required for all Outlook add-ins in the Office Store. We are also announcing that custom panes in Outlook will no longer be supported as of February 1, 2017. This applies across all platforms.

Add-in commands provide a significant advantage in terms of user engagement and discoverability over the legacy custom pane experience (shown in the following image).

Effective November 7, 2016, Outlook add-ins submitted to the Office Store must not declare the CustomPane extension point in the VersionOverrides node . This applies to both new submissions and updates to existing Office Store add-ins. This means less work for you as a developer because you don’t have to include an unnecessary extension point if you already have commands.

Call to action

We encourage you to adopt commands in your add-in as soon as possible. You will see higher adoption and retention rates and more satisfied users. The following are the effective dates for the Office Store requirements :

  • New and updated Word, Excel, and PowerPoint add-ins using the taskpane manifest must use commands to pass Office Store validation effective February 1, 2017.
  • Outlook add-ins that do not support commands will be removed from the Office Store effective February 1, 2017.
  • New and updated Outlook add-ins in the Office Store must not include the CustomPane extension point in the VersionOverrides node effective November 7, 2016.