David E. Craig

easyEws v1.0.14 released

April 22, 2020 David E. CraigLeave a comment

First off, there is no version 1.0.13.

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

April 16, 2020April 15, 2020 David E. CraigLeave a comment

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.

Office Scripts: The future is here

April 3, 2020April 2, 2020 David E. Craig2 Comments

Microsoft has been working hard to make Office available on every platform. One of the biggest changes has been the ability to run Office the a browser or Office online. However, one drawback has been that automation in Office online has been limited to Web Add-ins which are aimed solidly at professional developers. However, Visual Basic for Applications (VBA) macros are only supported in Windows and Mac clients. They are not supported on the web platform, the iOS or Android platforms. And, well, they still are not. However, something new has arrived which will allow you to create “macros” anywhere, on any platform (eventually).

Microsoft recently announced Office Scripts. It is an end-user approachable, web and collaborative supported scripting language. It is still in preview and only supported in Excel online, for now.

First, to access this you must have your administrator enable it in the Office 365 Portal:

For citizen programmers this line from the above page says it all:

Scripts allow you to record and replay your Excel actions on different workbooks and worksheets. If you find yourself doing the same things over and over again, an Office Script can help you by reducing your whole workflow to a single button press.

So, I enabled it in my test tenant and created the quintessential “Hello Wold” Action Recording. When your administrator enables this on your tenant, you will get this new Automation tab:

From there, I clicked on Record Actions, typed “Hello World!” in cell A1, and then stopped the macro. It then asked me to name it and give a description (optional), and then Save. From there it opened the Code Editor and here is what I see:

	async function main(context: Excel.RequestContext) {
	// Set range A1 on selectedSheet
	let workbook = context.workbook;
	let worksheets = workbook.worksheets;
	let selectedSheet = worksheets.getActiveWorksheet();
	selectedSheet.getRange("A1").values = [
	["Hello World"]
	];
	}

view raw

HelloWorld.js

hosted with ❤ by GitHub

Once you open a new workbook, you can then click on the Code Editor button and you will see all your recorded scripts:

The future is here. Check it out now. You can learn more about Office Scripts from here: https://docs.microsoft.com/en-us/office/dev/scripts/tutorials/excel-tutorial.

What is Office 365, really?

March 23, 2020 David E. Craig1 Comment

In my day-to-day dealings with people and organizations, there is a common confusion on the term “Office 365.” And that confusion is fed by a few common myths that I have heard repeated by some very smart people in those organizations. So, first, let me dismiss the myths…

The first one is that Office 365 is online, in the browser applications only… NO! Office 365 is NOT just Excel Online, Word Online, PowerPoint Online, Outlook Online, and OneNote Online.
And the second myth is that the desktop applications are getting deprecated… NO! Microsoft is NOT doing away with the installed desktop applications on Windows and Mac in favor of web based versions.

So let’s get to the question:

If Microsoft is not replacing Office with web versions, then what the heck is all this Office 365 and cloud stuff then?

Primarily, Office 365 is the name of the subscription. You no longer buy the Office applications on disks and install them, then buy the next version, etc. With the subscription you always get the newest version (and much more). As you will read from the link above, there are lots of FAQ’s and other information that explain how this works.

So Excel Online, ET AL. is PART of the Office 365 subscription based platform. Office 365 still includes the traditional Microsoft Office desktop applications on the PC/Windows or the Mac. And they are not going anywhere. When you hear that your organization is moving to Office 365 it does not mean you will ONLY be accessing Office from a web browser.

Office 365 is really Office anywhere, on any device. For example, Office 365 also includes applications on iPhone, iPad, and Android. And it is not just the traditional applications. There are incredible tools such as Forms, Sway, Teams, and for developers the Graph API. It also shifts workloads like Exchange Server for mail and SharePoint server for document management from local IT servers to servers run by Microsoft in the cloud.

So when you hear Office 365, DO NOT THINK GOOGLE DOCS. The online versions of Office are only there to provide an additional avenues to access Office from anywhere, on any device. Per the Office 365 website:

Works across multiple devices

Get the fully installed Office apps on multiple PCs, Macs, tablets, and mobile devices (including Windows, iOS, and Android).

They are not as fully featured and as such you really need to consider when you might use them over using the traditional Microsoft Office desktop applications. Per this site (my emphasis added):

Office for the web (formerly Office Web Apps) opens Word, Excel, OneNote, and PowerPoint documents in your web browser. Office for the web makes it easier to work and share Office files from anywhere with an internet connection, from almost any device. Microsoft Office 365 customers with Word, Excel, OneNote, or PowerPoint can view, create, and edit files on the go. …

The following tables compare Office for the web feature capabilities to feature-rich Microsoft Office desktop apps.

