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:

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:

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:

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:

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.rawgit.com/davecra/easyEWS/e8ea1eaf/easyEws.js

Here is the latest version on GitHub:

https://github.com/davecra/easyEWS/blob/master/easyEws1.0.6.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:

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
}

 

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:

  <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>

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:

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);
}

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

  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: