Category: Office Development

IMPORTANT: DOCS.COM is going to be retired in December 2017.

https://support.office.com/en-us/article/Important-information-about-Docs-com-end-of-service-3b0d4877-1643-457c-9756-8caf28b94da4?ui=en-US&rs=en-US&ad=US

I am not using GIST from GitHub and updating my blogs postes previously posted with Docs.com. See this post.

Recently a new feature was added to a relatively new product Microsoft Docs.doc.  Source Code upload with context highlighting. And I can embed it here in WordPress too. So, I am including my last post on easyEWS.js:

[code lang=”javascript” collapse=”true” title=”click to expand if the docs.com embedding below is not visible.”]
/*!
* easyEWS JavaScript Library v1.0.1
* http://davecra.com
*
* Copyright David E. Craig and other contributors
* Released under the MIT license
* https://tldrlegal.com/license/mit-license
*
* Date: 2016-04-18T19:14EST
*/

var easyEws = (function () {
"use strict";

var easyEws = {};

easyEws.initialize = function () {

// PRIVATE: creates a SOAP EWS wrapper
function getSoapHeader(request) {
var result =
‘<?xml version="1.0" encoding="utf-8"?>’ +
‘<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&#8217; +
‘ xmlns:xsd="http://www.w3.org/2001/XMLSchema"&#8217; +
‘ xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"&#8217; +
‘ xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"&#8217; +
‘ xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">&#8217; +
‘ <soap:Header>’ +
‘ <RequestServerVersion Version="Exchange2013" xmlns="http://schemas.microsoft.com/exchange/services/2006/types&quot; soap:mustUnderstand="0" />’ +
‘ </soap:Header>’ +
‘ <soap:Body>’ + request + ‘</soap:Body>’ +
‘</soap:Envelope>’;
return result;
};

// PRIVATE: makes an EWS callback with promise
function asyncEws(soap, successCallback, errorCallback) {
Office.context.mailbox.makeEwsRequestAsync(soap, function (ewsResult) {
if (ewsResult.status == "succeeded") {
var xmlDoc = $.parseXML(ewsResult.value);
successCallback(xmlDoc);
} else {
if (errorCallback != null)
errorCallback(ewsResult);
}
});
};

// PUBLIC: updates the x-headers in the mail item
// RETUNS: ‘succeeded’ if call completed successfully
// SEE: https://msdn.microsoft.com/en-us/library/office/dn596091(v=exchg.150).aspx
easyEws.updateEwsHeader = function (mailItemId, headerName, headerValue, successCallback, errorCallback) {
var soap =
‘<m:UpdateItem MessageDisposition="SaveOnly" ConflictResolution="AlwaysOverwrite">’ +
‘ <m:ItemChanges>’ +
‘ <t:ItemChange>’ +
‘ <t:ItemId Id="’ + mailItemId + ‘"/>’ +
‘ <t:Updates>’ +
‘ <t:SetItemField>’ +
‘ <t:ExtendedFieldURI DistinguishedPropertySetId="InternetHeaders"’ +
‘ PropertyName="’ + headerName + ‘"’ +
‘ PropertyType="String" />’ +
‘ <t:Message>’ +
‘ <t:ExtendedProperty>’ +
‘ <t:ExtendedFieldURI DistinguishedPropertySetId="InternetHeaders"’ +
‘ PropertyName="’ + headerName + ‘"’ +
‘ PropertyType="String" />’ +
‘ <t:Value>’ + headerValue + ‘</t:Value>’ +
‘ </t:ExtendedProperty>’ +
‘ </t:Message>’ +
‘ </t:SetItemField>’ +
‘ </t:Updates>’ +
‘ </t:ItemChange>’ +
‘ </m:ItemChanges>’ +
‘</m:UpdateItem>’;

soap = getSoapHeader(soap);
// make the EWS call
asyncEws(soap, function (xmlDoc) {
successCallback("succeeded");
}, function (errorDetails) {
if (errorCallback != null)
errorCallback(errorDetails);
});
};

// PUBLIC: returns a list of items in the folder
// RETURNS: an array of ItemIds
easyEws.getFolderItemIds = function (folderId, successCallback, errorCallback) {
var soap =
‘<m:FindItem Traversal="Shallow">’ +
‘ <m:ItemShape> ‘ +
‘ <t:BaseShape>IdOnly</t:BaseShape>’ +
‘ </m:ItemShape>’ +
‘ <m:ParentFolderIds>’ +
‘ <t:FolderId Id="’ + folderId + ‘"/>’ +
‘ </m:ParentFolderIds>’ +
‘</m:FindItem>’;

var returnArray = [];
soap = getSoapHeader(soap);

// call ews
asyncEws(soap, function (xmlDoc) {
$.each(xmlDoc.getElementsByTagName("t:ItemId"), function (index, value) {
returnArray.push(value.getAttribute("Id"));
});
successCallback(returnArray);
}, function (errorDetails) {
if (errorCallback != null) {
errorCallback(errorDetails);
}
});
}

// PUBLIC: gets the details for a specific item by ID
// RETURNS: a Dictionary of key/value pairs for the mail item
easyEws.getMailItem = function(ItemId, successCallback, errorCallback) {
var soap =
‘<m:GetItem>’ +
‘ <m:ItemShape>’ +
‘ <t:BaseShape>Default</t:BaseShape>’ +
‘ <t:IncludeMimeContent>true</t:IncludeMimeContent>’ +
‘ </m:ItemShape>’ +
‘ <m:ItemIds>’ +
‘ <t:ItemId Id="’ + ItemId + ‘" />’ +
‘ </m:ItemIds>’ +
‘</m:GetItem>’;
soap = getSoapHeader(soap);
// make call to EWS
asyncEws(soap, function (xmlDoc) {
var item = new MailItem(xmlDoc);
successCallback(item);
}, function (errorDetails) {
if(errorCallback != null) {
errorCallback(errorDetails);
}
});
}

// PUBLIC: expand a group and returns all the members
// NOTE: does not enumerate groups in groups
// RETURNS: An array of Email Addresses
easyEws.expandGroup = function (group, successCallback, errorCallback) {
var soap =
‘<m:ExpandDL>’ +
‘ <m:Mailbox>’ +
‘ <t:EmailAddress>" + group + "</t:EmailAddress>’ +
‘ </m:Mailbox>’ +
‘</m:ExpandDL>’;
soap = getSoapHeader(soap);
// make the EWS call
var returnArray = [];
asyncEws(soap, function (xmlDoc) {
var extendedProps = xmlDoc.getElementsByTagName("EmailAddress");
$.each(extendedProps, function (index, value) {
returnArray.push(value);
});
successCallback(returnArray);
}, function (errorDetails) {
if (errorCallback != null)
errorCallback(errorDetails);
});
};

// PUBLIC: Find a given conversation by the ID
// RETURNS: An array of ItemID
easyEws.findConversationItems = function (conversationId, successCallback, errorCallback) {
// NOTE: search for parent:
// http://stackoverflow.com/questions/19008696/exchange-find-items-in-ews-conversation-using-xml-request
// http://www.outlookcode.com/codedetail.aspx?id=1714
// https://msdn.microsoft.com/en-us/library/office/dn610351(v=exchg.150).aspx
var soap =
‘ <m:GetConversationItems>’ +
‘ <m:ItemShape>’ +
‘ <t:BaseShape>IdOnly</t:BaseShape>’ +
‘ <t:AdditionalProperties>’ +
‘ <t:FieldURI FieldURI="item:Subject" />’ +
‘ <t:FieldURI FieldURI="item:DateTimeReceived" />’ +
‘ </t:AdditionalProperties>’ +
‘ </m:ItemShape>’ +
‘ <m:FoldersToIgnore>’ +
‘ <t:DistinguishedFolderId Id="deleteditems" />’ +
‘ <t:DistinguishedFolderId Id="drafts" />’ +
‘ </m:FoldersToIgnore>’ +
‘ <m:SortOrder>TreeOrderDescending</m:SortOrder>’ +
‘ <m:Conversations>’ +
‘ <t:Conversation>’ +
‘ <t:ConversationId Id="’ + conversationId + ‘" />’ +
‘ </t:Conversation>’ +
‘ </m:Conversations>’ +
‘ </m:GetConversationItems>’;
soap = getSoapHeader(soap);
// Make EWS call
asyncEws(soap, function (xmlDoc) {
var returnArray = [];
$.each(xmlDoc.getElementsByTagName("t:ItemId"), function (index, value) {
returnArray.push(value.getAttribute("Id"));
});
successCallback(returnArray);
}, function (errorDetails) {
if (errorCallback != null)
errorCallback(errorDetails);
});
};

// PUBLIC Gets Internet headers for a spific item
// RETURNS: a Dictionary of key value pairs
// SEE: https://msdn.microsoft.com/en-us/library/office/aa566013(v=exchg.150).aspx
easyEws.getEwsHeaders = function (itemId, successCallback, errorCallback) {
var soap =
‘ <m:GetItem>’ +
‘ <m:ItemShape>’ +
‘ <t:BaseShape>AllProperties</t:BaseShape>’ +
‘ <t:IncludeMimeContent>true</t:IncludeMimeContent>’ +
‘ </m:ItemShape>’ +
‘ <m:ItemIds>’ +
‘ <t:ItemId Id="’ + itemId + ‘" />’ +
‘ </m:ItemIds>’ +
‘ </m:GetItem>’;

soap = getSoapHeader(soap);
// Make the EWS call
var returnArray = new Dictionary();
asyncEws(soap, function (xmlDoc) {
for (var item in xmlDoc.getElementsByTagName("t:InternetMessageHeader")) {
returnArray.add(item.getAttribute("HeaderName"), item.textContent);
}
successCallback(returnArray);
}, function (errorDetails) {
if (errorCallback != null)
errorCallback(errorDetails);
});
};

// PUBLIC: updates a folder property
// RETURNS: ‘succeeded’ is process completed successfully
easyEws.updateFolderProperty = function (folderId, propName, propValue, successCallback, errorCallback) {
var soap =
‘ <m:UpdateFolder>’ +
‘ <m:FolderChanges>’ +
‘ <t:FolderChange>’ +
‘ <t:FolderId Id="’ + folderId + ‘" />’ +
‘ <t:Updates>’ +
‘ <t:SetFolderField>’ +
‘ <t:ExtendedFieldURI ‘ +
‘ DistinguishedPropertySetId="PublicStrings" ‘ +
‘ PropertyName="’ + propName + ‘" ‘ +
‘ PropertyType="String" />’ +
‘ <t:Folder>’ +
‘ <t:ExtendedProperty>’ +
‘ <t:ExtendedFieldURI ‘ +
‘ DistinguishedPropertySetId="PublicStrings" ‘ +
‘ PropertyName="’ + propName + ‘" ‘ +
‘ PropertyType="String" />’ +
‘ <t:Value>’ + propValue + ‘</t:Value>’ +
‘ </t:ExtendedProperty>’ +
‘ </t:Folder>’ +
‘ </t:SetFolderField>’ +
‘ </t:Updates>’ +
‘ </t:FolderChange>’ +
‘ </m:FolderChanges>’ +
‘ </m:UpdateFolder>’;

soap = getSoapHeader(soap);
// make the EWS call
asyncEws(soap, successCallback, errorCallback);
}

// PUBLIC: gets a folder property
// RETURNS: property value if process completed successfully
easyEws.getFolderProperty = function (folderId, propName, successCallback, errorCallback) {

var soap =
‘<m:GetFolder>’ +
‘<m:FolderShape>’ +
‘<t:BaseShape>IdOnly</t:BaseShape>’ +
‘<t:AdditionalProperties>’ +
‘<t:ExtendedFieldURI ‘ +
‘ DistinguishedPropertySetId="PublicStrings" ‘ +
‘ PropertyName="’ + propName + ‘" ‘ +
‘ PropertyType="String" />’ +
‘</t:AdditionalProperties>’ +
‘</m:FolderShape>’ +
‘<m:FolderIds>’ +
‘<t:FolderId Id="’ + folderId + ‘"/>’ +
‘</m:FolderIds>’ +
‘</m:GetFolder>’;
soap = getSoapHeader(soap);
// make the EWS call
asyncEws(soap, function(xmlDoc) {
successCallback(xmlDoc.getElementsByTagName("t:Value")[0].textContent);
}, errorCallback);
}

// PUBLIC: Gets the folder id by the given name from the store
// RETURNS: a string with ID of the folder
easyEws.getFolderId = function (folderName, successCallback, errorCallback) {
var soap =
‘ <m:GetFolder>’ +
‘ <m:FolderShape>’ +
‘ <t:BaseShape>IdOnly</t:BaseShape>’ +
‘ </m:FolderShape>’ +
‘ <m:FolderIds>’ +
‘ <t:DistinguishedFolderId Id="’ + folderName + ‘" />’ +
‘ </m:FolderIds>’ +
‘ </m:GetFolder>’;
soap = getSoapHeader(soap);
// make EWS callback
asyncEws(soap, function (xmlDoc) {
var id = xmlDoc.getElementsByTagName("t:FolderId")[0].getAttribute("Id");
successCallback(id);
}, function (errorDetails) {
if (errorCallback != null)
errorCallback(errorDetails);
});
}
}

return easyEws;

})();

