Monday, April 09, 2012

EWS Managed API and Powershell How-To Series Part 7 Using the Configuration Information Operation

In the past couple of posts I've been looking at using the special operations in EWS that allow you to access the unconventional data in a mailbox such as OOF, FreeBusy etc. In this post I'm going to look at accessing the FAI (Folder Associated Items) userconfiguration Items. These are used to store a lot of the Meta-Information for various mailbox functions such as the Master Category list, Works hours, OWA Signature and various other configuration options. The best documentation for the options and formats that are used to store config information in FAI Items is the following Exchange Protocol Document http://msdn.microsoft.com/en-us/library/cc463899%28v=exchg.80%29.aspx.

Before looking at EWS you should consider whether using the Exchange Management Shell maybe a better option, most of the configuration Setting can now be set using EMS cmdlet's such as eg OWA Signature(Get-MailboxMessageConfiguration), WorkHours(Get-MailboxCalendarConfiguration).

With UserConfiguration information that is stored on a FAI item the Item will have a special ItemClass and the config data itself is stored in one or more Mapi properties in either a custom XML format,Roaming Dictionary format or Binary format. Lets look at a few examples of dealing with the different formats for different config Items

Master Category List

The first one I'll cover is the Master category list which I've shown an example of before but the Master Category list is held in a FAI item in the Mailboxes Calendar Folder with a ItemClass of IPM.Configuration.CategoryList and the data for the catergory list is held in a Mapi property in a Custom XML format that is documented in the Exchange Protocol Document i linked above.


To Access the Master Category list which is useful if you need to show the color associated with a particular Keyword.

  1. $folderid= new-object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Calendar,$MailboxName)     
  2. #Specify the Calendar folder where the FAI Item is  
  3. $UsrConfig = [Microsoft.Exchange.WebServices.Data.UserConfiguration]::Bind($service"CategoryList"$folderid, [Microsoft.Exchange.WebServices.Data.UserConfigurationProperties]::All)  
  4. #Get the XML in String Format  
  5. $CatXML = [System.Text.Encoding]::UTF8.GetString($UsrConfig.XmlData)  
  6. #Deal with the first character being a Byte Order Mark  
  7. $boMark = $CatXML.SubString(0,1)  
  8. #Parse the XML  
  9. [XML]$CatXML = $CatXML.SubString(1)  
  10. $NewCat = $CatXML.categories.category  
If you want to add a new Category the easiest way to do this is to clone a existing category from the existing XML change the properties then append it to the Categorylist. Here's an example

  1. $folderid= new-object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Calendar,$MailboxName)     
  2. #Specify the Calendar folder where the FAI Item is  
  3. $UsrConfig = [Microsoft.Exchange.WebServices.Data.UserConfiguration]::Bind($service"CategoryList"$folderid, [Microsoft.Exchange.WebServices.Data.UserConfigurationProperties]::All)  
  4. #Get the XML in String Format  
  5. $CatXML = [System.Text.Encoding]::UTF8.GetString($UsrConfig.XmlData)  
  6. #Deal with the first character being a Byte Order Mark  
  7. $boMark = $CatXML.SubString(0,1)  
  8. #Parse the XML  
  9. [XML]$CatXML = $CatXML.SubString(1)  
  10. #Clone exiting Entry  
  11. $NewCat = $CatXML.categories.category[0].Clone()  
  12. #Set properties  
  13. $NewCat.name = "My New Cat meow"  
  14. $NewCat.color = "10" #Steel Cat  
  15. $NewCat.keyboardShortcut = "0"  
  16. $NewCat.guid = "{" + [System.Guid]::NewGuid().ToString() + "}"  
  17. $NewCat.renameOnFirstUse = "0"  
  18. [Void]$CatXML.categories.AppendChild($NewCat)  
  19. $UsrConfig.XmlData = [System.Text.Encoding]::UTF8.GetBytes($boMark + $CatXML.OuterXml)  
  20. #Update Item  
  21. $UsrConfig.Update()  
OWA UserOptions

The most common form of data-format that is used for a configuration item is the Dictionary an example of this is the OWA.UserOptions FAI item that is held in the Root of the Mailbox. This contains the OWA configuration for the user including the OWA Signature. To show the settings that are currently held in the dictionary in this configuration Item we can use.

  1. $folderid= new-object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Root,$MailboxName)     
  2. #Specify the Root folder where the FAI Item is  
  3. $UsrConfig = [Microsoft.Exchange.WebServices.Data.UserConfiguration]::Bind($service"OWA.UserOptions"$folderid, [Microsoft.Exchange.WebServices.Data.UserConfigurationProperties]::All)  
  4. $UsrConfig.Dictionary  
If you wanted to set the OWA Signature for a user you would use something like this

  1. $folderid= new-object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Root,$MailboxName)     
  2. #Specify the Root folder where the FAI Item is  
  3. $UsrConfig = [Microsoft.Exchange.WebServices.Data.UserConfiguration]::Bind($service"OWA.UserOptions"$folderid, [Microsoft.Exchange.WebServices.Data.UserConfigurationProperties]::All)  
  4. $hsHtmlSigniture = "Im away use <a href='www.bing.com'>www.bing.com</a>";  
  5. $stTextSig = "Get a HTML email editor it is 2012 you know";  
  6. if($UsrConfig.Dictionary.ContainsKey("signaturehtml")){  
  7.     $UsrConfig.Dictionary["signaturehtml"] = $hsHtmlSigniture  
  8. }  
  9. else{  
  10.     $UsrConfig.Dictionary.Add("signaturehtml",$hsHtmlSigniture)  
  11. }  
  12. if($UsrConfig.Dictionary.ContainsKey("signaturetext")){  
  13.     $UsrConfig.Dictionary["signaturetext"] = $stTextSig  
  14. }  
  15. else{  
  16.     $UsrConfig.Dictionary.Add("signaturetext",$stTextSig)  
  17. }  
  18. $UsrConfig.Update()  
