Pinnable Taskpane in Outlook 2016


Have your add-in users been asking you for the ability to leave the add-in taskpane open in their mailbox as they switch between messages? At Ignite this year, we announced the addition of a new feature for Outlook add-ins, the Pinnable Taskpane. Today we are excited to announce this feature is now officially available in the subscription version (C2R) of Outlook 2016 for Windows users! The feature is identifiable by a pin icon as shown in the screenshot below and will only be available for taskpanes which have explicitly added support. We’ve provided some getting started instructions in this post.

A screenshot of a pinnable taskpane in Outlook.

A screenshot of a pinnable taskpane in Outlook. Note the pin icon in the upper right corner of the taskpane.

Please note the pinnable taskpane functionality defaults to off.  We chose to do this because we wanted the users to remain in control of their Outlook experience.  To ensure users leverage the “pinning” functionality we encourage you to show some teaching UI to tell users they can pin the add-in, if they want. Take a look at our design guidelines around First-Run experiences and toast notifications.

There are two main changes that need to be made to add-ins to support the Pinnable Taskpane: updating the manifest and registering for the ItemChanged event.

Updating the manifest

Last year we added a VersionOverrides version 1.0 section to the manifest with the release of add-in commands. As we continued to add new functionality we introduced VersionOverrides version 1.1 which is what you’ll need to add support for the Pinnable Taskpane. Adding the SupportsPinning tag to a ShowTaskPane action of a control indicates that the task pane support pinning. Below is an example of an extension point that supports pinning. Notice the SupportsPinning tag.

<Control xsi:type="Button" id="Contoso.Button0">
  <Label resid="residTaskpaneButton"></Label>
  <Tooltip>
    <Title resid="residTipTitle"></Label>
    <Description resid="residTipDescription"></Label>
  </Tooltip>

  <Icon>
    <bt:Image size="16" resid="functionIcon" />     
    <bt:Image size="32" resid="functionIcon" />
    <bt:Image size="80" resid="functionIcon" />
  </Icon>

  <Action xsi:type="ShowTaskPane">
    <SourceLocation resid="residTaskpaneUrl"/>
    <SupportsPinning>true</SupportsPinning>
  </Action>
</Control>

Registering for the ItemChanged Event

Now that the taskpane’s support has been declared in the manifest, the add-in must register to get an event when a new item is shown in the user’s mailbox. This can be done by leveraging the new Office.context.mailbox.addHandlerAsync API in Office.initialize. This API takes the following parameters: eventType, handler[,options], callback. Be sure to register for the ItemChanged event. Below is an example of how this might look:

Office.context.mailbox.addHandlerAsync(
  Office.EventType.ItemChanged,
  function(eventArgs) {
    // This is the event handler. Do something here.
  },
  function(asyncResult) {
    // This is callback for addHandlerAsync. This will be called ONCE when the event is registered.
  }
);

Interested in learning more about the Pinnable Taskpane? Take a look at the documentation here.

