easyEws Updated to 1.0.20

This was more than a patch this time. It was a minor update to two functions:

  • sendMailItem
  • sendPlainTextEmailWithAttachment

There was an issue reported (#12) where the sendMailItem function was not working in IE11. This was because it was created to take an inline object (ES6). Well on IE11 (which only supports ES5), it broke.

So, I fixed sendMailItem to support ES5 and also took the opportunity to add two often requested features of this function:

  • It will now allow you to submit HTML body content or Text. It will also parse the HTML for you if you submit it as is.
  • It will also now allow you to send both file attachment (new), and mail item attachments (original).

Please see the documentation for more information on the updates to this function: https://github.com/davecra/easyEWS#sendMailItem

Also I updated the sendPlainTextEmailWithAttachment function. Under the covers this uses the sendMailItem function. So I had to update it to use the new format so it would work as well. There was no change to it’s features/functionality however.

I did not get to the last item I have had requests for:

  • ability to specify recipients as To/CC/BCC. I will update this at some future date. Also, please let me know if you would like to see this.

Overall, the goal is to have the sendMailItem() function be a full multi-purpose function at some point. It is almost there, but please keep the suggestions coming.

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

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*

 

EWS: ExpandDL documentation is wrong

I am not certain how prevalent this issue is in the wild and/or if anyone else has encountered it or had to workaround it, but there is a documentation bug that had me pulling my hair our for nearly a week.

If you have a need to get the members of an Exchange public distribution group using Exchange Web Services (EWS) ExpandDL operation via SOAP, and you followed this documentation, you will have encountered this super unhelpful error:


<?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:Body>
<s:Fault>
<faultcode xmlns:a="http://schemas.microsoft.com/exchange/services/2006/types">a:ErrorInternalServerError</faultcode>
<faultstring xml:lang="en-US">An internal server error occurred. The operation failed.</faultstring>
<detail>
<e:ResponseCode xmlns:e="http://schemas.microsoft.com/exchange/services/2006/errors">ErrorInternalServerError</e:ResponseCode>
<e:Message xmlns:e="http://schemas.microsoft.com/exchange/services/2006/errors">An internal server error occurred. The operation failed.</e:Message>
</detail>
</s:Fault>
</s:Body>
</s:Envelope>

The problem is that the documentation is wrong. The namespaces used and the namespace prefixes are wrong. Here is what is on the documentation site:


<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<soap:Body>
<ExpandDL xmlns="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<t:Mailbox>
<t:EmailAddress>test@davidcr.local</t:EmailAddress>
</t:Mailbox>
</ExpandDL>
</soap:Body>
</soap:Envelope>

view raw

wrongsoap.xml

hosted with ❤ by GitHub

What I ended up doing was to use the EwsEditor tool and Fiddler (per the guidance of an awesome Exchange guru I work with – thanks Dan!), and I captured the proper soap coming from the Managed API. To get ExpandDL to work properly, you need this SOAP:


<?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="Exchange2013_SP1" />
</soap:Header>
<soap:Body>
<m:ExpandDL>
<m:Mailbox>
<t:EmailAddress>test</t:EmailAddress>
</m:Mailbox>
</m:ExpandDL>
</soap:Body>
</soap:Envelope>

view raw

rightsoap.xml

hosted with ❤ by GitHub

Anyway, I will be issuing an update to easyEws very soon to include the correct SOAP.

Outlook Email Reporting Sample

I just posted a new Outlook sample on GitHub. I have created something very similar to this sample for a couple of customers now and have been using this as a template. What this sample does is place a button on the Ribbon for users to report suspicious email to the administrator. The user will get the option to select why they think it is suspicious as well as provide a comment. When they click Send, it will email the administrator. The email address which receives this notification is configured in the URL for the add-in page via the manifest XML.

Anyway, I wanted to share this basic sample with the community so others can use this to quickly implement similar solutions in their environment.

All the details for configuring the add-in are in the README.md. Here is the link the new sample: https://github.com/davecra/Outlook.ReportAddin. I also created this in VS Code.

Please let me know if you have any questions or suggestions for other samples you would like to see.

EasyEWS: JavaScript Library Improved

I have been working on improving my various Outlook proof-of-concepts and nearly every one of them require using EWS to access data about items in Exchange, which are not exposed through the object model. As such I have been constantly improving easyEWS.js. I have just posted version 1.0.6 and also have provided a published CDN which you can now use to always get the latest version of the library. Here is the CDN:

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

Here is the latest version on GitHub:

https://github.com/davecra/easyEWS/blob/master/easyEws.js

Specifically, the improvements I have made are:

  1. Typed every var using JSDoc. See my post on that here. This should help with debugging any issues you have. And if you have issues with my library, please contact me.
  2. Updated the Error handling callbacks and the Debugging callback to include more information. Every function can be called with this pattern, and you will get more information now if something does wrong. Here is the essential pattern every function uses:

[code lang=”javascript” collapse=”false”]

easyEws.fn([x, [y],] function(z) {
// this is the success
}, function(error) {
// this is the failure – error
}, function(debug) {
// this is the debug information which contains:
// the soap message sent to the server
// the soap response from the server
// the server status message
// the server error message if any
}

[/code]

The Most Anticipated OfficeJS Feature is Here

If you are an Outlook Web Access developer trying to create an add-in to help mitigate the accidental release of Personally Identifiable Information (PII), you have probably been looking for a way to stop the send of the message if it does not pass a test. The functionality has not been a part of the new OfficeJS object model, until now. However, there are several things you need to know in order to set this up. Here are the general steps:

  • Use PowerShell to create a policy to enable to the OWAOnSendAddinAllUserPolicy
  • Use PowerShell to set that policy for a mailbox or group of mailboxes
  • Update your manifest file to enable the functionality and specify the event function you want to call when the user presses send
  • Write your JavaScript to properly handle the event.

NOTE: There are several caveats to this functionality. These are: you CANNOT publish an app using this functionality to the Store; this will not work on Shared mailboxes; and this will not work from any other clients, just Outlook Web Access (for now).

Create the OWAOnSendAddinAllUserPolicy

To set the policy for a user account, you need to create a policy with it enabled (or edit the default or specific policy you have applied). First, you need these steps to connect to the Exchange server as an administrator and establish a session:

Next, you need to then use PowerShell to set/configure the policy and then apply it to an account.

Once you have done, this you can then start writing the functionality into your code.

Update the Manifest file

The manifest will require a new and additional version overrides node. You will then use the FunctionFile to define an Extension point in your code. This will be a function you call. If you are not familiar with Function Files, here is a link to how to create one:

Here is what you manifest will need to look like:

[code lang=”xml” collapse=”true” title=”click to expand if the embedding below is not visible.”]
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides&quot; xsi:type="VersionOverridesV1_0">
<!– On Send requires VersionOverridesV1_1 –>
<!– https://dev.office.com/docs/add-ins/outlook/outlook-on-send-addins –>
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1&quot; xsi:type="VersionOverridesV1_1">
<Requirements>
<bt:Sets DefaultMinVersion="1.5">
<bt:Set Name="Mailbox" />
</bt:Sets>
</Requirements>
<Hosts>
<Host xsi:type="MailHost">
<DesktopFormFactor>
<!– Location of the Functions that UI-less buttons can trigger (ExecuteFunction Actions). –>
<FunctionFile resid="functionFile" />
<ExtensionPoint xsi:type="Events">
<Event Type="ItemSend" FunctionExecution="synchronous" FunctionName="onSendEvent" />
</ExtensionPoint>

</DesktopFormFactor>
</Host>
</Hosts>

</VersionOverrides>
</VersionOverrides>
[/code]

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
<!-- On Send requires VersionOverridesV1_1 -->
<!-- https://dev.office.com/docs/add-ins/outlook/outlook-on-send-addins -->
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
<Requirements>
<bt:Sets DefaultMinVersion="1.5">
<bt:Set Name="Mailbox" />
</bt:Sets>
</Requirements>
<Hosts>
<Host xsi:type="MailHost">
<DesktopFormFactor>
<!-- Location of the Functions that UI-less buttons can trigger (ExecuteFunction Actions). -->
<FunctionFile resid="functionFile" />
<ExtensionPoint xsi:type="Events">
<Event Type="ItemSend" FunctionExecution="synchronous" FunctionName="onSendEvent" />
</ExtensionPoint>
...
</DesktopFormFactor>
</Host>
</Hosts>
...
</VersionOverrides>
</VersionOverrides>
view raw OnSend.xml hosted with ❤ by GitHub

The important thing to note here is that your FunctionFile function for OnSend will need to be defined OUTSIDE the scope of the Office.initialize() function. It needs to be GLOBAL. So you simply place it in the root of your functionFile.js. However, you still need to define an Office.initialize() function in your FunctionFile and in there you probably will want to grab a reference to the mailbox, mailbox.item and the user maybe and place them in a global var as well. This way you will have access to those things in the Event method to be able to make call like body.getAsync() or subject.getAsync(), etc.

Here is how you define it:

[code lang=”javascript” collapse=”true” title=”click to expand if the embedding below is not visible.”]
var sendEvent;
function onSendEvent(event) {
///
<summary>
/// OUTLOOK SEND EVENT
/// Entry point for Message onSend event
/// Per example: https://github.com/OfficeDev/Outlook-Add-in-On-Send/tree/master/outlook-add-in-on-send
/// Setup mailbox policy first:
/// 1) Get sessions and commands: https://technet.microsoft.com/en-us/library/jj984289(v=exchg.160).aspx
/// 2) Set policy and more info: https://dev.office.com/docs/add-ins/outlook/outlook-on-send-addins
/// </summary>

/// <param name="event" type="object">ItemSend event is automatically passed by on send code to the function
// specified in the manifest.</param>
sendEvent = event;

// do your work here… since it will likely be ASYNC, you will want to
// set the event handler to a global. When you are done, you will issue
// > sendEvent.completed({ allowEvent: true }); // to send
// > sendEvent.completed({ allowEvent: false }); // to block
doSomething.Async(values, asyncComplete);
}
[/code]

var sendEvent;
function onSendEvent(event) {
/// <summary>
/// OUTLOOK SEND EVENT
/// Entry point for Message onSend event
/// Per example: https://github.com/OfficeDev/Outlook-Add-in-On-Send/tree/master/outlook-add-in-on-send
/// Setup mailbox policy first:
/// 1) Get sessions and commands: https://technet.microsoft.com/en-us/library/jj984289(v=exchg.160).aspx
/// 2) Set policy and more info: https://dev.office.com/docs/add-ins/outlook/outlook-on-send-addins
/// </summary>
/// <param name="event" type="object">ItemSend event is automatically passed by on send code to the function
// specified in the manifest.</param>
sendEvent = event;
// do your work here... since it will likely be ASYNC, you will want to
// set the event handler to a global. When you are done, you will issue
// > sendEvent.completed({ allowEvent: true }); // to send
// > sendEvent.completed({ allowEvent: false }); // to block
doSomething.Async(values, asyncComplete);
}
view raw OnSend.js hosted with ❤ by GitHub

Then later in your code, you can either Cancel the send or allow the send event to occur, like this:

[code lang=”javascript” collapse=”true” title=”click to expand if the embedding below is not visible.”]
function asyncCompelte() {
// procress the result
if(isOkToSend() == true) {
sendEvent.completed({ allowEvent: true }); // send it
} else {
sendEvent.completed({ allowEvent: false }); // block it
}
}
[/code]

function asyncCompelte() {
// procress the result
if(isOkToSend() == true) {
sendEvent.completed({ allowEvent: true }); // send it
} else {
sendEvent.completed({ allowEvent: false }); // block it
}
}

Once you have set the policy on the mailbox, modified your manifest and then added the event function to your FunctionFile, you are good to go. I will be working on a simple demo to place on GitHub in coming weeks and will post an update when complete.

UPDATE: Here it my post with the demo:
Outlook OnSend and Dialog Sample

But I wanted to get this information out here for now. In the meantime, you can use this demo as an example of how to implement this end-to-end:

Developing an On-premises Web Add-in

A customer I was working with wanted help developing a fully on-premises Outlook web add-in. By this, they wanted no part of it to reach out to the Internet (Azure or Office 365). They wanted:

  • To connect to their internal Exchange server
  • An internal IIS website
  • And no references to the Internet (including the Office.js).

This is the topology we are trying to achieve:

topology

If you have developed an Office Web Add-in lately, you find it is inherently biased to the Internet. Even the samples and solutions provided assume Office 365/Exchange and Azure websites. In a default, new Visual Studio solution, the links to the Office.js libraries and stylesheets are all pointing to the web. And, so as you might expect, there are some challenges to getting it to work on-premises only.

This posting covers what you must do to get such a solution to work, including getting past some pitfalls.

  1. First, you have to download the Office.js files locally. And especially for Outlook because the Office.js files that are provided by default in your solution folder (“for offline debugging” as part of VS2015U3 or earlier) are missing some features to work with specific builds of Outlook 2013 and Outlook 2016. You will run into some strange “type” missing and “Office not defined” errors if you forget this step.
  2. Once you have downloaded the Office.JS files, you will delete all the files under the Scripts\Office\1 folder and copy in the contents you downloaded in step 1.
  3. Next, find all your HTML pages where you have the following reference:[code language=”html”]
    <script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js&quot; type="text/javascript"></script>;
    [/code]
  4. Comment out that line and add the following two lines:
    [code language=”html”]
    <!– <script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js&quot; type="text/javascript></script> –>
    <script src="../../Scripts/Office/MicrosoftAjax.js" type="text/javascript"></script>;
    <script src="../../Scripts/Office/1.1/office.js" type="text/javascript"></script>;
    [/code]
  5. Once you have developed your solution, you must setup your IIS server. In general here is what you must do:
    • The IIS Server must have ASP.NET installed, it must have .NET4 installed and you must have the Web Application role enabled.
    • Open IIS Manager
    • Create a site, and figure the folder path
    • Convert the site to an Application
    • Apply an SSL certificate that is already trusted on all your client computers or that has a root certificate authority that is trusted on all your client computers. If you browse to your site using HTTPS and you get a RED warning about an untrusted site, then the certificate is not trusted or properly setup.
  6. Next, and this was a major issue to troubleshoot, your Exchange Web Services certificate cannot be expired. If it is, any EWS call you make will return “succeeded” but will be blank – missing data. Digging into the logs you might find an error: “ErrorInvalidClientAccessTokenRequest” The Microsoft Exchange Server Auth Certificate that is used for OAuth needs to be updated. To do this you have to be logged into the Exchange server as administrator:
    • Run this cmdlet to identify the thumbprint of the certificate being used for OAUTH:Get-AuthConfig | FT currentcertificate*
    • Run this cmdlet to identify the thumbprint of certificates used for other Exchange servers (IIS, SMTP, etc.):Get-ExchangeCertificate | Fl *thumb*
    • Run these cmdlets to configure Exchange to use the valid certificate (copy/paste the thumbprint from the Get-ExchangeCertificate output):$today = Get-Date
      Set-AuthConfig -NewCertificateThumbprint newthumbprint -NewCertificateEffectiveDate $today -Force
    • Run this cmdlet to make sure the changes are published to the environmentSet-AuthConfig -PublishCertificate
    • Run this cmdlet to verify the certificate thumbprintGet-AuthConfig | FT currentcertificate*,previouscert*
  7. Now you can deploy your solution to IIS, update your manifest to point to the IIS server (do not forget the HTTPS) and then install it on the Exchange Server Control Panel (ECP) under the Organization / Add-ins option as a mandatory add-in.
  8. Finally, and this last bit is important: IF USING OUTLOOK 2013 or OUTLOOK 2016, YOU MUST BE LOGGED INTO WINDOWS ON THE SAME DOMAIN AS YOUR EMAIL. I know, I know… for some folks this sucks. I have reported this to our product team and they are looking into it. If you are not logged into the same domain controller as your email address is registered, you will not see the advertised add-in. It will load in Outlook Web Access (OWA), but will not appear in Outlook 2013/2016. The exact cause of this problem is unknown, but hopefully it will be addressed in a future version of the product (Exchange or Outlook or both).

Setting up for 100% on-premises is difficult, but it CAN be done. There are a lot of steps, but if you follow the above prescription, you should get it to work. In time, I hope to see this process get easier. But in an online world where Microsoft Office 365 and Azure are main focus, “old fashioned” on-premises solutions are going to require a little more elbow grease.

NOTE: This entry was contributed to by Arthel Bibbens (MSFT) / Exchange PFE. You can follow his posts on this topic here:

 1-GetOrgConfig Administering Office Add-ins within Exchange 2013 and Exchange 2016

blogs.technet.microsoft.com

I recently worked with a developer to deploy an Office add-in within an Exchange 2013 on-premises environment. This project highlighted a capability of Exchange and Outlook that is a huge shift in the way mail add-ins are developed, deployed, and maintained. Let’s take a look at the key components of Exchange 2013 that support this…