easyEws Updated to v1.0.17

July 13, 2020 David E. CraigLeave a comment

There is one major change and one fix in this update:

The library no longer has any dependencies on jQuery. As such all parsing is done with DOMParser and all loops are traditional (for, versus $.each()).

NOTE: This is a fairly major change as it touches the core asyncEws call, which is at the very core over every call in the library. If you have an issue with this build, please point to the previous build of the library directly. See more below…
The sendPlainTextEmailWithAttachment() function was fixed to submit parameters as a Object versus individually.

The GitHub repository has all previous versions. For example, to access the primary CDN, go to:

https://cdn.jsdelivr.net/gh/davecra/easyEws/easyEws.js

If you need to access a specific version (like the last one):

https://cdn.jsdelivr.net/gh/davecra/easyEws/easyEws1.0.16.js

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

Office Web Add-in Debugging in VS Code

June 17, 2020June 16, 2020 David E. CraigLeave a comment

Another recent announcement that has me excited is the ability to debug Office Web Add-ins directly from VS Code. Before this recent announcement, it was a hit or miss proposition. There was Visual Studio 2019, that did a pretty good job. But I liked the lightweight simplicity of VS Code. Visual Studio 2019 seemed too too heavy-weight. It’s hard to put my finger on how or why, but I really enjoy VS Code for Web Add-in development so much better. Except for debugging…

So, to debug, I actually did most of my dev/test in the web versions of Office (Excel online, Outlook online, etc.). Then came the Edge Developer Tools Preview which helped debug task pane add-ins in the full clients. But that did not help with things like the On Send event in Outlook or other UI-less functions. So, it was a struggle at times.

Now that has all changed!!!

The process is a tad more complicated than I like, but it does work. Essentially, you need to:

Run VS Code as administrator
Install the extension in VS Code by pressing CTRL + SHIFT + X and searching for the “Microsoft Office Add-in Debugger”
Add the following code to the .vscode\launch.json file to enable Office Debugging in your project. You will need to update line #7, and replace the uppercase HOST text with the host application for your Office add-in.

{ 
   "type": "office-addin", 
   "request": "attach", 
   "name": "Attach to Office Add-ins", 
   "port": 9222, 
   "trace": "verbose", 
   "url": "https://localhost:3000/taskpane.html?_host_Info=HOST$Win32$16.01$en-US$$$$0", "webRoot": "${workspaceFolder}", 
   "timeout": 45000 
}

NOTE: If you create a new Office project with Yeoman, you will not need to add this line, it will be part of the default template going forward.

Press CTRL+SHIFT+D to then open the Debug pane, select Attach to Office Add-in option from the drop down list at the top of the pane, and press F5 to start debugging.
You can now set breakpoints, see variable values, etc.

Script Lab for Outlook. Yeah!

June 16, 2020 David E. CraigLeave a comment

OMG! This is a day I have been waiting for.

I do a LOT of Outlook Web Add-in development. A lot. I have made the move from Visual Studio to Visual Studio Code, from C# to JavaScript and have not looked back. However, there are a few things that make development in this new area difficult and that is rapid prototyping.

For C#, I could always go into VBA and see how the object model would behave when I needed to test a hypothesis. I was able to use VBA as a laboratory for ideas before I codified them into solid C# code in a VSTO Add-in. But there was no such laboratory in the JavaScript web add-in world, until now…

…Script Lab for Outlook has been released. And the best part, it is available in Outlook on Windows, Outlook on Mac and Outlook on the web!

If you do a lot of Outlook development this will be a godsend. You will now be able to go into Script Lab and test your code ideas before you add them to your more complex add-in.

Open Outlook, go into the Office Store and type “Script Lab” and Script Lab for Outlook should come up in your list. Select and install it. Then open a message in Outlook and you should see the Script Lab items on the Home tab.

Happy coding!

Communication between Office Web Add-ins

June 15, 2020 David E. Craig3 Comments