So, if you like your Excel just the way it is, installed on your scientific workstation with a bazillion gigabytes of RAM, you can still run it there if you move to Office 365. What you get with the traditional Office applications is more frequent, seamless and automatic updates from the web. Per the Office 365 website:

Monthly Updates

Get the latest features and capabilities with fully installed and always up-to-date versions of Outlook, Word, Excel, PowerPoint for Windows or Mac, OneNote (features vary), Teams, and Access and Publisher (PC only).

Hopefully, this has helped clear up and dispel the myths. And when you go back to the smart person that has told you otherwise, and continues to insist and tell you otherwise, please send them here.

Web Add-in Side Loader Tool

March 23, 2020March 20, 2020 David E. Craig3 Comments

Whether you have been following the guidance for Centralized Deployment of Web Add-ins or you do not have Office 365 and you want to create a SharePoint catalog for deployment, but realize it has limitations:

App catalogs on SharePoint do not support add-in features that are implemented in the VersionOverrides node of the add-in manifest, such as add-in commands.

You essentially try all the options on this page and find that side loading is the only method that will work. So you give it a shot, it works and now you are wondering how to deploy that to a larger group of users.

That is where this new tool that a fellow co-worker (Marty Andren) and I created will come in handy: The Web Add-in Side Loader Tool. Here is the link to the GitHub where it and it’s documentation are located:

https://github.com/davecra/WebAddinSideloader

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

Extended MessageBox Library

March 20, 2020 David E. Craig2 Comments

Several years ago I created this class to assist with making a better, more useful Message Box windows in Add-ins and other projects. You can find it here in my GitHub repository:

Extended MessageBox Library

There were a few times I wanted to show the user a message, but also provide them with a link. Other times I found that I needed to present an error to the user, but wanted to hide more “technical” details from them, unless they clicked a More Info button. I also found cases where I needed to present an error if the user wanted to stop a potentially unattended process, but also wanted the message to dismiss after a period of time so the process could continue. Other times I wanted to present the user with a useful message, but an option to “Do not show this message again.”

After creating custom forms, over and over again, this C# library was born. I recently was writing a VSTO add-in that needed the later option – do not show again – and dusted off this old library, cleaned it up a bit (not not completely) and used it again. I figured, for posterity, I would share this with everyone since I have found it so useful over the years.

For the most part you use this exactly like you would the regular MessageBox object, with some extra goodies included.

For example, this will create a very simple Message box that will look fmailiar:

ExtendedMessageBox.Show(“Hello World”);

Produces this:

A more common scenario you might need with a checkbox, looks like this:

	ExtendedDialogResult LobjResult = ExtendedMessageBox.Show("Hello World – Are you ok?",
	"The Office Context",
	MessageBoxButtons.OKCancel,
	MessageBoxIcon.Information,
	"Do not show this message again.");
	if(LobjResult.Result == DialogResult.OK && LobjResult.IsChecked)
	{
	// do something
	}

view raw

ExtendedMessageBoxCheckboxSample.cs

hosted with ❤ by GitHub

There are a lot more options and capabilities. I will not cover them all here, but they will be detailed in the README in the GitHub repository.

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

OfficeJS.dialogs Updated to v1.0.9

March 5, 2020March 18, 2020 David E. Craig1 Comment

Like yesterday with easyEws, it has been a while since I have touched the OfficeJS.Dialogs library. I updated it yesterday with a quick fix and some content updates. I have had questions about using it from a CDN. The primary issue is that the displayDialogAsync() API does not support CDN. It just displays the HTML as raw text in the dialog. There are some ways I can provide this as a workaround, but it involves me support infrastructure. So, the better thing is to just wait for the API to support CDN’s.

If you have any questions about using this library, please let me know.

easyEws Updated to v1.0.11

March 4, 2020 David E. Craig1 Comment

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

February 11, 2020 David E. CraigLeave a comment

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>

view raw

ResolveNamesResponse.xml

hosted with ❤ by GitHub

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>

view raw

ExpandDLOperation.xml

hosted with ❤ by GitHub

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>

view raw

ExpandDLSoapResponse.xml

hosted with ❤ by GitHub

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.

Downloading the OfficeJS Preview API for Offline Testing

January 23, 2020 David E. CraigLeave a comment

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:

	<head>
	<meta charset="UTF-8" />
	<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
	<title>My OfficeJS Add-in</title>
	<script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.9.1.min.js" type="text/javascript"></script>
	<!–<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>–>
	<!– PREVIEW API CDN –>
	<script src="https://appsforoffice.microsoft.com/lib/preview/hosted/Office.js" type="text/javascript"></script>
	</head>

view raw

previewapi.html

hosted with ❤ by GitHub

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!