easyEws v1.0.16 Published

I have made a few minor updates to easyEws. First, was a fix for distribution lists with an “&” in the name. The second is a few minor JSDoc updates for better linting. And finally, I changed a couple forEach loops to traditional for loops for performance reasons.

I have published the update to NPM and to my GitHub.

Please let me know if you have any issues or questions.

easyEws v1.0.15 Released

In this latest release I have incorporated my first community pull. A big thank you to Vijay Samtani for adding the sendMailItem. This new addition allows you to create a message to multiple recipients and with zero to many attachments.

Here is a link to the repository: https://github.com/davecra/easyEWS

You can references it in your code:


<script type="text/javascript" src="node_modules/easyews/easyews.min.js"></script>

And you can allow pull it down from NPM:

npm install easyEws

easyEws v1.0.14 released

First off, there is no version 1.0.13. wlEmoticon-winkingsmile.png

For this latest release, I have added one handy new function getParentId(). This function uses the child message “InReplyTo” field to locate the parent message with the same corresponding “InternetMessageId” field. If found, you will get the Id of that parent message. If not found, you will get NULL.

As per usual, to get the latest you can link to the CDN: https://cdn.jsdelivr.net/gh/davecra/easyEws/easyEws.js

Or you can access it from NPM via this command:

npm -install easyews

NOTE: I was informed that I had forgot to update NPM to v1.0.12 per the last release. So I have fixed that and have updated this build on NPM.

easyEws v1.0.12 released

I have updated the easyEws library.

The changes I made in v1.0.11 for ResolveNames were only ES6 compliant and did not work in IE11. Specifically, I defined an ES6 class object versus a more compliant ES3+ function/class. The update was recoded and now functions in IE11.

Additionally, there was a reported issue with recipient aggregation in the getallRecipientsAsync() function. I was using a .forEach() on the recipient array which seemed to be causing problems with larger result sets. So I updated it to use a standard for loop.

Other than that there were no major changes to this version.

easyEws Updated to v1.0.11

It has been a while since I have updated this library, however I have had a few requests.

The first one that I am publishing today is adding the ResolveNames operation. The latest is now on GitHub here. And you can install it using NPM like this:

npm install easyews

Also, I have updated the CDN listing. Before I was using RAWGIT but that has been retired. You can now add the CDN like this:


<html>
<head>
<!– DEBUG –>
<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/davecra/easyEws/easyEws.js"></script>
<!– Or, MINIFIED –>
<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/davecra/easyEws/easyEws.min.js"></script>
</head>
</html>

view raw

easyEwsCDN.html

hosted with ❤ by GitHub

To issue a resolve names you will pass the email address or the display name to the function like this:


async function run() {
var msg = Office.context.mailbox.item;
msg.to.getAsync(function(asyncResult) {
if(asyncResult.status == Office.AsyncResultStatus.Failed) {
$("#recipientResult").text(asyncResult.error);
} else {
/** @type {Office.EmailAddressDetails[]} */
var recips = asyncResult.value;
// are there any recipients at all
if(recips == null || recips.length == 0) {
$("#recipientResult").html("NO RECIPIENTS");
} else {
/** @type {string} */
var info = "<br/>DISPLAY NAME: " + recips[0].displayName + "<br/>" +
"EMAIL_ADDRESS: " + recips[0].emailAddress + "<br/>" +
"RECIPIENT_TYPE: " + recips[0].recipientType;
easyEws.resolveRecipient(recips[0].emailAddress, function(result) {
if(result == null || result.length == 0) {
info += "<br/>UNRESOLVED</br>";
} else {
info += "<br/>RESOLVED: " + result[0].MailBoxType;
info += "<br/>RESOLVED EMAIL: " + result[0].EmailAddress;
}
// write tot he form
$("#recipientResult").html(info);
}, function(error) {
$("#recipientResult").text(error);
}, function(debug) {
$("#debugResult").text(debug)
});
}
}
});
}

view raw

resolveNames.js

hosted with ❤ by GitHub

If you have any suggestions for this library, please ping me.

Expanding Personal Contact Lists in Outlook with OfficeJS

If you are developing an OfficeJS add-in for Outlook or Outlook Online (OWA) and your project requirements have a need to peek inside distribution lists, you might find that there are two kinds:

  • Distribution Lists – these are Exchange groups, or mail enabled Active Directory groups. These are managed by the enterprise IT and contain a list of email addresses and/or other distributions lists.
  • Contact Lists / Private Distribution Lists – these are personal lists created by the user that can contain similar objects.