/* HELPER FUNCTIONS AND CLASSES */
function MailItem(value) {

this.value = value || {};

MailItem.prototype.MimeContent = function () {
return this.value.getElementsByTagName("t:MimeContent")[0].textContent;
};

MailItem.prototype.MimeContent.CharacterSet = function () {
return this.value.getElementsByTagName("t:MimeContent")[0].getAttribute("CharacterSet");
};

MailItem.prototype.Subject = function () {
return this.value.getElementsByTagName("t:Subject")[0].textContent;
};
}

function Dictionary(values) {
this.values = values || {};

var forEachIn = function (object, action) {
for (var property in object) {
if (Object.prototype.hasOwnProperty.call(object, property))
action(property, object[property]);
}
};

Dictionary.prototype.containsKey = function (key) {
return Object.prototype.hasOwnProperty.call(this.values, key) &&
Object.prototype.propertyIsEnumerable.call(this.values, key);
};

Dictionary.prototype.forEach = function (action) {
forEachIn(this.values, action);
};

Dictionary.prototype.lookup = function (key) {
return this.values[key];
};

Dictionary.prototype.add = function (key, value) {
this.values[key] = value;
};

Dictionary.prototype.length = function () {
var len = 0;
forEachIn(this.values, function () { len++ });
return len;
};
};
[/code]