Message Records Management

The MRM Tag configuration for a mailbox is also held within a FAI item (you shouldn't be modifying this setting via EWS) but it is useful if you are creating a script that is going to be stamping these tags on Folders or Items to be able to retrieve them via EWS. This is a sample of getting the MRM Policy and Archive Tags from the FAI items that is held in the Inbox

  1. $folderid= new-object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Inbox,$MailboxName)     
  2. #Specify the Inbox folder where the FAI Item is  
  3. $UsrConfig = [Microsoft.Exchange.WebServices.Data.UserConfiguration]::Bind($service"MRM"$folderid, [Microsoft.Exchange.WebServices.Data.UserConfigurationProperties]::All)  
  4. $ConfXML = [System.Text.Encoding]::UTF8.GetString($UsrConfig.XmlData)    
  5. [XML]$ConfXML = $ConfXML    
  6. $ConfXML.UserConfiguration.Info.Data.PolicyTag  
  7. $ConfXML.UserConfiguration.Info.Data.ArchiveTag  
If you love working with Binary data than there is a lot more that can be done on the customization side using this operation to modify View Definitions etc these are very targeted configurations though and can be time consuming so I'm not going to cover those for now.

16 comments:

Anonymous said...

I am trying to create a custom Transport agent. This piece of code doesn't work for me:

if (e.MailItem.Message.To.Equals("timesheet@contoso.com"))
e.MailItem.Message.Subject = "Timesheet";

Can you tell what is wrong? I have tried to replace it with:

if (e.MailItem.Message.To.ToString() == "timesheet@contoso.com")
e.MailItem.Message.Subject = "Timesheet";

And it still doesn't work. Thanks.

Anonymous said...

The timesheet@contoso.com is a distribution group which forwards email messages to a SharePoint site document library.

How can i fix it? Thanks.

Anonymous said...

for Master Categorylist will output xml file to directory?

Glen said...

Sorry neither of these questions make sense ?

Cheers
Glen

Anonymous said...

sorry our question too short. I want to change the masterCategoryList for all this org users. I try your script on first phase. No any error and no any display on screen. I will this will create the xml file to directory but no. Then I stop to try the phase 2. Can we save the xml on directory? or show on screen?? thanks alot.

Glen said...

if you run Get-MessageCategory http://technet.microsoft.com/en-us/library/ee332329.aspx on the same mailbox do you see a category list ?. That mailbox need to have been logged onto for this to work.

Cheers
Glen

Anonymous said...

When running the first code example to examine the category list from my own mailbox, I get:
Cannot convert value "?xml version="1.0"?>

It then dumps the the entire xml to screen, followed by:
Error: "The specified node cannot be inserted as the valid child of this node, because the specified node is the wrong type."
[XML]$CatXML = $CatXML.SubString(1)

Glen Scales said...

Try changing the line to

[XML]$CatXML = $CatXML

The substring was dropping the ByteOrder mark which doesn't seem to a problem from you

Cheers
Glen

Anonymous said...

Awesome, now I just need to figure out how to use this to rename existing categories. Thanks for the quick reply!

Anonymous said...

Hi Glen, is it possible to add a new category for all mailboxes in the organization? My company is on Exchange Online and we want to create an inbox rule that checks message headers for a custom parameter and will be apply this category to messages that match the rule. If this is possible, would you be able to share how to accomplish this? Thanks!

Glen Scales said...

Categories are stored per mailbox, probably the best way to is use a GPO to push the category to you users see http://www.thirdtier.net/2015/05/pushing-outlook-categories-to-all-users/ . Otherwise you can write a script to do it (eg there is sample in this post that could be expanded) but it has to be run and maintained (eg new user provisioning etc) on a ongoing basis so a GPO would be a better method.

Andy Meyers said...

Thanks for writing this! Stumbling across it has been a huge time saver for me. Is there any way to create the master category list if they haven't logged in yet? I'm trying to add a category to a few users but they haven't logged into their mailboxes yet and am getting "The specified object was not found in the store., The configuration object was not found. Name = CategoryList." It works fine on established users.

Unknown said...

I have the same issue, changing the line as you suggested doesn't work.

ibro debill said...

I have the same issue when running [XML]$CatXML = $CatXML.SubString(1). The error is Error: "The specified node cannot be inserted as the valid child of this node, because the specified node is the wrong type."
This error happens sometimes for some mailboxes. The only workaround i found is to replace the entire xml of this mbx with the xml file of another mbx then recreate the first mbx categories.
i would prefere to fix the broken xml instead of replacing it so if someone has a solution...

ibro debill said...
This comment has been removed by the author.
ibro debill said...

I found a solution:
[string]$CatXML = [System.Text.Encoding]::UTF8.GetString($UsrConfig.XmlData)