Sometimes you have multiple add-ins and you need to facilitate communication between them. For example, a common scenario I have heard is that you have:

A Content Add-in that displays something like a graph or an organization chart.
A Taskpane app that allows you to manipulate settings, upload and download data from a backend web service.

You need to be able to facilitate communication between the two so that when updates happen to one add-in, the other receives those updates. I recently worked on a proof of concept that helped prove how this can be done.

The solution is to use the Document as a communication medium. In the particular case we used CustomXMLParts in the document. Here is how it would work:

One add-in would need to send an update to the other, so it would write a CustomXMLPart with a specific namespace and a “context” (basically, I am the TaskPane communicating) to the document.
Both add-ins will have a window.setInterval() thread running to check the documents for CustomXMLParts in that given namespace.
The timer on the Content Add-in would fire, find the new customXMLPart from the taskpane, read the contents and then update itself as needed and finally, delete the CustomXMLPart.

Here is the code for the Content Add-in to look for the message from the TaskPane:

	Office.initialize = function(reason) {
	// background thread checker
	window.setInterval(() => { checkForPart(); }, 1000);
	}

	const ns = "http://pfe.microsoft.com/excelpoc/1.0";
	const xml = "<message xmlns='http://pfe.microsoft.com/excelpoc/1.0'>" +
	"<sentby>[who]</sentby>" +
	"<info>[data]</info>" +
	"</message>";
	const from_tp = "TASKPANE ADD-IN";
	function checkForPart() {
	Excel.run(function(context) {
	/*@type {Excel.CustomXmlPartScopedCollection} /
	var customXmlParts = context.workbook.customXmlParts.getByNamespace(ns);
	customXmlParts.load();
	return context.sync().then(function () {
	if(customXmlParts.items.length > 0) {
	/*@type {OfficeExtension.ClientResult<string>} /
	var xmlData = customXmlParts.items[0].getXml();
	context.sync().then(function() {
	/*@type {DOMParser} /
	var parser = new window.DOMParser();
	/*@type {Document} /
	var xmlDoc = parser.parseFromString(xmlData.value, "text/xml");
	/*@type {Element} /
	var who = xmlDoc.getElementsByTagName("sentby")[0];
	/*@type {Element} /
	var data = xmlDoc.getElementsByTagName("info")[0];
	document.getElementById("message").innerText = who.innerHTML;
	if(who.innerHTML == from_tp) {
	// write tot he pane
	var dt = new Date();
	var currentTime = pad(dt.getHours(),2) + ":" + pad(dt.getMinutes(),2) + ":" + pad(dt.getSeconds(),2);
	// update a DIV on the page
	document.getElementById("message").innerHTML = "<p>Message sent on " +
	currentTime +
	" by " + who.innerHTML +
	" and the message is " + data.innerHTML;
	// now we delete the part
	customXmlParts.items[0].delete();
	return context.sync();
	}
	});
	}
	});
	});
	}

view raw ContentAddInReadCustomXmlPart.js hosted with ❤ by GitHub

Next, here is the code in the Task Pane Add-in that will send the message for the content add-in to read:

	const ns = "http://pfe.microsoft.com/excelpoc/1.0";
	const xml = "<message xmlns='http://pfe.microsoft.com/excelpoc/1.0'>" +
	"<sentby>[who]</sentby>" +
	"<info>[data]</info>" +
	"</message>";
	const from_tp = "TASKPANE ADD-IN";
	function sendMessage() {
	Excel.run(function(context) {
	var data = xml.replace("[who]", from_tp).replace("[data]", "This message is coming from the taskpane.");
	const customXmlPart = context.workbook.customXmlParts.add(data);
	customXmlPart.load();
	return context.sync().then();
	});
	}

view raw SendCustomXmlPartMessage.js hosted with ❤ by GitHub

Getting Started with OfficeJS

May 27, 2020May 23, 2020 David E. CraigLeave a comment

If you are just getting started with OfficeJS, then this post is for you. I will assume you have some understanding of what Office Web Add-ins are. However, there is one very basic point I will demonstrate in this tutorial:

An Office Web Add-In is simply a web site and an XML “description” file. I detailed this in this blog post. And we are going to build on that.

So, you are brand new to OfficeJS, and want to get started. The first thing you need to do is get your development environment up and running. There is a script for that:

Microsoft Office Development Environment Script
NOTE: For more information on this script, please read my blog post.

Next, you will need to pull down the Web Add-in Side Loader tool. Keep this ZIP on your desktop. This will be used later in the steps below to make it really easy for you to install the Add-in to Excel. However, if you prefer to do the steps manually, see the link below. For more information on this tool, please see my blog post and/or the GitHub repository.

Now that you have the development environment setup, lets build your very first, super basic Excel add-in:

Create a folder on your desktop called “MyFirstAddIn”
Open Notepad and copy/paste the code from HERE, then click File, Save, name it “manifest.xml”, change the type to “All Files *.*”, browse to folder on your desktop, and click Save.

NOTE: In this step you created the manifest file. This file will be used to “install” the add-in into Excel. Essentially, it will tell Excel where the web page is for the task pane.

Close Notepad, then open it again. Copy paste this code HERE, then click File, Save, name it “home.html”, change the type to “All Files *.*”, browse to the folder on your desktop, and click Save.

NOTE: In this step you created the primary file for website. This one file contains both the HTML and JavaScript needed to make the taskpane load in Excel.

Now you need to side load the manifest and you do that by first opening the ZIP file on your desktop: Set-WebAddin (v1.0.0.0).zip and extracting the Set-WebAddin.exe to the “MyFirstAddIn” folder.
Press Window+R to open the run dialog, and type CMD and press enter.

NOTE: This will open the Windows Command Prompt which you will use to sideload the add-in and run it.
NOTE: The word “sideload” is a fancy way to say install it for only your instance of Excel. It is also known as Developer Sideloading.

Change the directory to the folder on your desktop with this command:

cd "%userprofile%\desktop\MyFirstAddIn"

Next, type this command:

Set-WebAddin -test -manifestPath "%userprofile%\desktop\myfirstaddin\manifest.xml"

NOTE: In this step you have sideloaded the add-in to Office. This essentially tells Office you have an added an Excel add-in via the information in the manifest file which, when loaded tells Excel everything it needs to know about it, including where to find it. If you prefer to do the sideloading steps manually, you can follow them here.

Now you are almost ready. Type this last command (that is a dot/period at the end, very important):

http-server .

NOTE: The above steps start a local the http-server on your computer so that it will serve the webpage in the browser from the folder (.) you are current inside. You can now test this by clicking this link.

You are now ready to go. Simply open Excel and a new Blank Workbook. Then on the Insert tab, click the down arrow next to My add-ins and click BasicAddin. It should look like this:

The BasicAddIn in the Developer Add-ins menu

Your add-in Task Pane should load.
Click in cell A1, type “Hello World!”, and then in your Task Pane, click the “Click here” button and you should see “Hello World!” in the bottom of the page.
Once you are done, you can press CTRL+C in the command prompt window to shutdown the server and then to uninstall the add-in you can use this command:

Set-WebAddin -cleanup -manifestPath "%userprofile%\desktop\myfirstaddin\manifest.xml"

And that is it. There are three things to note here:

You created your first web add-in.
You did not use VSCode or any Integrated Development Environment. You did this only with Notepad.
But as an added bonus – you have also installed VSCode and the tools you need to start doing more complex things with Office Web Add-ins.

JavaScript, HTML, Web, CSS, front-end, back-end, web server, ports, local hosts… some, if not all of these are new terms if you are just getting into this new world of the Web and Web add-ins. But it does not have to be that complicated. As I referred to earlier, the following posts should be your next two stops on your journey:

Getting started as an OfficeJS Developer
Start Developing in OfficeJS Today with ScriptLab

If you have any questions, please reach out to me.

easyEws v1.0.15 Released

May 5, 2020May 5, 2020 David E. CraigLeave a comment

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>

view raw

easyewshtmlscriptline.html

hosted with ❤ by GitHub

And you can allow pull it down from NPM:

npm install easyEws

Microsoft Office Development Environment Setup Script

April 27, 2020April 27, 2020 David E. Craig1 Comment

If you are new to Office Web Add-in Development, then this post is for you. Even if you are not new and you need to setup a new development environment, this post is for you too.

Now, as far as manually setting up a new Office web add-in development environment, there are a few sources for helping you get started. There is the official guide here:

Set up your development environment

And I have also written one here:

How to-Configure VSCode for Office Development

NOTE: Mine is a tad more complicated, but essentially walks you through setting up for full fledged development, including source control with Git. That article was actually more for me when I wrote it.

BUT WAIT, THERE’S MORE…

However, after a co-worker and fellow Office Developer (Marty Andren) and I got to talking about this topic, I had an idea to create a script essentially automating the entire process. That was how the Microsoft Office Development Setup script, or MODES was born. The script is posted in the following repository:

https://github.com/davecra/modes

The MODES script is provided as-is for folks who need to setup an Office development environment. It is a simple run it and done. Once you have completed this script you will have:

The latest versions of Visual Studio Code
The latest version of NodeJS
The latest version of Node Package Manager (NPM)
The latest version of Yeoman (more info here)
And the Office Yeoman generator.

NOTE: This also installs http-server, a simple local web server that I hope to use in a forthcoming blog post that expands on a previous post demonstrating how easy it is to build a Web Add-ins from scratch.

NOTE: The script installs everything as local user, so there is no need for administrative permissions.

On the MODES GitHub post, you can follow the README directions to download and run the PowerShell script. If you are unfamiliar with PowerShell, you can just follow the steps and should walk you through what you need to do fairly quickly and easily.

If the above script cannot be run on your system (as a script), you can try to perform the steps manually by Copy/Pasting the following GIST into a PowerShell window and pressing enter:

	Add-Type –assembly "system.io.compression.filesystem";$vscode_url = "https://aka.ms/win32-x64-user-stable";$vscode_output = $env:USERPROFILE + "\downloads\vscode.exe";$node_url = "https://nodejs.org/dist/latest/win-x64/node.exe";$node_output = $env:USERPROFILE + "\downloads\node.exe";$node_install_path = $env:USERPROFILE + "\node";$npm_url = "https://nodejs.org/dist/npm/npm-1.4.9.zip";$npm_output = $env:USERPROFILE + "\downloads\npm.zip"
	Invoke-WebRequest –Uri $vscode_url –OutFile $vscode_output
	Invoke-WebRequest –Uri $node_url –OutFile $node_output
	Invoke-WebRequest –Uri $npm_url –OutFile $npm_output
	Start-Process –FilePath $vscode_output –ArgumentList ('/VERYSILENT', '/MERGETASKS=!runcode') –Wait
	md $node_install_path
	copy $node_output $node_install_path
	[io.compression.zipfile]::ExtractToDirectory($npm_output, $node_install_path)
	[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::User) + ";" + $node_install_path, [EnvironmentVariableTarget]::User)
	$env:Path += ";" + $node_install_path
	cd $node_install_path
	Start-Process –FilePath npm –ArgumentList ('install', '-g', 'npm') –WindowStyle Hidden –Wait
	Start-Process –FilePath npm –ArgumentList('install', '-g', 'yo', 'generator-office') –WindowStyle Hidden –Wait
	Start-Process –FilePath npm –ArgumentList('install', '-g', 'http-server') –WindowStyle Hidden –Wait
	$yo_file = $node_install_path + "\yo.ps1"
	ren $yo_file "yo.ps1.old"

view raw

modes_gist.ps1

hosted with ❤ by GitHub

This GIST is a “minified” version of the script on GitHib (no comments, no output and some lines are combined). So if you run this GIST, you will need to do give it time to complete as there is no feedback.

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"]
	];
	}