https://docs.com/david-craig/5089/easyews

Please let me know what you think.

UPDATE: By the way, if you want to embed DOCS.COM links in your blog posts on WordPress, DO NOT use the Embed option on your listing. Instead just copy the raw link and past it into your page. WordPress with automagically convert it for you.

UPDATE (3/1/2021): This solution probably does not work with the updated Office templates that do not have an “app” object defined. You would need to add code like this:

[code language="javascript"]
var app = {};
[/code]

A better option is to use the “updateEwsHeader()” function from my easyEws library.

Transport headers are a very useful tool to help pass application settings from one user mailbox to another. It is also useful in some rules on transport and edge servers to determine how to treat a specific message. While manipulating these headers is easier in Outlook (full client) doing this from a Mail App is a little less clear.

The following code is how I managed to get this to work. First, you have to SAVE the mail item so that you can get a EWS ID. Once you get the ID, we then build the soap message (I declared this in the ‘app’ namespace). Once we have the SOAP message we then make the EWS call.

NOTE: I am using the window.alert() which you can find how to use here.

[code language="javascript"]
    function setXHeader() {

        // first save the item
        Office.cast.item.toItemCompose(Office.context.mailbox.item).saveAsync(function (composeId)
        {
            var id = composeId.value;

            // update the x-headers
            var xml = app.updateXHeaderSoap(id, "X-Test", "ValueHere");
            Office.context.mailbox.makeEwsRequestAsync(xml, function (ewsResult) {
                if (ewsResult.status != "succeeded") {
                    window.alert("Unable to attach x-headers.\n" + ewsResult.error.message);
                }
            });
        });
    }

        // updates the x-headers in the mail item
        // SEE: https://msdn.microsoft.com/en-us/library/office/dn596091(v=exchg.150).aspx
        app.updateXHeaderSoap = function (id, property, value) {
            var soap =
                '<UpdateItem MessageDisposition="SaveOnly" ConflictResolution="AlwaysOverwrite"' +
                '            xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
                '   <ItemChanges>' +
                '       <t:ItemChange>' +
                '           <t:ItemId Id="' + id + '"/>' +
                '           <t:Updates>' +
                '               <t:SetItemField>' +
                '                   <t:ExtendedFieldURI DistinguishedPropertySetId="InternetHeaders"' +
                '                                       PropertyName="' + property + '"' +
                '                                       PropertyType="String" />' +
                '                   <t:Message>' +
                '                       <t:ExtendedProperty>' +
                '                           <t:ExtendedFieldURI DistinguishedPropertySetId="InternetHeaders"' +
                '                                               PropertyName="' + property + '"' +
                '                                               PropertyType="String" />' +
                '                           <t:Value>' + value + '</t:Value>' +
                '                       </t:ExtendedProperty>' +
                '                   </t:Message>' +
                '               </t:SetItemField>' +
                '           </t:Updates>' +
                '       </t:ItemChange>' +
                '   </ItemChanges>' +
                '</UpdateItem>';

            return app.getSoapHeader(soap);
        };

 app.getSoapHeader = function(request) {
         var result =
             '<?xml version="1.0" encoding="utf-8"?>' +
             '<soap:Envelope xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance' +
             '               xmlns:xsd=http://www.w3.org/2001/XMLSchema' +
             '               xmlns:m=http://schemas.microsoft.com/exchange/services/2006/messages' +
             '               xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/' +
             '               xmlns:t=http://schemas.microsoft.com/exchange/services/2006/types>' +
             '   <soap:Header>' +
             '       <RequestServerVersion Version="Exchange2013" xmlns=http://schemas.microsoft.com/exchange/services/2006/types soap:mustUnderstand="0" />' +
             '   </soap:Header>' +
             '   <soap:Body>' + request + '</soap:Body>' +
             '</soap:Envelope>';
         return result;
     };
[/code]

I have been getting more and more requests to integrate Visual Studio Tools for Office solutions with SharePoint. As such I find myself connecting to SharePoint Lists and grabbing files and uploading files, etc. The following set of functions are a small subset (but most the most generic), that I can provide for now. The primary function here is CopyToSharePoint. This function does exactly what it sounds like. You provide the URL to the site, the List name you want to copy to, the local path and filename of the file you want to upload.

This does NOT work with Office 365 SharePoint lists. Those require a special project you can download from MSDN to get you the proper SharePoint context for the Microsoft Cloud. The following example only works with on-premises SharePoint installs.

NOTE: I will be working on cleaning up all my SharePoint integration code so it is generic (detached from its specific solutions), and attach it here as a full solution.

[sourcecode language=”csharp”]
/// <summary>
/// Copies the given file to the SharePoint site
/// </summary>
/// <param name="PstrSite">The URL to the site: http://sharepoint/site </param>
/// <param name="PstrList">The name of the list: Documents </param>
/// <param name="PstrLocalPath">The local path of the file to be copied: c:\test\test.docx</param>
/// <param name="PstrLocalName">The local name of the file: text.docx</param>
public static void CopyToSharePoint(string PstrSite, string PstrList, string PstrLocalPath, string PstrLocalName)
{
try
{
SPContext LobjContext = GetSharePointContext();
SPList LobjList = GetSharePointList(PstrSite, PstrList);
SPFolder LobjFolder = LobjList.RootFolder;
LobjContext.Load(LobjFolder);
LobjContext.ExecuteQuery();
string LstrRelativeUrl = LobjFolder.ServerRelativeUrl + "/" + PstrLocalName;
// copy the temp file
using (var LobjFs = new FileInfo(PstrLocalPath).OpenRead())
{
SP.File.SaveBinaryDirect(Common.GobjClientContext, LstrRelativeUrl, LobjFs, true);
}
}
catch (Exception PobjEx)
{
MessageBox.Show(PobjEx.ToString());
}
}