For an Office Add-in, you must use the makeEwsRequestAsync() command to submit EWS to Exchange. And the specific command you will need to use is ExpandDL to get the members of a DL (or contact list). With regards to the first item in the list above, it is pretty straight forward. For the second item there is this blurb on the page:

Private distribution lists are located in the Contacts folder of a user’s mailbox. Private distribution lists do not have e-mail addresses so their store item identifiers are used in an ExpandDL request. Members of a private distribution list can be any mail-enabled user, contacts or distribution lists from Active Directory, or contacts or private distribution lists from a user’s Contacts folder.

The bold part is key. But where do you get this. When you request a to.getAsync() and receive “Bob’s Favorite People” as a recipient item what do you do with it?

The key is to call the EWS method ResolveNames. When you call this on “Bob’s Favorite People” you will get a return value with PrivateDL and an ItemID (the Exchange Store Item ID in the users Contact folder) that you will then send that ItemId to ExpandDL. Here is what the soap response would look like from ResolveNames:


<?xml version="1.0" encoding="utf-8"?>
<!– Note: EwsEditor has replaced the "utf-16" text in the first line with"utf-8" in order for the XML to render in the response web control. –>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="15" MinorVersion="20" MajorBuildNumber="2305" MinorBuildNumber="24" Version="V2018_01_08" xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
</s:Header>
<s:Body>
<m:ResolveNamesResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:ResolveNamesResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:ResolutionSet TotalItemsInView="1" IncludesLastItemInRange="true">
<t:Resolution>
<t:Mailbox>
<t:Name>Bob's Favorite People</t:Name>
<t:RoutingType>MAPIPDL</t:RoutingType>
<t:MailboxType>PrivateDL</t:MailboxType>
<t:ItemId Id="AAMkADU2NjQzOWIxLWZkMTktNDU2NC04MGYwLTc4OGUxZTQ3ZTQ4OQBGAAAAAABU0Ha8nllhSqfh0CtR+4+uBwAdo3MIorCqSaC1lyH8qlH1AAAAAAEOAAAdo3MIorCqSaC1lyH8qlH1AAQQFxCnAAA=" ChangeKey="EgAAABYAAAAdo3MIorCqSaC1lyH8qlH1AAQQUFsg" />
</t:Mailbox>
</t:Resolution>
</m:ResolutionSet>
</m:ResolveNamesResponseMessage>
</m:ResponseMessages>
</m:ResolveNamesResponse>
</s:Body>
</s:Envelope>

You can then make your ExpandDL request like this:


<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2016" />
</soap:Header>
<soap:Body>
<m:ExpandDL>
<m:Mailbox>
<t:ItemId Id="AAMkADU2NjQzOWIxLWZkMTktNDU2NC04MGYwLTc4OGUxZTQ3ZTQ4OQBGAAAAAABU0Ha8nllhSqfh0CtR+4+uBwAdo3MIorCqSaC1lyH8qlH1AAAAAAEOAAAdo3MIorCqSaC1lyH8qlH1AAQQFxCnAAA=" />
</m:Mailbox>
</m:ExpandDL>
</soap:Body>
</soap:Envelope>

The result will be a list of all the email addresses, like this:


<?xml version="1.0" encoding="utf-8"?>
<!– Note: EwsEditor has replaced the "utf-16" text in the first line with"utf-8" in order for the XML to render in the response web control. –>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="15" MinorVersion="20" MajorBuildNumber="2305" MinorBuildNumber="24" Version="V2018_01_08" xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
</s:Header>
<s:Body>
<m:ExpandDLResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:ExpandDLResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:DLExpansion TotalItemsInView="3" IncludesLastItemInRange="true">
<t:Mailbox>
<t:Name>Bill S. Preston Esquire</t:Name>
<t:EmailAddress>bill@WyldStallyns.ooo</t:EmailAddress>
<t:RoutingType>SMTP</t:RoutingType>
<t:MailboxType>Contact</t:MailboxType>
</t:Mailbox>
<t:Mailbox>
<t:Name>Theodore Logan</t:Name>
<t:EmailAddress>ted@WyldStallyns.ooo</t:EmailAddress>
<t:RoutingType>SMTP</t:RoutingType>
<t:MailboxType>Contact</t:MailboxType>
</t:Mailbox>
<t:Mailbox>
<t:Name>Wyld Stallyns Fans</t:Name>
<t:EmailAddress>fans@WyldStallyns.ooo</t:EmailAddress>
<t:RoutingType>SMTP</t:RoutingType>
<t:MailboxType>Contact</t:MailboxType>
</t:Mailbox>
</m:DLExpansion>
</m:ExpandDLResponseMessage>
</m:ResponseMessages>
</m:ExpandDLResponse>
</s:Body>
</s:Envelope>