Comments (19)

  1. Sandun Tharaka says:

    Hello,
    I tried to make Pinnable taskpane in outlook Add-in. I followed same given instructions. But it not works.My current Outlook version [1702] ,Can you please share a sample project of Pinnable taskpane.

    1. Per the documentation: “Note: Pinnable taskpanes are currently only supported by Outlook 2016 for Windows (build 7668.2000 or later for users in the Current or Office Insider Channels, build 7900.xxxx or later for users in Deferred channels).” For a sample, see https://github.com/jasonjoh/command-demo. The taskpane on the message read form is pinnable.

  2. Kranthi Kumar Vulpe says:

    Hi Jason Johnston,
    I am developing add in which works in web, client, Ipad, Mac , I want the Add-in to be Pinnable taskpane , is it possible to make it pinnable in all these platforms?
    many Thanks!

    1. Not yet, but we’re working on it. I don’t have a timeframe to share though.

      1. Frank Martin says:

        Hi – is there currently support for a taskpane on the right for Mac, either pinnable or non-pinnable?

        1. Yes task panes are supported on Mac. Pinnable feature isn’t there yet though.

          1. Frank Martin says:

            Hi Jason,

            We are seeing the task pane on Outlook 365 and also Windows 2013 Outlook. However on a Mac we still see it under the emails and not on right as a task pane. Is there a setting in the manifest to make this work on a Mac?

          2. Frank Martin says:

            To clarify- we are using Outlook 2016 for Mac

          3. Are you using VersionOverrides in the manifest to add buttons to the ribbon? https://dev.office.com/docs/add-ins/outlook/add-in-commands-for-outlook

          4. Hi Jason,

            We have two questions here:
            1. How to achieve always Pinnable option?
            2. Add-in not being rendered as Task Pane(Side loading) in Mac instead rendering in the bottom of action button?

            For Question 1: I’m testing with Add-in Command Demo sample project which has VersionOverrides in Manifest. I’m not seeing Add-in always pinned to right. Our outlook version: 2016 MSO (16.0.4498.1000) 32-bit. Does this mean we need to upgrade Outlook?
            https://github.com/jasonjoh/command-demo

            For Question 2: As of now it is loading fine as a task pane in outlook client windows, webmail, I-pad except Outlook client in MacBook. Is there any pre-requisites or configurations in manifest needed to make the add-in to load in a task pane(as Side loader) in MacBook?

          5. For #1, yes you need to update. https://dev.office.com/docs/add-ins/outlook/manifests/pinnable-taskpane gives the versions needed. For #2, you also probably need to update. I’m assuming you have Outlook 2016 for Mac? Are you not seeing the buttons added into the ribbon?

          6. Jason,
            For #1: I’m using Outlook 2016 as already mentioned and I belive the only way you can update Outlook is through “Windows Update”. My system is showing it’s already up-to-date. Why is my “Windows Update” not installing the build version that you are referring to? Is there any other way I can get the latest update?
            For #2: Our company has license for Outlook 2015 in Mac. I’ve run the “Windows Update” today, Now, I can see buttons in the ribbon. So, this issue is resolved. Appreciate your help!!

          7. You should check in Outlook itself, under File->Office Account. Do you have an “Update Options” button there? If not, you have an MSI-based installation (rather than the Office 365 Click-to-Run type of install). In that case the updates work differently. Let me check on the status of pinnable in MSI builds.

          8. The pinnable task pane feature hasn’t made it to MSI builds yet. It’s only available right now in click-to-run from Office 365 installations. https://support.office.com/en-us/article/Overview-of-update-channels-for-Office-365-ProPlus-9ccf0f13-28ff-4975-9bd2-7e4ea2fefef4

          9. Frank Martin says:

            Bharath can you share with Jason the version you are seeing?

            Jason – we are building an enterprise CRM software add-in, would it be possible for you to contact me at frank.martin@pega.com? Thanks

          10. Frank,
            It’s there in my previous post. Our outlook version: 2016 MSO (16.0.4498.1000) 32-bit

  3. Shyam Sundar Sah says:

    Hi , I am developing Outlook apps for outlook desktop and Web App. I used MVC 5 for rendering file in Task Panel. It is working in Outlook desktop version but not rendering for Outlook Web apps. After that , I tried aspx file again I got same issue . Does outlook web apps only render html and javascript ???. I also tried to render using node, express.js with web project but got same issue?? I am suffering from rendering issue. It says something goes to wrong…………….
    https://support.office.com/en-us/article/-Something-went-wrong-error-when-you-try-to-start-an-Office-app-4b4471dd-cf86-4a37-910d-35a01a6c7d17

    I hope you will response me

    1. I don’t know of any reason that an ASP MVC app would not work for an add-in. This isn’t the place to provide troubleshooting support, I’d recommend posting on StackOverflow with the tag outlook-web-addins.

  4. Sandy Atkinson says:

    Is their an ETA on Pinnanble task panes on Mac Outlook 2016?

Skip to main content