/// <summary>
/// Get the SharePoint context
/// </summary>
/// <returns></returns>
public static SP.Context GetSharePointContext(string PstrSite)
{
// get the current context
SPClientContext LobjContext = new SPClientContext(PstrSite);
// do we have a cached credential?
if (MobjCredential == null)
{
// no – ask the user to sign in or use current
CredentialsForm LobjCreds = new CredentialsForm();
if (LobjCreds.ShowDialog() == DialogResult.OK)
{
if (LobjCreds.UseCurrent)
{
MobjCredential = CredentialCache.DefaultNetworkCredentials;
}
else
{
MobjCredential = new NetworkCredential(LobjCreds.UserName,
LobjCreds.Password,
LobjCreds.Domain);
}
}
else
{
PbolUserCancel = true;
return null; // cancel
}
}
LobjContext.Credentials = MobjCredential;
return LobjContext;
}

/// <summary>
/// Access the list
/// </summary>
/// <returns></returns>
public static SP.List GetSharePointList(string PstrSite, string PstrTitle)
{
try
{
SPList LobjList = null;
SPContext LobjContext = GetSharePointContext(PstrSite);
if (LobjContext != null)
{
if (!string.IsNullOrEmpty(PstrTitle))
{
SPListCollection LobjLists = LobjContext.Web.Lists;
LobjContext.Load(LobjLists);
LobjContext.ExecuteQuery();

foreach (SPList LobjItem in LobjLists)
{
if (LobjItem.Title == PstrTitle)
{
LobjList = LobjItem;
break;
}
}

// done
return LobjList;
}
else
{
return null;
}
}
else
{
return null;
}
}
catch (Exception PobjEx)
{
MessageBox.Show(PobjEx.ToString());
return null;
}
}
[/sourcecode]

I ran into an interesting problem trying to add a field to a table cell range from C#. I would get an exception:

The command is not available.

This is because the range you get from a cell includes it’s cell marker and you cannot delete that. So, you have to reset the range by one character (see bolded line below). Like this:

private void insertTableWithField(Word.Range PobjRange)
{
Word.Table LobjTable = PobjRange.Tables.Add(PobjRange, 2, 1);
LobjTable.Cell(1, 1).Range.Text = “Table with Field”;
Word.Range LobjRange = LobjTable.Cell(2, 1).Range;
LobjRange.SetRange(LobjRange.Start, LobjRange.End – 1);
Word.Field LobjField = LobjRange.Fields.Add(LobjRange);
LobjField.Code.Text = “DOCPROPERTY Author \\* MERGEFORMAT”;
}