NOTE: For now the ResolveNames operation is not supported in my library easyEws. I am working to add it in the coming weeks.

Please let me know if you have any suggestions or questions.

NOTE: I am not an Exchange Web Services (EWS) expert, but have some experience with it through the OfficeJS makeEwsRequestAsync() command. To get the answer for this blog entry, I had to go to a real EWS expert to figure this one out. Many thanks to Dan Bagley (EwsEditor) for his assistance.

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

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 to remove a tab:

5febe0ec-e536-4275-bd02-66818bf9e191
customtab,Tab_5febe0ec-e536-4275-bd02-66818bf9e191_myTab,

If you want to remove a group on an existing Outlook tab, it looks like this:

5febe0ec-e536-4275-bd02-66818bf9e191
customgroup,TabMail,Group_5febe0ec-e536-4275-bd02-66818bf9e191_msgReadGroup_TabMail

And this is a bit more tricky, but if you need to remove an item from a context ribbon in Outlook, you will add an entry like this:

5febe0ec-e536-4275-bd02-66818bf9e191
customgroup,TabComposeTools\TabMessage,Group_5febe0ec-e536-4275-bd02-66818bf9e191_msgComposeGroup

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 item by item. And it is important to note that your item may appear on multiple tabs. For example, if your manifest is putting your custom group on TabDefault, that could end up in two places for a Compose message:

  • TabMail
  • TabComposeTools\TabMessage

The latter is a context tab and you have to specify the context tab name first, then the tab name. The tab name alone will not help. Finding the context tab is a bit more complex, but you can get those identifiers from here.

So in the end you might end up with a RemoveCustomizations.txt file that looks like this:

5febe0ec-e536-4275-bd02-66818bf9e191
customtab,Tab_5febe0ec-e536-4275-bd02-66818bf9e191_myTab,
customgroup,TabMail,Group_5febe0ec-e536-4275-bd02-66818bf9e191_msgReadGroup_TabMail
customgroup,TabComposeTools\TabMessage,Group_5febe0ec-e536-4275-bd02-66818bf9e191_msgComposeGroup

Overall, 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.

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.

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:

 

Updated Outlook Web Add-in Sample

I will be presenting a demo at the MVP Summit 2018 for Outlook and also helping with some labs in Excel on the OfficeJS platform. In preparation, I updated my Outlook Sample on my GitHub. This sample was created in VSCode via a Yeoman template.

What the add-in does is a check of all users on the To/CC/BCC line, splits apart any groups (or groups in groups) and then checks to see if any of the user emails are external to your domain. If any external users are found it prompts you with dialog asking if you are sure you want to send:

Outlook Blocking Add-in

The updated add-in demonstrates:

  • The OnSend event
  • The use of dialogs
  • And the newly added ExpandDL function for Exchange Web Services through the makeEwsRequestAsync() call.

In this sample, I am using both of my libraries:

  • easyEws – to help with the ExpandDL call. Updated in a previous post.
  • OfficeJS.dialogs – to display the dialog you see above.

I also had to create a set of asynchronous functions and asynchronous recursive function calls to perform this work – which got a tad complex. For now all the code is in the function-file.js, but to help with splitting out all recipients and groups I might build this into a new library. For example, here is the function to recursively call itself asynchronously (splitting groups in groups in groups in groups…):


/**
* Splits a group and calls the completed function
*/
function splitGroupsAndFindExternalsRecursivelyAsync() {
if(groups.length == 0) {
// if no groups stop
completedCallback();
} else {
/** @type {string} */
var group = groups.pop();
// call expandGroup to get users
easyEws.expandGroup(group, function(groupUsers) {
groupUsers.forEach(function(groupUser, index){
if(groupUser.MailboxType() == "PublicDL") {
groups.push(groupUser);
} else {
/** @type {string} */
var emailDomain = getDomain(groupUser.Address());
if(emailDomain != domain) {
externals.push(groupUser.Address());
}
}
}); // groupUsers.forEach
splitGroupsAndFindExternalsRecursivelyAsync(); // recursive
}, function(error) {
console.log(error);
// just fail
completedCallback();
}); // easyEws.expandGroup
} // end-if
}

Anyway, I will be demonstrating this add-in and the functionality required at the MVP Summit. So if you are attending, I hope to see you there.