Downloading the OfficeJS Preview API for Offline Testing

Recently, I had a need to download the preview of the OfficeJS API for testing in an offline environment. The primary (and preferred) way to access the preview beta library is to point to it on the CDN via your HTML, like this:

However, if you need to download this for use offline in testing, you can actually download it using Node Package Manager. All you need is this command:

npm install @microsoft/office-js@beta

I was able to do my testing as if I were online with the CDN, so all was good. Happy coding! wlEmoticon-hotsmile.png

Removing Web Add-in Ribbon Customization in Outlook for Windows

If you are following the latest updates the the OfficeJS API’s, you will see that PowerPoint, Excel and Word have this new feature that allows you to specify an equivalent COM add-in in place of the Web Add-in. Here is the link:  https://docs.microsoft.com/en-us/office/dev/add-ins/develop/make-office-add-in-compatible-with-existing-com-add-in

This is useful for when you have created a Web Add-in but it is not as feature rich as your COM add-in. So on the Windows clients, you still want your COM (or VSTO) solution to run there and not the web version of the add-in.

However, this feature has not yet arrived for Outlook. I am told that this is coming, but for now there really are only two workarounds.

If you are using Office 2016, you can set your manifest requirements to 1.5, like this:

    <Requirements>
      <bt:Sets DefaultMinVersion=”1.5″>
        <bt:Set Name=”Mailbox” />
      </bt:Sets>
    </Requirements>

If you are needing to support Outlook 2019 or Outlook for Office 365, then this easy trick will not work. So what you need to do is a bit more complicated. To start you need to collect some information first:

  1. Open Outlook, and verify that your web add-in customization has loaded.
  2. Go to File, Options, Customize Ribbon:options
  3. At the bottom, click Import/Export and select Export all customizations.
  4. Save the “customui” file to the desktop and then open it in Notepad.
  5. You will look for your customization and it will be in a group or a tab and contain an if like this: x1:Group_5febe0ec-e536-4275-bd02-66818bf9e191_msgEditGroup_TabNewMailMessage.
  6. Make note of this value, minus the namespace (x1:) and whether it is a customtab or a customgroup.

If this does not work for you a couple of other options are to add the Group to the Quick Access bar, by right-clicking on the group and selecting “Add to Quick Access.” This should help it appear in the customUI file. However, if this still does not work, you can make an “educated guess” at the name by using these steps:

  1. Open your manifest file in your Web Add-in and locate the ID:

    5febe0ec-e536-4275-bd02-66818bf9e191

  2.  Next, locate what you called the group in your manifest:

    < Group id=”msgEditGroup” >

  3. Finally, you need to determine which “Ribbon” it is on. This is a tad more complex, but since most following the “TabDefault” option, here are two defaults I know about, that could help you:
    • TabNewMailMessage
    • TabReadMailMessage
  4. From there you can build the Group identifier:

    Group_5febe0ec-e536-4275-bd02-66818bf9e191_msgEditGroup_TabNewMailMessage

  5. If you are working with a custom tab, you would look in your manifest and get the name of the custom tab:

    <CustomTab id=”myTab”>

  6. From there you can build your tab identifier:

    Tab_5febe0ec-e536-4275-bd02-66818bf9e191_myTab

The namespace is what makes this whole process a little harder than expected. This namespace is a UID for the Exchange Account to which the add-in was installed. And this ID is unique to every user and each email account in Outlook. What you will need to do is customize the Ribbon XML in your solution to then hide this group. I have created a solution here on github that shows how to do this end-to-end with a new add-in:

https://github.com/davecra/RemoveOfficeWebAddin

The primary functionality is found in the GetCustomUI function. Here is the function:

What this does is loads a file called RemovedCustomizations.txt from the install directory of the add-in. This file will contain entries like this:

5febe0ec-e536-4275-bd02-66818bf9e191
customgroup,TabNewMailMessage,Group_5febe0ec-e536-4275-bd02-66818bf9e191_msgEditGroup_TabNewMailMessage
customgroup,TabNewMailMessage,Group_5febe0ec-e536-4275-bd02-66818bf9e191_msgDesignGroup_TabNewMailMessage

Important to note, the first entry is the ID of your Web Add-in. This is used to create the namespace entry,

You will use the steps above, to build this list. This is a tad more complex than I had hoped it would be, so please let me know if you get stuck on any parts and/or if there are areas that you think I can elaborate more.

Simple Client-Side JavaScript MIME Parser

Today, I have been working on JavaScript for the first time in a while. I have spent a lot of time lately in VSTO and specifically targeting Outlook. It was good to get back to the OfficeJS side of the house.

A customer of mine requested if there was a way to easily parse the MIME content from the easyEws library call: getMailItemMimeContent

I found a number of server-side JavaScript libraries but nothing that would help me with parsing the data on the client-side. Here is the class I created and I am contemplating incorporating it into it’s own library at some point and expanding on it. But for now, here it is:

To use this, I am demonstrating from an On Send event in OfficeJS. I grab the mail item being composed, save it to make sure it is in the Drafts folder, grab the ID of the message, then use that to grab the MIME data. Here is the sample code:

Visual Studio 2017: This is an invalid xsi:type… mailappversionoverrides/1.1:Event

If you have been using Visual Studio 2017 to create an Outlook Web Add-in and are trying to use the new ItemSend event, you will note per the documentation the you need to add the MailAppVersionOverrides 1.1 to your manifest:

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">

The problem is that when you try to build and run the project, you get this exception:

Severity Code Description
Warning This is an invalid xsi:type ‘http://schemas.microsoft.com/office/mailappversionoverrides/1.1:Events&#8217;.

a

Specifically, Visual Studio 2017 does not like this line:

<ExtensionPoint xsi:type="Events">

If you are like me you have been hoping for an update to Visual Studio 2017 to fix this, but I just got word today that it did not get into the last update to Visual Studio 2017, but will make it into Visual Studio 2019. However, you do not need to run off and install Visual Studio 2019 once it is available. There is a workaround, and here are the steps to follow:

  • If you have an updated Exchange 2016 Server CU9 or later, you can browse to this folder:
    C:\Program Files\Microsoft\Exchange Server\V15\Bin
  • Locate and copy the file MailAppVersionOverridesV1_1.xsd and copy it to a removable drive or a network share.
  • On your development machine, locate the existing MailAppVersionOverridesV1_1.xsd. It should be located here:
    C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Xml\Schemas\1033
  • Rename the existing file to MailAppVersionOverridesV1_1.old.
  • Copy the version of the MailAppVersionOverridesV1_1.xsd you got from your Exchange Server here.

At this point you should be good to go.

But wait!?!?! You say you don’t have an Exchange Server? You use Office 365 and your instance of Exchange is up in the cloud? OK… Now this is not the “preferred” method, but it will get the job done. I created a GIST, and you can download it from here. wlEmoticon-hotsmile.png Simply view RAW, copy, open Notepad, paste, Save As: MailAppVersionOverridesV1_1.xsd, and then you have your file.

makeEwsRequestAsync Error: “The requested web method is unavailable to this caller or application”

If you get the following error when using the Office.context.mailbox.makeEwsRequestAsync() method, it is probably because the supported method is not available to this function:

The requested web method is unavailable to this caller or application

The details of the supported function are outlined in this article on MSDN. If you do not see the method you are trying to call in that table, it is not supported.

However, if you are like me and you do see your function in there, like “ExpandDL” it might be because when you recently updated to CU9 or CU10 (this method was added in CU9), you did not run setup with the “PrepareAD” switch. This last step is required in order to update the policies that allow this function to work. You can also run these two commands from the Exchange PowerShell to update your server:

  • Install-CannedRbacRoles
  • Install-CannedRbacRoleAssignments

NOTE: If these commands are not found, you need to first run this command:
Add-PsSnapin Microsoft*

 

How to Fix IntelliSense in VSCode for OfficeJS

I spent the better part of this morning trying to figure out why a new Yeoman generated Outlook add-in was not working with IntelliSense in VSCode. I would type “Office.” and nothing would appear. I would press CTRL+{SPACE} and still nothing.

After a lot of digging and comparing projects that did work to those that did not, I found that the @types were missing. So I then installed @types/office-js:

npm install @types/office-js

Once I did this, viola! IntelliSense started working like a charm. From my experience this has happened to me a few different times, in these given scenarios:

  • Moving an OfficeJS project from VS2017 to VSCode
  • Moving a Script Lab project to VSCode
  • Creating a blank OfficeJS project from scratch with just two files (manifest and webpage).

In my continued research I found that the way VSCode handles types is through NPM and you need to have data type definition files to get it all to work, that is why you need to install both NPM and the OfficeJS @types to get this to work. Per this page:  https://code.visualstudio.com/Docs/languages/javascript

Automatic Type Acquisition (ATA) uses npm, the Node.js package manager, to install and manage Type Declaration (typings) files. To ensure that Automatic Type Acquisition works properly, first ensure that you have npm installed on your machine.

Secondly to that, for OfficeJS development, make sure you have @types/office-js.

easyEws v1.0.10 Released

In this release I have incorporated two new functions to help with recipients (To/CC/BCC) and groups/distribution lists:

  • getAllRecipientsAsync() – helps you by getting all the unique recipients on the To/CC/BCC lines. It returns two lists in the callback:
    • A list of standard users
    • A list of groups
  • splitGroupsAsync() – accepts an array of groups (or Distribution Groups) and expands them to a unique set of users.

I have also corrected a few small bugs, like one with MailBoxUser (where Address was incorrectly JSDoc’d as Email).

I have also included a minified version of the library. So you can access easyEws.min.js in your code to reduce the download.

You can access it from: