Exchange 2010 : Powershell

Working with Disconnected Mailboxes in Exchange Server 2010, Office 365 and Hybrid–Part 2

Michael Van Horenbeeck — Sun, 13 May 2012 21:22:06 GMT

Introduction

In the previous part of this article, we covered some of the basics about what disconnected mailboxes are and showed how to ‘work’ with them in an on-premise deployment of Exchange Server 2010.
This second (short) part will focus mostly on disconnected mailboxes and archives in Office 365 (Exchange Online). As you will see, since Exchange Online is also based on Exchange Server 2010, differences are rather small and mostly due to the limitation of being a “shared platform”.

Locating disconnected/deleted mailboxes

Before, I showed you how you could find disconnected mailboxes in your environment. Working with disconnected mailboxes in Office 365 is pretty much the same. However, the example script from the previous part uses the Get-MailboxServer cmdlet which isn’t available in Exchange Online. Alternatively, you could/should use the Exchange Control Panel and navigate to the following page:

By clicking the highlighted button, a new window will appear which will provide you a list of all (soft) deleted mailboxes:

From this window, you also have the options to recover a mailbox.

Cloud-based Archives

Cloud-based archives (or Online Archives) are also a bit special. They exist online while the user’s mailbox can be located on-premise. If that is the case, you’ll be somehow limited in how you can treat disconnected archives.
You will only be able to reconnect the archive, by re-enabling it. For example, re-enabling the Online Archive for an on-premise user:

Enable-Mailbox <Identity> –RemoteArchive –ArchiveDomain<servicedomain>

If a disconnected archive exists, it will be reconnected. If not, a new archive will be created. Disconnected/Deleted archives will stay in Exchange Online for 30 days. After that, they are deleted and not recoverable.

Note disconnected archives will stay in Exchange Online for 30 days. After that, they are deleted and not recoverable.

Cheating to restore an (on-premise) Archive

As stated earlier, you can only restore an Archive to the user account it previously belonged to. But what if you (accidentally) deleted that account and cannot recover it from a backup? The answer is simple: you’ll have to cheat Exchange into believe that the new account you created is actually the old one. To do this, you change the legacyExchangeDN-attribute for the new user account into the value of the old user account. If you don’t know what the old value was; try reconnecting the archive: the command will fail and provide you the legacyExchangeDN it is looking for. The error will look something like this:

The legacy DN '/O=COMPANY/OU=EXCHANGE ADMINISTRATIVE GROUP (FYDIBOHF23SPDLT)/CN=RECIPIENTS/CN=<USERACCOUNT>' of disconnected mailbox does not match user legacy DN '/o=COMPANY/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=<USERACCOUNT_OLD>'.

+ CategoryInfo : NotSpecified: (Microsoft.Excha...ilboxStatistics:MailboxStatistics) [Connect-Mailbox], M

dbAdminTaskException

+ FullyQualifiedErrorId : 13614534,Microsoft.Exchange.Management.MapiTasks.ConnectMailbox

To work around this issue, do the following:

Open ADSI Edit and connect to the default naming context
Navigate to the new user’s object, and open the properties. Located the legacyExchangeDN-attribute and enter the value that was attributed to the old account. Write down the value that is currently in there so that you can change it back afterwards.
Now, try connecting the archive to the new user account. This time, the command should succeed. (Connect-Mailbox –Identity <id> –Archive –user <(Alternative_)user>)
Either export the archive to a PST or import the content temporarily back into the primary mailbox.
Disable the archive.
Change the legacyExchangeDN value back to the value you wrote down.
Create a new archive for the user.

Changing back the the legacyExchangeDN value on the new user account avoids possible issues further down the road. Alternatively, you can run the steps above against a (service) account that you created only for this purpose. That way, you don’t have to change attributes on a user-account that is in use.

Note since you cannot alter this attribute for online users; you will not be able to run this cheat in Exchange Online. Also note that this ‘cheat’ is not supported!

Have fun!

Michael

Working with Disconnected Mailboxes in Exchange Server 2010, Office 365 and Hybrid–Part 1

Michael Van Horenbeeck — Sun, 29 Apr 2012 21:29:00 GMT

Introduction

In this article, I will try to explain what Disconnected mailboxes are. How a mailbox becomes disconnected and how you can identify and work with disconnected mailboxes in Exchange Server 2010 on-premise, Exchange Online and in a combination of both (Hybrid).

First, to understand what disconnected mailboxes are we need to take a (quick) look at what ‘mailbox’ actually is. The object that you see when running Get-Mailbox or through the Exchange Management Console is actually called a user-mailbox. In fact, that name literally states what it represents: a user and a mailbox. A user mailbox is thus a “combination” of an AD User Account and an Exchange Mailbox:

All information on the user’s Exchange mailbox is stored in the user’s AD-attributes whereas the data itself is stored within the mailbox in Exchange. Using either ADSIEdit or PowerShell, you can view these attributes. The following list shows a common set of attributes for a user with an Exchange mailbox. Note that all Exchange-related attributes start with “msExch*”:

msExchAddressBookFlags                : 1
msExchArchiveQuota                    : 52428800
msExchArchiveWarnQuota                : 47185920
msExchBypassAudit                     : False
msExchDumpsterQuota                   : 31457280
msExchDumpsterWarningQuota            : 20971520
msExchHomeServerName                  : /o=Exchange/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Configuration/cn=Servers/cn=E14-EX10-01
msExchMailboxAuditEnable              : False
msExchMailboxAuditLogAgeLimit         : 7776000
msExchMailboxGuid                     : {70, 147, 162, 91...}
msExchMailboxSecurityDescriptor       : System.DirectoryServices.ActiveDirectorySecurity
msExchMDBRulesQuota                   : 64
msExchModerationFlags                 : 6
msExchPoliciesIncluded                : {1429c9fb-4d64-45c2-84f5-fa61dfa1a19c, {26491cfc-9e50-4857-861b-0cb8df22b5d7}}
msExchProvisioningFlags               : 0
msExchRBACPolicyLink                  : CN=Default Role Assignment Policy,CN=Policies,CN=RBAC,CN=Exchange,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=EXCH14,DC=local
msExchRecipientDisplayType            : 1073741824
msExchRecipientTypeDetails            : 1
msExchTextMessagingState              : {302120705, 16842751}
msExchTransportRecipientSettingsFlags : 0
msExchUMDtmfMap                       : {emailAddress:6484, lastNameFirstName:64242358264673623325, firstNameLastName:64242358264673623325}
msExchUMEnabledFlags2                 : -1
msExchUserAccountControl              : 0
msExchVersion                         : 44220983382016
msExchWhenMailboxCreated              : 29/04/2012 11:34:09

The above list is what you see under normal circumstances. However, it is possible that a user’s mailbox gets “disconnected” from the user’s object. This means that the User Object and the Exchange Mailbox are no longer ‘linked’ together. There are two ways this can happen:

When you disable a user’s mailbox, the Exchange mailbox itself does not get deleted immediately. The mailboxes are retained in the environment for the duration of the deleted mailbox retention period (by default 30 days) unless you permanently delete the mailbox deliberately.
Whenever a soft-delete occurs. This is usually the case where a user’s mailbox is moved from one database to another. After the move, Exchange will not delete the source mailbox from the source database. Instead, it will mark the source mailbox as “soft-deleted”. Just as with disabled mailboxes, they are kept within the database for the duration of the deleted mailbox retention period unless deleted permanently on purpose.

Whenever a user’s mailbox is disconnected the user account attributes also change. For example: disabling a user’s mailbox might result in only the following attributes still having a value:

msExchAddressBookFlags   : 1
msExchBypassAudit        : False
msExchProvisioningFlags : 0
msExchUMDtmfMap          : {emailAddress:6484, lastNameFirstName:64242358264673623325, firstNameLastName:64242358264673623325}
msExchWhenMailboxCreated : 29/04/2012 11:34:09

As you can see neither msExchangeHomeServerName or msExchangeMailboxGuid are present. These attributes represent the user’s mailbox and the Exchange server where the mailbox is located. They are unique to a mail-enabled account. But because it’s disabled, the values are now empty.

Note to retrieve these attributes using PowerShell, you can e.g. run the following command:

Get-ADUser <username> –properties * | Select-Object MSExch*

Retrieving Disconnected Mailboxes

Disconnected mailboxes show up in the Disconnected Mailboxes container under Recipient Management in the Exchange Management Console:

Although this is the easiest way to identify any existing disconnected mailboxes, the Management Console is limited in the actions that you can perform on these mailboxes. For the remainder of this article, I’ll continue showing how you can work with disconnected mailboxes from the Exchange Management Shell.

To retrieve a list of disconnected mailboxes using PowerShell, you must run the following command. This command will only return mailboxes that have been disabled.

Get-Mailbox | Get-MailboxStatistics | ? {$_.DisconnectReason –eq “Disabled”}

Retrieving a list of all disconnected mailboxes is a bit more “tricky”. You could either combine to conditions:

Get-Mailbox | Get-MailboxStatistics | ? {($_.DisconnectReason –eq “Disabled”) –or ($_.DisconnectReason –eq “SoftDeleted”)}

Additional Info MVP Mike Pfeiffer created a script that uses a slightly different approach: instead of looking at DisconnectReason, it will rather look at the “DisconnectDate” attribute. If the attribute contains a value, the mailbox is considered in a disconnected state (no matter how it got disconnected).

Note It is entirely possible that not all disconnected mailboxes show up when running the commands above: if you disabled the mailbox only recently, it might be possible that the mailbox isn’t marked as disconnected in the Exchange store yet. To “force” the detection of disconnected mailboxes, you would then use the Clean-Mailboxdatabase command:

Clean-MailboxDatabase –Identity <mailboxdatabase>

Working with Disconnected mailboxes

In case of a disabled mailbox, there are three actions that you can perform:

Connect it to an existing user account in Active Directory
Restore it to a new or existing user account in Active Directory
Permanently delete it from the Exchange mailbox database

On mailboxes that are in a soft-deleted state, you can only perform the following two actions:

Restore the mailbox
Permanently delete it from the Exchange mailbox database

Reconnecting disconnected mailboxes

By default, when running the Connect-Mailbox command, the disconnected mailbox will be reconnected to the matching user account. Alternatively, you can also use the New-MailboxRestoreRequest command which is only available through the EMS. The latter will leverage the Mailbox Replication Service (MRS) to recover mailbox data from the mailbox into an existing, connected, mailbox.

Note you can only reconnect a mailbox using Connect-Mailbox to a user account that has currently no mailbox connected.

To reconnect a mailbox, run the following command:

Connect-Mailbox –Identity <identity> –Database <database> –user <user>

Restoring disconnected mailboxes

Restoring a disconnected mailbox is different from reconnecting one. Instead of reconnecting the mailbox to a user accounts that does not have a mailbox it will use MRS to copy contents from the disconnected mailbox into a target mailbox. Note that this is also your only option in case of a soft-deleted mailbox. They cannot be reconnected using the connect-mailbox command.

You will need to have the correct permissions (Recipient Provisioning Permissions) in order to run this command. For more information, please have a look here: http://technet.microsoft.com/en-us/library/dd638132.aspx

New-MailboxRestoreRequest –SourceDatabase <database> –SourceStoreMailbox <disconnectedmailbox> –TargetMailbox <targetmailbox>

Note if you are restoring to an alternate user account, the command will throw an error (see screenshot for more details). In that case, you will need to add the –AllowLegacyDNMismatch parameter in order to complete the command successfully. The check whether or not the LegacyDN matches on both source and target mailbox is performed is to prevent you to accidentally restore the mailbox to the wrong target mailbox.

Optionally, you can also restore a disconnected mailbox to an archive mailbox:

New-MailboxRestoreRequest –SourceDatabase <database> –SourceStoreMailbox <mailboxGuid> –TargetMailbox <targetmailbox> –TargetIsArchive

As you can see from this command, the parameter “-TargetIsArchive” is used to determine that we’re restoring an archive.

From an end-user perspective, he (or she) will see the contents from the disconnected mailbox merged into the existing mailbox. Using different switches with the New-MailboxRestoreRequest command, you can control what and where mails are restored. For more information, please visit: http://technet.microsoft.com/en-us/library/ff829875.aspx

Permanently Deleting a Disconnected Mailbox

To permanently remove a disconnected mailbox, you use either the Remove-Mailbox or Remove-StoreMailbox command:

To remove both the mailbox and user account immediately, run the following command:

Remove-Mailbox –Identity <mailbox> –Permanent $true

Alternatively, you can remove a previously disconnected mailbox using the following command:

Remove-StoreMailbox –Database <database> –Identity <name> –MailboxState <SoftDeleted/Disabled>

Note the identity of the mailbox to be deleted can either be the mailbox's name or GUID.

Personal Archives

Personal Archives behave quite similar to regular mailboxes. When an archive is disabled, it also becomes disconnected and it will also remain in the database until the deleted mailbox retention period has elapsed. The process of reconnecting a personal archive is also pretty similar to reconnecting a regular disconnected mailbox:

Connect-Mailbox –Identity <name or Guid> –Archive –User <user> –Database <database>

Note the –Archive switch. Adding this parameter ‘tells’ the command that you’re reconnecting an archive.

Note you cannot reconnect an archive to another user. It must be reconnected to the user it was previously connected to.

Conclusion

This concludes the first part of this article in which we covered the most important actions regarding Disconnected Mailboxes. In the next part of this article we are going to have a look at what you can do with Disconnected Mailboxes in Office 365 and/or a hybrid deployment.

For more information on Disconnected Mailboxes, have a look at the following TechNet-article: http://technet.microsoft.com/en-us/library/bb232039.aspx

Cheers!

Michael

PowerShell 101 – bulk actions with PowerShell

Michael Van Horenbeeck — Sun, 04 Mar 2012 23:05:03 GMT

Introduction

As a consultant, I’m frequently confronted with all sorts of questions. Some of them have already been subject of one of my posts, but there’s still the number one questions that I haven’t blogged about: how do you perform bulk-actions via PowerShell? Microsoft is screaming: “Learn PowerShell” for quite a while now, still a lot of IT Pro’s haven’t found their way to it yet. Mostly this is because they’re not confronted with PowerShell yet or – so I have been told – the learning-curve to start with PowerShell is quite steep.

I must admit that when I was first facing PowerShell I thought to myself: how on earth am I going to grasp this. Only to find myself a short while later working almost exclusively in PowerShell. The only thing to get you going are some of the key concepts and a good will. The rest will follow automatically.

In this article I will go through some of the basics that you will need to perform most common (bulk) actions.

Pipeline

PowerShell is all about (.NET) objects. Every cmdlet you run, will return objects. These object can either be attributed to a variable (e.g. in a script) or they can be sent through “the pipeline” to another cmdlet which will use those objects as input for processing. Let’s use an example to clarify things:

The cmdlet Get-Mailbox will return a list of all mailboxes in your organization:

For styling-purposes, I omitted a part of the results from the screenshot.

Now, let’s say you would want to change the quota for all of these mailboxes, you could simply “pipe” the results to another cmdlet. For instance, you would want to change the ProhibitSendQuota for each mailbox to 3GB:

Get-Mailbox | Set-Mailbox –ProhibitSendQuota 3GB

A quick check (Get-Mailbox) will indeed confirm the settings has been changed for each mailbox:

As you can see, sending object through the pipeline is relatively simple. We will come back to this a bit later when we will be bulk-importing users.

Filtering

There are a few ways of filtering the results of a cmdlet in PowerShell: you could use the –Filter parameter that is available with some cmdlets or you pipe the results from your cmdlet to a where-clause. The difference between both is that using the filter-parameter will actually narrow down the scope of the cmdlet which results in less objects returned in the output, whereas the other method will return all object after which they are filtered by the where-clause. Therefore the first approach usually consumes less resources as fewer results are actually returned. Let’s use the example where we want only mailboxes returned that have a specific value in a custom attribute.

Using the filter-parameter:
Get-Mailbox –Filter {CustomAttribute1 –eq “Example”}
Using the where-clause after the pipeline:
Get-Mailbox | Where-Object {$_.CustomAttribute1 –eq “Example”}

As you can see, the results for both cmdlets are identical. To clarify the results, I also added “| FT Name,CustomAttribute1” to the cmdlet. This sends the results from previous cmdlets through the pipeline where they are formatted. FT stands for Format-Table. This will format the results in a table. By specifying properties immediately behind the Format-Table, I limited the output to only those properties. For more information on formatting the output of a cmdlet, have a look here: Using Format Commands to Change Output View

To filter results, in this example, I the “-eq” operator which stands for “equals”. There are other operators that you could use as well. More information can be found through the PowerShell help: ‘Get-Help About_Operators’,' ‘Get-Help About_Logical_Operators’ and ‘Get-Help About_Comparison_Operators’

Passwords

PowerShell treats passwords a bit different than most other object. Passwords obviously need to be secure. Usually, when a cmdlet allows you to provide a password (e.g. New-ADUser or New-Mailbox) it requires that the value for that property is a secured string (not just plain text).

Entering the following would just not work. I will omit all other parameters, just for clarity:

New-Mailbox –Password “thisisthepassword”

In order to get “around” this, you can do either of the following:

Leverage the Get-Credential cmdlet:

New-Mailbox –Password (Get-Credential).password

Alternatively, you could assign the password to a variable and use that variable in the cmdlet:

$password = (Get-Credential).Password
$New-Mailbox –Password $password
Use ConvertTo-Securestring:

New-Mailbox –Password (ConvertTo-SecureString –AsPlainText “Password” –Force)

Note: The first approach is more secure as you will be prompted to enter credentials (=password not visible). The second approach requires you to write down the password in clear text in the script and makes it visible to anyone who can read the script.

Example: Bulk importing

One of the tasks that PowerShell significantly facilitates is bulk importing objects like e.g. users. Using the Import-CSV cmdlet, PowerShell allows you to easily import contents from a CSV file. Let’s say we would like to bulk-import a couple of new users. First, we start off by creating a new (simple) CSV file. The New-Mailbox cmdlet (which we will be using to create a new mailbox) has some required parameters which we will add to the CSV file. The only one we’re not adding right now is the password because it would be entered in clear text in the CSV-file and therefore be visible to everyone who opens the CSV:

FirstName,LastName,UserPrincipalName

User1,Test,user1@domain.com
User2,Test,user2@domain.com
…

Now, import the CSV:

Import-CSV <path_to_csv>

Note: PowerShell recognizes that you’re trying to import objects and will create an object per line in your CSV file.

We still haven’t actually created new mailboxes right now. In order to create new mailboxes, we need to do something with the objects from the CSV file. By piping the results from the Import-Csv cmdlet to the New-Mailbox cmdlet we will create new mailboxes:

Import-Csv <path_to_csv> | Foreach-Object {New-Mailbox <parameters>}

How does PowerShell know what value to give to what property for the new mailbox? Actually, you will have to tell PowerShell which properties to use. You do this by assigning a property that went through the pipeline to an attribute of the New-Mailbox cmdlet.
For instance:

Import-Csv <path_to_csv> | Foreach-Object {New-Mailbox –FirstName $_.<propertyname>}

The names of the properties are the headers that you used in your CSV file (make sure that your headers do not contain spaces). In the example from above this would be FirstName, Lastname and UserPrincipalName:

Import-Csv c:\import.csv | Foreach-Object {New-Mailbox –FirstName $_.FirstName}

Note: The “$_” refers to the object that is currently being passed through the pipeline. Each line in your CSV file is represented by an object (PowerShell automatically creates an object for each line). The values you’ve provided in your CSV are the properties for that given object.Thus, $_.FirstName stands for the property with name “FirstName” of the object that is currently coming through the pipeline. In this example this is either User1 or User2.

When we bring things together, we would get the following:

Import-Csv c:\import.csv | Foreach-Object {New-Mailbox –FirstName $_.FirstName –LastName $_.LastName –UserPrincipalName $_.UserPrincipalName}

Note: sometimes you’ll see something like this: Import-Csv <csv> | foreach{<action>} or even Import-Csv <csv> | %{<action>}. Both “foreach” and “ %” are abbreviations for Foreach-Object. You can also abbreviate Where-Object with either “where” or “?”.

We’re not completely there yet. We’re still missing Name and Password.

The Name-property specifies the user’s name as it will appear in Active Directory Users and Computers and on the Recipient Properties and User Information tab. In this example we’ll combine the user’s first name and last name by assigning these values to a new variable:

$name = $_.FirstName+” “$_.LastName

The password – as explained before requires a somewhat different approach. We will create a new variable and assign a password to it:

$password = (Get-Credential).password

Note: If we would use the Get-Credential cmdlet within the foreach-loop, we would be prompted for a password for each new object that passes through the pipeline. In our example that would only be two times, but imagine importing a few hundred items…

Bringing everything together generates the following script:

$password = (Get-Credential).password

Import-Csv c:\import.csv | Foreach-Object{

$name = $_.Firstname+” “+$_.LastName

New-Mailbox –Name $name –FirstName $_.FirstName –LastName $_.LastName –UserPrincipalName $_.UserPrincipalName –Password $password

}

Exchange 2010: User Permission Enumeration Script

Michael Van Horenbeeck — Mon, 27 Feb 2012 21:40:09 GMT

Introduction

Recently, someone asked me if it was possible to get an overview of all the permissions one might have been granted on other mailboxes. The first thing that popped up in my mind was to use the Get-MailboxPermission cmdlet, but soon I realized there were some limitations.

First of all, the cmdlet appears to only take into consideration explicitly granted permission. Thus if a user would be granted access through means of a group, those permissions would not show up. Secondly, the cmdlet would not return all permissions one might have over a mailbox. To overcome that, I would also need to run the Get-AdPermission cmdlet.

As you will notice, the script is not very performing. One might ask why I created it then. Well, first of all there was the question that got me to write the script. And secondly (probably the most important reason) was that I wanted to prove that PowerShell could handle virtually anything. I hope by sharing this script, you maybe pick up some ideas or learn a few tricks. Either way, there’s still a lot room left for improvement and I’m eagerly awaiting your feedback. If you have any comments, suggestions or you found a bug: please let me know!

The Script

The script will create a HTML-report listing either all Mailbox- or all AD Permissions (on a mailbox) for a given user. The script will also take into account that permissions might have been granted through group membership. However; this currently goes only one level deep. Groups that are within the top-level group are disregarded.

You can download the script from here: http://www.pro-exchange.be/media/p/1362.aspx

Requirements

Due to some restrictions, the script can – for now – only be run from an Exchange Server. It needs both the AD Module for PowerShell as well as the Exchange Management Shell. The script takes into account that the AD Module for PowerShell isn’t loaded by default and will do so – if available:

    Get-Module -ListAvailable | foreach{ if($_.Name -eq "ActiveDirectory"){$module = "true"} }
    if($module -eq "true"){
        Import-Module ActiveDirectory
    }
    else{
        // end script and notify
        Write-Output "This script requires AD DS Remote Server Administration Tools to be installed"
        Exit
    }

How does it work?

When taking a look at the logic behind the script it’s all very simple:

How to use the script

I have tried making the usage of the script as easy as possible. To be honest, Jason Helmick inspired me during one of his presentations @ TechDays 2012; so that is why I chose to create a “tool”-alike script. When dot-sourcing the script, you will actually be able to start the process by running the Get-UserMailboxPermission cmdlet.

First, dot-source the script:

. .\Get-UserMailboxPermissions.ps1

After doing this, the Get-UserMailboxPermission cmdlet will be available, allowing you to kick of the processing:

Get-UserMailboxPermission –User <username> –path <path_to_report> –query <AD/Mailbox>

About the arguments:

The User-parameter is used to indicate which user you want to look for permissions for. In other words: “what permissions does this user have on all other mailboxes?”. Enter a users’ alias here.
The Path-parameter is just the location where the report will be stored. It only needs a path as the filename is – at this time – chosen by the script.
The Query-parameter is used to indicate whether to look for mailbox permissions or for AD permissions on mailboxes. Hence either to use “AD” or “Mailbox”.

Running Get-Help Get-UserMailboxPermission will provide you with more information about the script:

The result

After processing, a HTML-report is generated which provides you with a table that lists all the users’ permissions for other mailboxes. Different colors are used to indicate whether a permission was granted (or denied) explicitly or through group membership:

Performance

Unfortunately (but not totally unexpected) the script is not very performing. This is largely due to the fact that it will enumerate all permissions for all mailboxes. It goes without saying that the more mailboxes you have, the more time it will take to process. As a reference: I used the script in a medium-sized environment with about 750 mailboxes and it took a little over a half our to complete processing the mailbox permissions. Given the fact that going through the AD permissions is an even bigger task, one might expect that it could run well over a few hours. However; at this point I haven’t been able to test the report for AD-permissions on such a scale yet. I expect it to run at least twice as long (if not even longer…).

The future

I’m planning on continuing to develop this script and maybe add some features over time.

The next release I should have fixed/added:

Allow the user-argument to accept values from the pipeline
Combine both AD- and mailbox permissions in a single report
Better error handling
….

Don’t forget to check back regularly for updates!

The Exchange 2010 Scripts

Michael Van Horenbeeck — Sun, 18 Dec 2011 20:58:41 GMT

Introduction

Both Exchange 2007 and Exchange 2010 are accompanied by a bunch of pre-created scripts that allow you to perform various tasks ranging from configuring some extra services to some basic reporting. These scripts reside in a “scripts”-folder within the Exchange installation folder and can easily be reached using the “$exscripts”-variable (which contains the path to the folder) from the Exchange Management Shell:

Almost every Service Pack that was released introduced some new scripts. Because Exchange 2010 SP2 recently hit the road, I decided to create an overview of the new scripts that shipped with it along with the existing ones. In the overview I will try to gather the available information and explain the script’s purpose. I will also try to keep this list up to date if newer scripts would be released in the future.

Did you know?

The TechNet website offers a lot of scripts with various purposes that can be used with different versions of Exchange. The repository contains scripts from both the MS Exchange Team as other Exchange professionals and are freely available for download. Check out the TechNet Script Repository for more fancy scripts!

The “stars” of the scripts folder

The following list contains all scripts from the Exchange 2010 Scripts folder with information I gathered from various resources (mostly TechNet) as well as personal experiences. Sources and additional information are always mentioned under “More information:”

Name

Purpose

AddReplicaToPFRecursive.ps1

This script will add replicas to existing Public Folders and is often used during migrations from one Exchange version to another (e.g. Exchange 2003 to Exchange 2010).

To execute the script, use the following syntax:

AddReplicaToPFRecursive.ps1 –Server <oldservername> –ServerToAdd <newservername> –TopPublicFolder <pfname>

AddUsersToPFRecursive.ps1

This script will add user permissions to Public Folders.

Note: If you use the script, but a user has already access to a specific Public Folder, the script will throw a warning.
More information: http://technet.microsoft.com/en-us/library/aa998834.aspx

AggregatePFData.ps1

The script aggregates and captures information collected from three cmdlets:

Get-PublicFolderItemStatistics
Get-PublicFolderStatistics
Get-PublicFolder

The following information is aggregated at the public folder level, and not at the item level:

Last user access and last user modification times
Owner of the public folder
Properties such as MailEnabled, HasRules, ItemCount, FolderType, HasModerator, and TotalItemSize

More information: http://technet.microsoft.com/en-us/library/ee633474.aspx

AntispamCommon.ps1

This script is referenced by other anti-spam scripts in Exchange 2007 and is not intended to be used directly.

CheckDatabaseRedundancy.ps1

Checks the redundancy of databases by validating that they have at least N configured and "healthy" copies. Active and passive copies are both counted.

To use this script you need to provide either $MailboxDatabaseName or $MailboxServerName.To generate events for Monitoring, you need to provide -MonitoringContext switch.

Note: This scripts will only provide an output if a DAG is present in the environment.

CheckInvalidRecipients.ps1

This script is designed to return information on invalid recipient objects and possible attempt to fix them.

The script will attempt to fix two classes of errors:

Primary SMTP Address Problems: If a recipient has multiple SMTP addresses listed as primary or the primary SMTP is invalid, the script will try to set the WindowsEmailAddress as the primary SMTP address, since that is the address Exchange 2003 would have recognized as the primary (although E12 does not)
Distribution Group Hidden Membership: If a distribution group has HideDLMembershipEnabled set to true, but ReportToManagerEnabled, ReportToOriginatorEnabled and/or SendOofMessageToOriginatorEnabled are set to true, then the membership is not actually securely hidden. The script will set ReportToManagerEnabled, ReportToOriginatorEnabled and SendOofMessageToOriginatorEnabled to false to fix the distribution group.

Note: to automatically try fixing reported problems, the –FixErrors switch needs to be provided.

CITSConstants.ps1

This file contains global constants used by CI Troubleshooter library

CITSLibrary.ps1

This file contains Content Index Troubleshooter functions

CITSTypes.ps1

This file contains additional types used by CI troubleshooter library

CollectOverMetrics.ps1

This script reads DAG member event logs to gather information about database operations (such as database mounts, moves, and failovers) over a specific time period. For each operation, the script records the following information:

Identity of the database
Time at which the operation began and ended
Servers on which the database was mounted at the start and finish of the operation
Reason for the operation
If the operation was successful, including the error details if the operation failed

The script writes this information to .csv files with one operation per row. It writes a separate .csv file for each DAG.

More information: http://technet.microsoft.com/en-us/library/dd351258.aspx#CollectOver

CollectReplicationMetrics.ps1

This script provides an active form of monitoring because it collects metrics in real time, while the script is running. It collects data from performance counters related to database replication. The script gathers counter data from multiple Mailbox servers, writes each server's data to a .csv file, and can then report various statistics across all of this data (for example, the amount of time each copy was failed or suspended, the average copy or replay queue length, or the amount of time that copies were outside of their failover criteria).

More information: http://technet.microsoft.com/en-us/library/dd351258.aspx#CollectRep

configure-SMBIPsec.ps1

This script is to be used to help add the necessary IPsec configuration to protect SMB (File Share) communication.

ConfigureAdam.ps1

You can use the ConfigureAdam.ps1 script in the Shell to modify the default configuration of the Active Directory Lightweight Directory Services (AD LDS) on the Edge Transport server.

After you install the Edge Transport server role, you can use the ConfigureAdam.ps1 script provided with Exchange 2010 to modify the ports and directories that AD LDS uses. The ConfigureAdam.ps1 script invokes the dsdbutil command to change the registry settings for AD LDS.

ConfigureNetworkProtocolParameters.ps1

Configures a Global Catalog running on the machine on which the script is run to listen on the standard NSPI Rpc-over-Http port 6004. This would enable Rpc-over-Http connections from Outlook clients to a GC, RpcProxy'ed by CAS boxes.

More information: http://technet.microsoft.com/en-us/library/bb124159(EXCHG.65).aspx

ConvertOABVDir.ps1

This script will convert the OAB virtual directory to an IIS web application, as well as, create a new application pool, MSExchangeOabAppPool. Converting the OAB virtual directory is necessary to support different authentication methods like Kerberos and Certificate authentication.

Note: You need to execute this script on each Client Access Server.
More Information: http://gallery.technet.microsoft.com/scriptcenter/525fb1dc-b612-4998-a2d1-55f32a6c35ac

ConvertTo-MessageLatency.ps1

This script enables you to get latency information any email still in the Message Tracking Logs. This can be useful in troubleshooting scenarios where you have to deal e.g. with slow email delivery.

DagCommonLibrary.ps1

A collection of DAG-related functions for use by other scripts.

DatabaseMaintSchedule.ps1

Random generates maintenance and quota notification schedule time based on the specified criteria.

DiagnosticScriptCommonLibrary.ps1

Library file used by scripts in the Management Pack for Exchange 2010 (SCOM)

Disable-InMemoryTracing.ps1

This script will undo the changes made by the Enable-InMemoryTracing.ps1 script.

Usage:

.\Disable-InMemoryTracing.ps1

enable-CrossForestConnector.ps1

When you want to establish direct mail flow with servers that are running Exchange in a different Active Directory forest, you must configure both Send- and Receive connector with.

This script will adjust the permissions on a Send Connector (add ‘ANONYMOUS LOGON’ to the Send Connector)

More information: http://technet.microsoft.com/en-us/library/bb123546.aspx

Enable-InMemoryTracing.ps1

This script will enable In-Memory tracing by changing the InMemoryTracing value from $false to $true in the EnabledInMemoryTraces.config in the bin directory, found under the the Exchange Install Folder.

Usage:

.\Enable-InMemoryTracing.ps1

enable-OutlookCertificateAuthentication.ps1

This script will configure the different virtual directories so that Outlook can used Smart Card Authentication.

More information: http://technet.microsoft.com/en-us/library/hh227263.aspx

ExchUCUtil.ps1

Script that makes necessary changes so that OCS/Lync can read UM data from Exchange.

More information: http://technet.microsoft.com/en-us/library/dd572267(office.13).aspx

Export-OutlookClassification.ps1

Script that exports your message classifications so that they can be imported into Outlook. The script will generate an XML-file.

More information: http://technet.microsoft.com/en-us/library/aa998271.aspx

Export-RetentionTags.ps1

This script is used in conjunction with the Import-RetentionTags.ps1 script and exports existing Retention Policy Tags to an xml file. It has proven to be useful in deployments where also Exchange Online (Office 365) is used.
If a user applied Retention Policy Tags prior to moving his mailbox to the cloud, they need to be exported from the on-premise environment and imported to Office 365. This has to be done prior to moving the mailbox.

Running the script is relatively easy:

.\Export-RetentionTags.ps1 <path_to_xml_file>

More information: http://technet.microsoft.com/en-us/library/dd297955.aspx

get-AntispamFilteringReport.ps1

You can run this script to draw a report for the Exchange Anti Spam Agents. The following values are accepted as command parameters:

messagesrejected
messagesdeleted
connections
messagesquarantined

Usage:

.\Get-AntispamFilteringReport.ps1 <command> –report <path>

get-AntispamSCLHistogram.ps1

This script will output the total number of emails calculated for every SCL Rating.

Usage:

.\Get-AntispamSCLHistogram.ps1

More information: http://technet.microsoft.com/en-us/library/aa995744.aspx

get-AntispamTopBlockedSenderDomains.ps1

This script will show you which domains have the largest share in the amount of spam sent to you.

Note: this information can sometimes be misleading because spammers tend to spoof real email addresses. This script cannot and does not take this into account. However, for domains that you are absolutely sure you don’t want to get emails from, this might prove very useful.

get-AntispamTopBlockedSenderIPs.ps1

This script will show the top 10 IP addresses that have sent you spam. This can be useful for building up a list of IP’s to blacklist.

get-AntispamTopBlockedSenders.ps1

This script will provide the top 10 of email addresses that have sent you spam.

get-AntispamTopRBLProviders.ps1

This script can be used for “monitoring” the RBL provides that are configured for your environment. It will provide you an overview of the configured RBL’s and the amount of “hits” they have provided you with.

get-AntispamTopRecipients.ps1

This script will provide you with an overview of the email addresses within your organization that are prone to receiving spam.

get-setuplog.ps1

This script will “parse” the Exchangesetup.log and show it on screen in a more readable way.

Get-UCPool.ps1

This script will query Active Directory and report back on any UC Pools that might have been configured for OCS/Lync

GetDatabaseForSearchIndex.ps1

This script will return the database that is associated with a set of catalog files.

Usage:
To use the script, run a Get-Childitem of the directory containing the catalog files and pipe it through to the script.

Get-ChildItem <path> | GetDatabaseForSearchIndex.ps1

GetSearchIndexForDatabase.ps1

This script does exactly the opposite of the GetDatabaseforSearchIndex.ps1 script. It will provide you the path to the catalog files for the database you provided with the script.

Note: to use this script add the database name after the script. E.g.: GetSearchIndexForDatabase.ps1 “Mailbox Database”

Import-RetentionTags.ps1

This script will import Retention Tags that have previously been exported with the Export-Retentiontags.ps1 script.

install-AntispamAgents.ps1

This script will install and enable the following Anti-Spam agents on a Hub Transport Server:

Connection filtering
Content filtering
Sender ID
Sender filtering
Recipient filtering
Sender reputation

Note: after running the script the Microsoft Exchange Transport services needs to be restarted.
For more information: http://technet.microsoft.com/en-us/library/bb201691.aspx

LargeToken-IIS_EWS.ps1

This script was released with Exchange 2010 SP1 RU4 in order to solve the following issue:
http://support.microsoft.com/kb/2491354

Note: This script requires PowerShell v2. It uses Remote Registry Service & WS-Management on E2K10 CAS Servers.

LargeToken-Kerberos.ps1

This script was also released with Exchange 2010 SP1 RU4 in order to solve the following issue:
http://support.microsoft.com/kb/2491354

The script will change the value for the MaxTokenSize registry key.

More information: http://support.microsoft.com/kb/327825 & http://support.microsoft.com/kb/263693

MailboxDatabaseReseedUsingSpares.ps1

This script is used for reference only. Executing the script will fail as a referenced library is missing. This library is actually used within Microsoft but is not available for the public.

Note: A big thanks to Tonino for helping me out with this one.

ManageScheduledTask.ps1

This script allows to add/modify/remove scheduled tasks through PowerShell.

The following parameters are accepted:

Install

DeleteExisting

ServerName

TaskName

PsScriptPath

PsScriptArgs

Uninstall

Disabled

Enable

TestExistence

RunFromSetup

Usage:
To create a new scheduled task that will run a custom script called “custom.ps1”, run the following cmdlet:

ManageScheduledTask.ps1 –Install –ServerName <servername> –PsScriptPath .\custom.ps1 –TaskName “Custom Script”

MigrateUMCustomPrompts.ps1

This script is used to migrate a copy of the UM custom prompts in Exchange 2007 (UM) to Exchange 2010 (UM). Custom prompts are audio files used in the Exchange UM Role that contain customized welcome-messages and –announcements.

More information: http://technet.microsoft.com/en-us/library/gg309147.aspx

Move-TransportDatabase.ps1

This script will move the Transport Database (mail.que) and log files to a new location. Next to moving the files, the script takes also care of stopping/starting the necessary services and it will create the target folder (including permissions) if it does not exist yet.

Usage:

Move-TransportDatabase –queueDatabasePath <path> –queueDatabaseLoggingPath <path>

MoveAllReplicas.ps1

When you are migrating Public Folders (e.g. when transitioning from Exchange 2003 to Exchange 2007 or 2010) all replicas must be moved off the legacy environment before you can decommission it.

Although you could perform this action manually as well, the script will allow you to easily perform the action of moving all existing replicas to the (new) server that you define.

Usage:

Moveallreplicas.ps1 –server<sourceserver> -newserver<destinationserver>

MoveMailbox.ps1

By default, Exchange 2010 performs mailbox moves asynchronously. However; in some cases an Administrator might require moves to be executed synchronously. In that case ,this script can be used.

Usage:
The script accepts pretty much the same parameters used with the New-MoveRequest cmdlet

.\MoveMailbox.ps1 –Identity <id> –TargetDatabase <targetdb>

More information: http://technet.microsoft.com/en-us/library/dd876878.aspx

new-TestCasConnectivityUser.ps1

In order to use some of the end-to-end diagnostic cmdlet in Exchange 2010, you need to create a test-user that can be used to execute the cmdlets.

A good example where this is needed, if when you deploy System Center Operations Manager. The cmdlets executed by SCOM to check the Exchange’s health require, the test user to be present.

Usage:

.\New-TestCasConnectivityUser.ps1

More information: http://technet.microsoft.com/en-us/library/dd638082.aspx

Prepare-MoveRequest.ps1

Before you can run the New-MoveRequest to move mailboxes across forests, a mail use needs to exist in the target forest. This script will create a mail user in the target forest (based on the user in the source forest) and will also copy the AD attributes from the source object to the target object.

More information: http://technet.microsoft.com/en-us/library/ee861103.aspx

RedistributeActiveDatabases.ps1

A Database Availability Group is an active environment in which database can (and will) be moved from one mailbox server to another for various reasons:

Maintenance
Failure
Corruption
…

Over time, databases could be active on servers other than the ones that you had foreseen initially. This script will allow you to “rebalance” your active databases on servers participating in your DAG, based on the db’s activation preference.

More information: http://technet.microsoft.com/en-us/library/dd335158.aspx

Reenable-AuditLoggingAgent.ps1

When upgrading to Exchange 2010 SP1, in Exchange 2010 RTM, running “Setup.com /prepareAD” the Admin Audit Log Agent gets disabled. It will not be running until the installation is completed. Run this script to fix this issue. The script will roll back the msExchangeVersion of the Agent.

Note: the issue goes away automatically once SP1 is completely installed.

Usage:

.\Reenable-AuditLoggingAgent.ps1

ReinstallDefaultTransportAgents.ps1

This script will reinstall the default Transport Agents for a Hub Transport or Edge Server. It can for instance be used to recover from an issue with transport agents.

Usage:

.\ReinstallDefaultTransportAgents.ps1

Note: the MS Exchange Transport services needs to be restarted after running this cmdlet.

RemoveReplicaFromPFRecursive.ps1

The script will remove a server from the replication list of a Public Folder and it’s subfolders. If the server isn’t listed, nothing is changed as well as when the server holds the only replica.

More information: http://technet.microsoft.com/en-us/library/aa997966.aspx

RemoveUserFromPFRecursive.ps1

This script removes a user from the client permissions list for a public folder and from all the folders beneath it in the hierarchy.

More information: http://technet.microsoft.com/en-us/library/aa997966.aspx

ReplaceReplicaOnPFRecursive.ps1

This script will replace a server listed as a replica by a new server for all public folders and the folders beneath it in the hierarchy. If the server to replace isn’t listed, nothing will be changed for that particular folder.

More information: http://technet.microsoft.com/en-us/library/aa997966.aspx

ReplaceUserPermissionOnPFRecursive.ps1

This script replace permissions of a user in the permission list for a public folder and the folders beneath it in the hierarchy with new permissions. If no permissions for the user can be found, nothing will be changed on that particular folder.

More information: http://technet.microsoft.com/en-us/library/aa997966.aspx

ReplaceUserWithUserOnPFRecursive.ps1

This script replaces a user with another user in the permissions list for a public folder or the folders beneath it in the hierarchy. If no permission entries can be found, nothing will be changed. Note that existing permissions will not be removed.

More information: http://technet.microsoft.com/en-us/library/aa997966.aspx

Reset-AntispamUpdates.ps1

This script resets baseline antispam data to original out-of-box state

Usage:

.\Reset-AntiSpamUpdates.ps1

ResetAttachmentFilterEntry.ps1

This script is used to reset the list of attachment-types that are blocked by the attachment-filtering feature, to the factory set defaults. It will do this by first removing the existing entries and then adding the default ones. If needed additional filenames or extensions can be added to the script.

Usage:

ResetAttachmentFilterEntry.ps1

ResetCasService.ps1

This script will reset and recreate the virtual directory for the service that you define.

Usage:

.\ResetCasService.ps1 <service> “<identity>”

for example:

.\ResetCasServices.ps1 owavirtualdirectory “owa (default web site)”

ResetSearchIndex.ps1

This script will remove the Search Index Catalog associated with the specified Mailbox Database.

Usage:

.\ResetSearchIndex.ps1 <databasename>

Note: optionally the –force parameter can be passed to the script as well. If –force is used, the script will not prompt for confirmation when deleting the Catalog directory.

ResumeMailboxDatabaseCopy.ps1

This script will resume activation and log file replication (copy and replay) for the specified mailbox database.

The script accepts the following parameters:

Datacenter
MailboxServer
Database

Usage:

.\ResumeMailboxDatabaseCopy.ps1 –database <dbname>

RollAlternateServiceAccountPassword.ps1

In a setup where Kerberos Authentication is used for MAPI client connectivity, a so-called Alternative Service Account (ASA) is used. You can use this script to generate a new password for the service account and propagate it to the Client Access Servers.

More information: http://technet.microsoft.com/en-us/library/ff808311.aspx

StartDagServerMaintenance.ps1

Whenever you need to do some patching on a server that is part of a DAG, there are some actions that you need to take to make sure that the node you are working on is temporarily disregarded by the DAG:

Move active databases to another DAG member
Pause the node in the cluster
Block the Database Copy Auto Activation on the mailbox server
Block replication and replay activities for each database hosted by the server
Optionally move cluster core resources to another server in the DAG

Instead of manually performing the tasks above, the StartDagServerMaintenance.ps1 script will perform all of the steps automatically.

The script is used together with the –Servername parameter which defines what server to put in ‘maintenance mode’.

Usage:

StartDagServerMaintenance.ps1 –ServerName <servername>

More information: http://technet.microsoft.com/en-us/library/dd298065.aspx

StopDagServerMaintenance.ps1

This script will reverse the action performed by the StartDagServerMaintenance.ps1 script.

More specifically, it will perform the following actions:

Run the Resume-MailboxDatabaseCopy cmdlet for each database copy hosted by the server
Resume the node in the cluster
Re-enable Database Copy Auto Activation (sets the DatabaseCopyAutoActivationPolicy to Unrestricted)

This script is also run with the –Servername parameter.

Usage:

StopDagServerMaintenance.ps1 –ServerName <servername>

More information: http://technet.microsoft.com/en-us/library/dd298065.aspx

StoreTSConstants.ps1

This file/script stores the default settings used by the Troubleshoot-DatabaseLatency.ps1 script.

More information: http://technet.microsoft.com/en-us/library/ff798271.aspx

StoreTSLibrary.ps1

A collection of Store Troubleshooter functions for use by other scripts like:

Troubleshoot-DatabaseLatency.ps1
Troubleshoot-DatabaseSpace.ps1

Troubleshoot-CI.ps1

This script monitors (and performs) troubleshooting on the Content Index catalogs. It detects and resolves the following issues:

Deadlocks
Corruption
Stalls
Backlog

This troubleshooter can be used against the server or just a database, and can be used to detect as well as resolve problems. It can also be used in just a monitoring context to log warnings and failure events in the app log.

For an usage example, check out on of my earlier blog posts: http://www.pro-exchange.be/blogs/exchange2010/archive/2011/11/21/troubleshooting-a-mailbox-database-copy-in-failedandsuspended-state.aspx

More information: http://blogs.technet.com/b/exchange/archive/2011/01/18/3411844.aspx

Troubleshoot-DatabaseLatency.ps1

This script is used by System Center Operations Manager (SCOM) to detect (and correct) latency issues on a database. Alternatively you can also create a scheduled task to run this script at predefined times.

The scripts executes the following tasks:

Checks whether database latencies are above the latency threshold of 70ms.
Checks whether the disk's transfers-per-second rate is less than the DiskReadRateThreshold performance counter and whether the disk's seconds-per-transfer rate is greater than the DiskReadLatencyThreshold performance counter. If this is the case, the script determines that the disk must be replaced because it's under low-load conditions but is exhibiting high latencies.
Checks whether a single user is using more than one thread over the last 10 minute period for longer than the value specified by the TimeInServerThreshold parameter. If this is the case, the user is likely contributing to the high latencies, and, as a result, the user's mailbox is quarantined. The user's mailbox is quarantined for six hours, during which the user won't have access to e-mail.

More information: http://technet.microsoft.com/en-us/library/ff798271.aspx

Troubleshoot-DatabaseSpace.ps1

Just as the Troubleshoot-DatabaseLatency.ps1-script, this script is used by SCOM 2007 to detect and correct any abnormal growth of either log files or database file (.edb). Alternatively, you can schedule a task to execute this script at predefined intervals.

The script executes the following tasks:

Keeps track of log generation rate for the highest log generators per database.
Keeps track of the available disk space for both the database and the log files.
Keeps track of the log generation rate. If it appears that the disk is going to run out of space within the value specified by the HourThreshold parameter (based on the log generation rate), further action must be taken.
If all of the preceding conditions are fulfilled, the script determines the list of top 25 users who accessed the database during the last one-hour period. The script then quarantines the top high-usage mailboxes for which the sum of the log generation rate is greater than the difference between the current generation rate and the sustainable generation rate that would allow tiding over the configurable time threshold. These users are quarantined for six hours, during which they won't have access to e-mail.
If the troubleshooter is unsuccessful at dropping the log generation rate to below the threshold level, it will write out events that translate into health model alerts. At this point, the script removes the database from provisioning by running the Set-MailboxDatabase cmdlet with the ExcludeFromProvisioning parameter set to $true against the specified database. You may need to move mailboxes to a new server to rebalance space.
If the troubleshooter quarantines more than 10 users, this indicates a systemic issue, which you need to follow up on. The health model will trigger an urgent alert from this condition.

More information: http://technet.microsoft.com/en-us/library/ff477617.aspx

uninstall-AntispamAgents.ps1

This script will reverse the actions performed by the Install-AntiSpamAgents.ps1 script and uninstall the Exchange Anti Spam Agents from the Hub Transport Server.

Note: the Microsoft Exchange Transport Service needs to be restarted after running this script. To verify that the transport agents have been uninstalled successfully, you can run the Get-TransportAgent cmdlet. Otherwise, you can also make sure that the Anti-spam tab is removed from the Exchange Management Console.

Using Exchange Web Services (EWS) to add entries in a calendar

Michael Van Horenbeeck — Sat, 12 Nov 2011 17:17:00 GMT

Introduction

A while back, I was at a customer that was looking for a way to add calendar items to all his user’s calendars.
Calendars can easily be manipulated using Exchange Web Services. The script I created, is built upon a script I’ve downloaded a while back from Mike Pfeiffer. For instance, his script uses parameters to provide details for the entries to create in the calendars. Also, his script uses AutoDiscover to retrieve the EWS-url. However; since this wasn’t a requirement for the customer, I omitted both AutoDiscover as the input through parameters in my script.

A word on the managed API

Before ‘diving’ a bit deeper, I just have to point out that I’m not a developer. So please – bear with me – if I don’t always use the 100% correct terminology

The managed API is an object model that you can use to develop applications (and scripts) that make use of the Exchange Web Services (EWS). It is significantly easier than the legacy way of interacting with Exchange like e.g. WebDAV.

In November 2011, Microsoft introduced version 1.2 of the API. However, at time of writing version 1.1 is the latest version available for download.

The following link provides an overview of all the features included in the API and the differences between the latest version (1.2) and earlier versions:

http://msdn.microsoft.com/en-us/library/dd633678(v=exchg.80).aspx

Building the solution

Before starting: if you need more information on how to use the Managed API, MSDN offers a ton of information on this topic. Have a look at the following URL and start from there: Microsoft Exchange Web Services Managed API 1.2

If you want your PowerShell script to use the Managed API, we need to make the API available to PowerShell (and thus the script) by importing it:

Add-Type -Path "C:\Program Files\Microsoft\Exchange\Web Services\1.1\Microsoft.Exchange.WebServices.dll"

Next, we need to create an instance of Exchange WebService .NET object:

$service = New-Object Microsoft.Exchange.WebServices.Data.ExchangeService -ArgumentList ([Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2007_SP1)

Note: in the cmdlet, you also need to specify the version of Exchange you are connecting to. Obviously in this example, I was connecting to a server running Exchange 2007 SP1.

After we’ve created the instance, we need to connect to Exchange. This can be done various ways (for instance using AutoDiscover), but in this example, we’ll provide the web-services URL directly:

$service.Url = [system.URI] "https://servername.domain.local/ews/exchange.asmx"

Now that we’ve connected to Exchange through the specified URL, it’s time to add some functionality to the script. Because I want the script to be re-usable, I needed a way of providing info to the script. You could use parameters, but because you might want to add multiple items at once, using a CSV-file seemed the best option to me. So, I had to import the csv-file:

$calendaritems = import-csv "calendaritems.csv"

In this script, the customer was looking for a way to add simple “informational” calendar items (such as public holidays from different countries), therefore I kept the amount of info provided through the csv-file as simple as possible. The content of the csv-file looks like this:

Subject,Body,Start,End,AllDayEvent
Event1,”This is event 1”,01/01/2011,01/01/2011,True
Event2,”This is event 2”,”Wednesday, November 02, 2011 1:00:00 PM”,”Wednesday, November 02, 2011 2:00:00 PM”,False

As you can see from the input above, there are different way in which you can define the contents. You can keep the start- and end date simple (useful for all-day events), but you could also add a more complex time-notation for events that take up a certain amount of time.

Now that we have the contents to add to the calendar(s), we now need to know to what calendar(s) to add them to. If you have to target all your users you could add the following:

$users = Get-Mailbox

But because I wanted to have full control (without having to built another query) over who gets the new calendar items, I again make use of a csv-file. The CSV is – again – extremely simple: I only need the user’s SMTP Address (PrimartySMTPAddress):

$users = import-csv “users.csv”

Next, we’re going to loop through the array $users (the list of all users that need to get the content of the “calendaritems.csv”-file) and add the items to their calendar. To loop through the array we use the following cmdlet:

foreach($user in $users){
}

Before we can add an item to a user’s calendar, the account that is used to run this script needs to impersonate the user. That’s why we need the Primary SMTP Address for the user. This also means that we have to give that account “Application Impersonation” rights. Check out the following URL for more information: http://msdn.microsoft.com/en-us/library/bb204095%28v=exchg.140%29.aspx

$service.ImpersonatedUserId = New-Object Microsoft.Exchange.WebServices.Data.ImpersonatedUserId -ArgumentList([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress,$user.PrimarySMTPAddress)

Note that $user.PrimarySMTPAddress refers to the value in the users.csv file.

Now that we’ve set that straight, we need to build the entries and save them to the user’s calendar:

foreach($item in $calendaritems){
            $appointment = New-Object Microsoft.Exchange.WebServices.Data.Appointment -ArgumentList $service
            $appointment.Subject = $item.Subject
            $appointment.Body = $item.Body
            $appointment.Start = $item.Start
            $appointment.End = $item.End
            $appointment.LegacyFreeBusyStatus = "Free"
            if($item.AllDayEvent = "true"){
            $appointment.IsAllDayEvent = $true
            }
         else{
            $appointment.IsAllDayEvent = $false
        }

            $appointment.Save([Microsoft.Exchange.WebServices.Data.SendInvitationsMode]::SendToAllAndSaveCopy)
        }

Taking a look at the code above, there are some things we need to explain:

We start by creating a new instance of a calendar object using:

$appointment = New-Object Microsoft.Exchange.WebServices.Data.Appointment -ArgumentList $service

Then we define the entry’s Subject, Body, Start- & End-date, all have been defined through the calendaritems.csv file.

$appointment.Subject = $item.Subject
$appointment.Body = $item.Body
$appointment.Start = $item.Start
$appointment.End = $item.End

Hard-coded in the script, we define the Free/Busy status as “Free” because the entry added to the user’s calendar is a pure informational entry.

$appointment.LegacyFreeBusyStatus = "Free"

Next, we sett the “IsAllDayEvent”-flag, based on the value we’ve entered in the calendaritems.csv file:

if($item.AllDayEvent = "true"){
$appointment.IsAllDayEvent = $true
}
else{
$appointment.IsAllDayEvent = $false
}

In the end, we save the appointment to the calendar:

$appointment.Save([Microsoft.Exchange.WebServices.Data.SendInvitationsMode]::SendToAllAndSaveCopy)

That’s it. Easy, wasn’t it?

Bringing it all together

If we bring all the pieces together, the script finally ends up looking like this:

Add-Type -Path "C:\Program Files\Microsoft\Exchange\Web Services\1.1\Microsoft.Exchange.WebServices.dll"

$service = New-Object Microsoft.Exchange.WebServices.Data.ExchangeService -ArgumentList ([Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2007_SP1)
$service.Url = [system.URI] https://servername.domain.local/ews/exchange.asmx

$calendaritems = Import-CSV "calendaritems.csv"
$users = import-csv “users.csv”

foreach($user in $users){
    $service.ImpersonatedUserId = New-Object Microsoft.Exchange.WebServices.Data.ImpersonatedUserId –ArgumentList ([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress,$user.PrimarySMTPAddress)

    foreach($item in $calendaritems){
        $appointment = New-Object Microsoft.Exchange.WebServices.Data.Appointment -ArgumentList $service
        $appointment.Subject = $item.Subject
        $appointment.Body = $item.Body
        $appointment.Start = $item.Start
        $appointment.End = $item.End
        $appointment.LegacyFreeBusyStatus = "Free"

        if($item.AllDayEvent = "True"){
            $appointment.IsAllDayEvent = $true
        }
        else{
            $appointment.IsAllDayEvent = $false
        }

        $appointment.Save([Microsoft.Exchange.WebServices.Data.SendInvitationsMode]::SendToAllAndSaveCopy)
    }

}

Sources & Extra Information

If you’re looking for some great examples (and tutorials) and need some more idea’s on what you can do with EWS and PowerShell, check out the following blogs:

Exchange 2010 SP1 Installation Error “Scripting Agent Initialization failed: “file is not found…””

Michael Van Horenbeeck — Sun, 23 Oct 2011 21:34:29 GMT

Introduction

When you try to install a new Exchange Server or if make an attempt to recover a failed server, you might run into the following error:

This error occurs because the Scripting Agents CmdLetExtentionAgent is enabled but during installation the ScriptingAgentConfig.xml is not found. By default, the file is called ScriptingAgentmConfig.xml.sample (and that is also how it is copied from the installation source).

I find it very unfortunate that the installer doesn’t take into account that if the Scripting Agent is installed it should change the filename, therefore avoiding this error. However; I understand that this might not be an easy thing to do. So let me show you how you can avoid this error.

Solution(s)

The first solution:

Copy the ScriptingAgentConfig.xml from another server (or a backup) to “C:\Program Files\Microsoft\Exchange Server\V14\Bin\CmdletExtentionAgents” before running the installer. This way, the installer will find the file and will not throw an error. Just make sure that you create the folders exactly as written, because the folder path is case sensitive.:

The second solution: Disable the Scripting-Agent before you run the install/recovery and re-enable it afterwards.

Run the following cmdlet from another Exchange Server: Disable-CmdletExtensionAgent –Identity “Scripting Agent” and confirm:
(Re)Run setup:
Re-enable the scripting agent running Enable-CmdletExtensionAgent –Identity “Scripting Agent”:

Get a list of mobile devices in Exchange 2010 using PowerShell

Michael Van Horenbeeck — Tue, 27 Sep 2011 21:12:00 GMT

Introduction

Hi there! Following my previous blog post about Exchange 2010 and consumerization of mobile devices, I decided to create a little script that might help you find out what mobile devices are actually connecting to your Exchange 2010 environment.

Step-by-Step

First, I define the variables that I’m going to use.
$Date = Get-Date -uformat "%Y%m%d"
$Logfile = "C:\Logs\ActiveSync-all-$date.txt"
$Devices = @()

Secondly, I add headers to the text file. This makes handling easier when you import it into Excel.
Add-Content -path $LogFile "name,devicemodel,devicetype,useragent,lastsynctime"

Then we build a list of all mailboxes that have an ActiveSyncDevice configured (or in use) and we filter on objects that are on an Exchange 2010 server:
$Mailboxes = Get-CASMailbox -ResultSize Unlimited | Where {$_.HasActiveSyncDevicePartnership -eq $True -and $_.ExchangeVersion.ExchangeBuild.Major -ilike "14"}

Next, we loop through the result and per mailbox we’re going to query for devices using the Get-ActiveSyncDeviceStatistics cmdlet. We loop through each device to get some of the details (like the model etc):

ForEach ($mailbox in $mailboxes){
    $Devices= Get-ActiveSyncDeviceStatistics -Mailbox $mailbox.name
    $name = $mailbox.Name
    ForEach ($device in $devices) {
        $Model = $Device.DeviceModel
        $Type = $Device.DeviceType
        $LastSyncTime = $Device.LastSuccessSync
        $UserAgent = $Device.DeviceUserAgent
        Add-Content -path $Logfile "$name,$Model,$Type,$UserAgent,$LastSyncTime"
    }
}

Bringing it all together

If we bring all of the above together, we get the following result:

$Date = Get-Date -uformat "%Y%m%d"
$Logfile = "C:\Logs\ActiveSync-all-$date.txt"
$Devices = @()

Add-Content -path $LogFile "name,devicemodel,devicetype,useragent,lastsynctime"

$Mailboxes = Get-CASMailbox -ResultSize Unlimited | Where {$_.HasActiveSyncDevicePartnership -eq $True -and $_.ExchangeVersion.ExchangeBuild.Major -ilike "14"}

The output of the file will look something like this:

Michael Van Horenbeeck,Android,Android,Android/3.2-EAS-1.2,09/27/2011 05:55:59,
Michael Van Horenbeeck,Android,Android,Android/3.2-EAS-1.2,,
Michael Van Horenbeeck,htcace,htcace,Android-EAS/3.10.000.083346.405,09/27/2011 20:00:48,
Michael Van Horenbeeck,TestActiveSyncConnectivity,TestActiveSyncConnectivity,Microsoft-Server-ActiveSync/12.0+(TestExchangeConnectivity.com),09/16/2011 13:05:41,

As you can see, I’m indeed using an Android-device. If you look closely, you’ll notice that there are 2 different devices.
You’ll also notice that not all devices register their Model/Type correctly (like my Android device). Others do pop out in the logs more clearly:

User X,iPad,iPad,Apple-iPad2C2/812.1,09/27/2011 18:52:48,
User X,HTC Touch Pro,PocketPC,MSFT-PPC/5.2.5310,09/27/2011 20:07:02,
User Y,iPad,iPad,Apple-iPad1C1/803.148,09/27/2011 20:12:39,
User Y,SAMSUNG,WP,MSFT-WP/7.0.7004,09/27/2011 20:19:11,

Note: If you ever used the testexchangeconnectivity.com website to test your ActiveSync deployment, you will notice that it will show up in the logs as well.

EDIT:

Tom Vergauwen, a colleague of me just pointed out there's an easier way using:

Get-ActiveSyncDevice | Get-ActiveSyncDeviceStatistics

It requires less iterations in the script; making it a lot quicker to process (certainly in large environments).
Note: Get-ActiveSyncDevice is not available on Exchange 2007, so you'll have to stick with the first script if you want to adapt it to Exchange 2007.

Bringing the best of both worlds together, results into the following script:

$Date = Get-Date -uformat "%Y%m%d"
$file = "C:\temp\eas-devicelist-$date.csv"

new-item $file -type file -force -value "User;DeviceType;DeviceModel;DeviceID;DeviceUserAgent;LastSyncTime'n"

$devices = Get-ActiveSyncDevice | Get-ActiveSyncDeviceStatistics

ForEach($device in $devices){
   $Model = $Device.DeviceModel
   $Type = $Device.DeviceType
   $id = Device.DeviceID
   $LastSyncTime = $Device.LastSuccessSync
   $UserAgent = $Device.DeviceUserAgent

   $identity = $device.identity|out-string
   $identity = $identity.split("/")[-2]

Add-Content -Path $file "$identity;$Type;$Model;$id;$UserAgent$LastSyncTime"
}

Again: thanks Tom for pointing this out!

Examining the Message Tracking Logs using EMS

Michael Van Horenbeeck — Sun, 11 Sep 2011 17:11:05 GMT

Introduction

Recently I was asked to provide an overview of the amount of mails that flow in and out a specific mailbox during a specific timeframe. The purpose was to create some kind of ‘profile’ (baseline) out of this mailbox.
Previously, this would typically have been information that you could get from the Exchange Profile Analyzer (EPA). But the Profile Analyzer uses WebDAV to ‘tap into’ Exchange which isn’t supported in Exchange 2010 anymore making it unusable in this case.

Thus, I had to revert back to either a 3rd party tool or the message tracking logs. On top of that, the Management Console has no option to easily export information into e.g. a CSV-file…

Based on the requirements, I decided to write a script that would fetch me some information from the message tracking logs:

- Date/Time of the mails that have been sent/received
- Recipient/Sender
- Subject

In this particular case, Message Tracking Logs were kept for 7 days. Even though it was not required, I decided to create daily statistics. Last but not least, I wanted these reports to be sent out automatically so that no further ‘maintenance’ was required.

The solution

Note: I’ve masked some of the output in the screenshots because the scripts were ran in a live environment.

The EMS allows to query the message tracking logs using the Get-MessageTrackingLog cmdlet:

Get-TransportServer

In the customer’s environment, there are multiple Hub Transport servers. To make sure that I include all the servers, I either add the –server parameter and run the command for each Hub Transport server, or I do the following:

Get-TransportServer | Get-MessageTrackingLog

(The output is exactly the same, but now includes the logs from all Hub Transport servers)

Next, I wanted to filter the events that are shown. As stated above, I only need the Date/Time, Recipient or Sender and the Subject:

Get-TransportServer | Get-MessageTrackingLog | ft Sender,Recipients,TimeStamp,MessageSubject

Note: the message shown above are the system messages which count as received messages as well! (if you want to filter them out you’ll have to add a where-clause to the cmdlet):

Get-TransportServer | Get-MessageTrackingLog | Where-Object{$_.MessageSubject -ne "Your mailbox is almost full."} | ft Sender,Recipients,TimeStamp,MessageSubject

So far so good

Running the cmdlets above, will provide us with the entire message tracking logs from all the different hub transport servers. In order to get the stats for a specific mailbox, during a specific timeframe, we need to filter:

the date (we want a daily report with the sent / received messages from the day before)
the sender/recipient

To fetch results from the message tracking logs during a specific timeframe, we need to use the –start and –end parameters:

Get-TransportServer | Get-MessageTrackingLog –Start "MM/dd/yyyy hh:mm:ss" –End "MM/dd/yyyy hh:mm:ss" | ft Sender,Recipients,TimeStamp,MessageSubject

Fetching results for a specific mailbox (email) means that this mailbox can either be sender or recipient, resulting in the following cmdlets:

Get-TransportServer | Get-MessageTrackingLog –Start "MM/dd/yyyy hh:mm:ss" –End "MM/dd/yyyy hh:mm:ss" –Sender email@domain.tld | ft Sender,Recipients,TimeStamp,MessageSubject

Get-TransportServer | Get-MessageTrackingLog –Start "MM/dd/yyyy hh:mm:ss" –End "MM/dd/yyyy hh:mm:ss" –Recipients email@domain.tld | ft Sender,Recipients,TimeStamp,MessageSubject

However, because of the way messages are logged in the message tracking logs, this might cause to return a message multiple times. For instance, if a mail is sent to both internal and external recipients, a second entry in the message tracking logs can be found for the external recipients only. This is by design the way the Exchange store handles messages. If we want to avoid that, we need to specify the EventID’s and Sources as well:

Get-TransportServer | Get-MessageTrackingLog -Recipients email@domain.tld -EventId DELIVER -Start "mm/dd/yyyy 0:00:00" -End "mm/dd/yyyy 23:59:59" | where{$_.Source -eq "STOREDRIVER"}

Get-TransportServer | Get-MessageTrackingLog –Sender email@domain.tld -Start "mm/dd/yyyy 0:00:00" -End "mm/dd/yyy 23:59:59" -EventID RECEIVE

Bringing it all together

If we bring all the parts from above together, we’ll finally end up with the following code below. Note the way we handle the date & time to make sure that it’s in the correct format. This is because the script will be run using a scheduled task and I want it to automatically “calculate” the date of the day before, based on the systems’ time and date at the moment the script is ran:

#defining the variables
$servers = Get-TransportServer
$email = "email@domail.tld"
$total_received = @()
$total_sent = @()

$getdate = '{0:MM/dd/yyyy}' –f (get-date).addDays(-1)
$filedate= '{0:ddMMyyyy}' –f (get-date).addDays(-1)

foreach($server in $servers){

#fetching the received messages
$in = Get-MessageTrackingLog -Server $server -Recipients $email -EventId DELIVER -Start "$getdate 0:00:00" -End "$getdate 23:59:59" | where{$_.Source -eq "STOREDRIVER"}

   foreach ($i in $in){
      $received = New-Object PSobject
      $received | Add-Member -type NoteProperty -name Sender -value $i.sender
      $received | Add-Member -type NoteProperty -name Subject -value $i.messagesubject
      $received | Add-Member -type NoteProperty -name Time -value $i.timestamp
      $total_received += $received
   }

#fetching the sent messages
$out = Get-MessageTrackingLog -server $server –sender $email -Start "$getdate 0:00:00" -End "$getdate 23:59:59" -EventID RECEIVE

   #add a extra loop to detect whether the fetched results (recipients) are an array or not. If it’s an array, join to a string (needed because of output format)
   foreach($o in $out){
         if($o.recipients -is [system.array]){
        $recip = [string]::join(";",$o.recipients)
     }
     $sent = New-Object PSObject
     $sent | Add-Member -type NoteProperty -name Recipients -value $recip
     $sent | Add-Member -type NoteProperty -name Subject -value $o.messagesubject
     $sent | Add-Member -type NoteProperty -name Time -value $o.timestamp
     $total_sent += $sent

   }

}

#results are exported to a csv-file on the local hdd. This way we have a file that we can re-use later.
$total_received | Export-CSV c:\mailstats\received_$filedate.csv -notypeinformation
$total_sent | Export-CSV c:\mailstats\sent_$filedate.csv –notypeinformation

#the code below is used to mail the files we’ve created before
$smtpServer = "servername.domain.tld"
$msg = new-object Net.Mail.MailMessage
$smtp = new-object Net.Mail.SmtpClient($smtpServer)
$msg.From = "mailstats@domail.tld"
$msg.To.Add("recipient@domain.com")
$msg.Subject = "FYI: Exchange Mailbox Statistics for $email"
$msg.Body = "Daily Mail Stats for $email"

$att_sent = New-Object Net.Mail.Attachment("c:\mailstats\sent_$filedate.csv")
$att_received = New-Object Net.Mail.Attachment("c:\mailstats\received_$filedate.csv")
$msg.Attachments.Add($att_sent)
$msg.Attachments.Add($att_received)

$smtp.Send($msg)

Conclusion

Although there is no GUI which will allow you to save data from the message tracking logs, fetching data through the EMS is pretty straightforward and not that hard at all. You can – if needed – customize the script to include multiple mailboxes and file-handling (e.g.: exporting to html).

Cheers!

Michael

Using the Scripting Agent to automate some basic “housekeeping” tasks

Michael Van Horenbeeck — Wed, 31 Aug 2011 10:28:06 GMT

Introduction

Recently, Koen published an article about applying “housekeeping” retention policies to end-users.

Somewhere in the article, there was a specific line that drew my attention:

“… The policy will need to be applied to future mailboxes as well. Obviously I can request the service desk to update their user/mailbox creation procedures. However as an exchange admin I prefer to keep control. In other words we need something that we can run over and over again…”

One way of making sure that the policy is applied to every new mailbox, is to instruct the helpdesk/service desk to run a script every time a new user is created. However, this is still a manual intervention which leaves room for (human) error. I wanted to go a step further, and make sure that the policy is applied every time a new mailbox is created.

CMDlet extension agents

CMDlet extension agents are components in Exchange Server 2010 that are called whenever a cmdlet runs. They – literally – extend the functionality of an existing cmdlet and are available on any Exchange Server Role but the Edge Transport Server.
Only native Exchange 2010 cmdlets can ‘call’ these extension agents. This means that you cannot – directly – call upon these agents using a script you’ve written yourself. However; if your script contains a native Exchange 2010 cmdlet (e.g. New-Mailbox), that cmdlet will still be calling the cmdlet extension agent.

Exchange 2010 includes several built-in agents but I’m not going into detail about the different agents. Nonetheless, for a detailed overview, take a look here: http://technet.microsoft.com/en-us/library/dd335067.aspx

For this article, it is the scripting agent in particular that I’m interested in.

Scripting Agent

The scripting agent is a cmdlet extension agent that allows you to ‘add’ some of your own scripting during execution of an Exchange 2010 cmdlet. The scripting agent includes some API’s that an Exchange 2010 cmdlet can call whenever a script is configured to be run. In short: it allows you to run your own code: before, during or after an Exchange 2010 cmdlet is run.

If you’d like to have more information on the Scripting Agent, take a look here: http://technet.microsoft.com/en-us/library/dd297951.aspx

But instead of trying to explain everything into detail, let’s just use an example and everything will become clear.

Building on Koen’s example, I would like to achieve the following:

apply a retention policy named “Retention Policy 1” to new user mailboxes
exclude VIP-mailboxes and assign them a retention policy “Retention Policy VIP”

And of course, lazy admin as I am, I want these task to be executed automatically – without any user intervention.

Based on the requirements above, I could create a simple script like this:

$policy = “Retention Policy 1”
$policy_vip = “Retention Policy VIP”

$mbx = get-mailbox | where{!$_.RetentionPolicy}
foreach($mb in $mbx){
   # we assume that all VIP-users have a mailbox in the database “VIP”
   if($mb.database –eq “VIP”){
      Set-Mailbox –RetentionPolicy $policy_vip
   }
   else{
      Set-Mailbox –RetentionPolicy $policy
   }
}

Although this script can automatically assign a retention policy whenever it is run, someone still has to run it manually after a new user has been created. And that’s exactly what I’m trying to avoid

Building the solution

Let’s see what happens when we put the Scripting Agent into action.

In the directory: “.\Program Files\Microsoft\Exchange Server\v14\Bin\CmdletExtensionAgents”, you will find a file called ScriptingAgentConfig.xml.sample. This file contains some samples on what you could do with the scripting agent:

Either rename the file to ScriptingAgentConfig.xml and alter it or create a new ScriptingAgentConfig.xml-file. I – personally – prefer creating a new (blank) file.

Copy-Paste the code below in the file:

<?xml version="1.0" encoding="utf-8" ?>
<Configuration version="1.0">
<Feature Name="MailboxProvisioning" Cmdlets="New-Mailbox">
<ApiCall Name="OnComplete">
If($succeeded) {
    $Name= $provisioningHandler.UserSpecifiedParameters["Name"]
    $retpolicy = "Retention Policy 1"
    $policy_vip = "Retention Policy VIP"
    if($provisioningHandler.UserSpecifiedParameters["RetentionPolicy"] -eq $null){
         if((get-mailbox $Name).database.name -eq "VIP"){
                Set-Mailbox -Identity $Name -RetentionPolicy $policy_vip
         }
         else{
             Set-Mailbox -Identity $Name -RetentionPolicy $retpolicy
         }
    }
}
</ApiCall>
</Feature>
</Configuration>

As you can see, we are using the onComplete-API which will make our code run after the new-mailbox cmdlet has been completed.

Let’s break down the script, and see what each part does:

if($succeeded): will validate that the cmdlet ‘new-mailbox’ ran successfully
$Name = $provisioningHandler.UserSpecifiedParameters["Name"]: assigns the value of the name-parameter that was provided with the new-mailbox cmdlet to the variable “$Name”
if($provisioningHandler.UserSpecifiedParameters["RetentionPolicy"] -eq $null): we check whether a retention policy was already provided with the new-mailbox cmdlet. If so; no action will be taken.
if((get-mailbox $Name).database.name -eq "VIP"): if the user’s mailbox is created in the VIP-database, assign “Retention Policy VIP”. Else, assign “Retention Policy 1”

After saving the file, we need to enable the Scripting Agent using the following cmdlet:

Enable-CmdletExtentionAgent “Scripting Agent”

You can verify it’s status running the following cmdlet:

Get-CmdletExtentionAgent “Scripting Agent” | fl Name,Enabled

Let’s create a mailbox and see what happens:

New-Mailbox –Name RetPol1 –Password (CovertTo-Securestring “P@ssw0rd” –AsPlainText –Force) –UserPrincipalName "RetPol1@domain.tld”

Now query for the user’s Retention Policy:

Magic! Even without specifying a Retention Policy, the user got the one I specified before assigned!

Now, let see what happens if we create the user in the VIP database:

This time the user got a different retention policy: “Retention Policy VIP”.

And what happens if we provide a retention policy with the new-mailbox cmdlet?

Exactly, the script will not change the retention policy (even though we created the user in the VIP database).

Conclusion

As you see, scripting agents are not that difficult to implement and offer you a wide range of possibilities in automating certain tasks.

Obviously, you could already provide a retention policy when executing the new-mailbox cmdlet using the –RetentionPolicy parameter. But that would still require you to enter that every single time, which leaves room for human error.

Extra Resources

By coincidence, not so long ago, another colleague (Michel de Rooij) also published an article about using CMDlet extension agents to automatically create an archive in a specific database whenever a new mailbox is created. I definitely recommend reading it through!

http://eightwone.com/2011/08/24/automatic-archive-provisioning-with-cmdlet-extension-agents/

If you want to get to know more about the Scripting Agent, take a look at the following TechNet article:

http://technet.microsoft.com/en-us/library/dd297951.aspx

Integrating AD RMS with Exchange 2010 (part 3)

Michael Van Horenbeeck — Sun, 28 Aug 2011 20:25:06 GMT

Introduction

In the first part of this article, we talked about what AD RMS was and how to setup a small test-environment. In the second part, I showed how to integrate RMS with Exchange 2010 and how you could/should create and deploy rights policy templates to your users.

Today, I’ll show you how to protect a new mail message using Outlook 2010 or OWA and I will also be talking about the more automated ways of integrating RMS templates: Outlook- & Transport protection Rules.

Outlook- & Transport Protection Rules

If we would use the environment that we created during the past two parts of this article, creating rights-protected content would entirely be up to the user. This would mean that if the user did not apply a RMS template on an outgoing message, the message could still leave the organization without being protected, possibly leaving sensible information unprotected.

There are cases in which you might want content always to be protected (e.g. email coming from the financial department). Outlook- & Transport Protection rules enable you to create “rules” that will automatically apply a RMS template, without any user intervention. The main difference between both is that an Outlook Protection Rule will encrypt the message when it leaves the user’s computer (before hitting the hub transport servers) whereas a Transport Protection Rule will apply a RMS template while the message is in transit (on the hub transport servers). In the latter case, the user will have no idea whether the message will be encrypted or not. Outlook Protection Rules allows the user to see that the message was encrypted and – if configured – also allows the user to modify the template used to encrypt the message.

If you want to use Outlook Protection Rules, you also have to make sure that the template that is defined in the rule also is available on the client’s computer. For more information on how to achieve that, please take a look at my previous article.

Whenever a message is protected with an Outlook Protection Rule, it is encrypted and therefor – normally – not readable to a hub transport server. This would definitely limit processing options during transport (e.g. for message compliancy). Fortunately, Exchange 2010 allows you to enable “transport decryption”. The decryption agent will decrypt the message upon reception, allowing other agents to also process the message (e.g. append a disclaimer etc.). Once processing is complete, the hub transport server will re-encrypt the message with the same AD RMS template that was used to encrypt it in the first place, before sending it out onto the internet.

For more information about transport decryption and –agents, have a look here: http://technet.microsoft.com/en-us/library/dd638126.aspx and http://technet.microsoft.com/en-us/library/bb125012.aspx

Creating Outlook Protection Rules

Creating an Outlook Protection Rule is pretty straightforward, however you can only do this using the Exchange Management Shell (EMS):

New-OutlookProtectionRule –Name <name> –ApplyRightsProtectionTemplate <name_of_the_rms_template>

In the example above, I first queried for all availably RMS templates using the Get-RMSTemplate cmdlet. I then used the “Do Not Print” template to create an Outlook Protection Rule that would apply to all email messages.

If you want to limit the scope of the Outlook Protection Rule, you would use either the –SentTo or –SentToScope parameters:

Notice that I added the –SendToScope “inOrganization” parameter. This will make sure that the Outlook Protection Rule is only applied to messages sent internally.

Note: I replaced the name of the RMS template by the TemplateGUID. This because I created a duplicate RMS-template called “Do Not Forward and wanted to be sure the correct one was selected.

For more information on the New-OutlookProtectionRule and it’s parameters, please check: http://technet.microsoft.com/en-us/library/dd298182.aspx

Creating Transport Protection Rules

Transport protection rules are “no more” than regular transport rules which we use to apply an AD RMS Template to a message. Creating transport rules can either be done through the EMC or the EMS.
In order to alternate between EMS and EMC, I will show you how to perform this task using the EMC. However, if you want to use the EMS, take a look here: http://technet.microsoft.com/en-us/library/bb125138.aspx

Open the EMC and navigate to “Organization Configuration” > “Hub Transport”; select the “Transport Rules”-tab from the result pane and click “New Transport Rule” from the actions pane.

This will launch the “New Transport Rule”-wizard.

Enter descriptive details and click Next:

Select an appropriate condition that meets your requirement and click Next. In this example I chose to create a condition based on the membership of a Distribution Group “HR”:

Select “Rights Protect Message with RMS Template” and click the underlined text “RMS Template”:

Select the desired RMS Template and confirm:

Click Next.

Add an exception (if required) and click Next:

Click Next again and then click New.

Creating a rights-protected document with Outlook

Besides the automatic application of RMS templates (through Outlook- or Transport Protection Rules), a user can still decide to apply a RMS template to a message himself.

Open a new mail message and navigate to the options-tab. From there, click the arrow under “Permission”:

Select an available template to apply it to the message.

Creating a rights-protected document with OWA

From within OWA, open a new mail message and click the arrow next to the permissions-icon. Select an available template to apply it to the message.

Conclusion

Throughout the past few articles, we created a simple RMS infrastructure and integrated it with Exchange 2010. We deployed some RMS templates and distributed them to a Windows 7 machine.
Afterwards we’ve also taken a look at the more automated ways of integrating RMS through protection rules.

I hope that you feel a bit more confident with regards to RMS/IRM now and if if you have any questions, please don’t hesitate to comment or to contact me directly.

See you next time!

Michael

Applying “housekeeping” retention policies to the end users

Koen Vermoesen — Fri, 26 Aug 2011 12:40:00 GMT

In my previous blog post I wrote about a basic retention policy for doing some basic housekeeping using Exchange 2010 retention policies. The last sentence of that post post reads:

All there’s is left to do is applying the policy to the remainder of the user base, but don’t forget to skip the CEO’s mailbox ;-)

Right now you’re probably thinking “Get-Mailbox | Set-Mailbox” does the trick. Obviously it does the trick; but I’ve got a couple more requirements.

The retention policy needs to be set on about 2500. If you’re like me that you rather spend halve a day writing a script than using that time to make the changes in the GUI. (+ I wouldn’t have something to blog about.)

I’ve got that CEO mailbox to exclude. I could of course easily exclude a single mailbox. Let’s make it a bit more future proof and ensure the scripts can deal with multiple exclusions.

It’s also a good idea to filter mailboxes out which already have a retention policy set. The policy will need to be applied to future mailboxes as well. Obviously I can request the service desk to update their user/mailbox creation procedures. However as an exchange admin I prefer to keep control. In other words we need something that we can run over and over again.

Lets go over the different sections of the script:

First of all we start with defining the list of excluded mailboxes. I chose to use a lengthy way of doing so. This way I could add sufficient comments to ensure it’s really clear which VIPs we’re dealing with (as there is no logical connection between the alias and the user).

# Defining the mbx to be excluded from the retention policy
# You can add to the list as needed
# However make sure you use the alias, not SamAccountName!
$Exceptions = @() # Define array
$Exceptions += "ABC123" # Casper
$Exceptions += "DEF456" # Melchior
$Exceptions += "GHI789" # Balthazar

After Some more variable definitions, we convert the exclusion list form an array of strings to an array of mailbox object (needed later on in the script). Afterwards we print a list on screen showing the list of excluded mailbox.

# Set more variables
$RetPol = "Remove old deleted items and calendar entries"
$TableCols = "Alias","DisplayName","RetentionPolicy"

# Display Exclusions
Clear-Host
Write-Host "Retention Policies will NOT be changed for:" -ForegroundColor Red
$Exceptions = $Exceptions | Get-Mailbox # Convert array of strings to array of mbx objects
$Exceptions | ft $TableCols

The next section does a query for mailboxes for which not Retention Policy has been set yet.

# Exclude mbx which already have the retention policy set
Write-Host "`nBuilding the list of mailboxes without a Retention Policy set" -ForegroundColor Green
$MBX = @() # Define array
$MBX += $(Get-Mailbox -ResultSize Unlimited | where {!$_.RetentionPolicy}) # Exclude mailboxes which have already a retention policy set
$MBX | ft $TableCols
Write-Host "`nPlease check if these counts seem realistic to you." -ForegroundColor Green
Write-Host "# of mbx on the exclusion list:" $Exceptions.Count
Write-Host "# of mbx without retention policy:" $MBX.Count

We compare the array of mbxs without retention policy with the exception list. We converted the exception list earlier on to be able to compare of objects of the same type. The delta is the list of mailboxes we need to update. The PassThru-parameter is need to ensure our command returns mailbox objects because the Compare-Object command returns “difference objects” by default. The SideIndicator property on the other hand excludes results that are in $Exceptions but not $MBX, which can happen if you do some creative testing.

# Exclude mbx on the exclusion list
$MBX2Set = @() # Define array
$MBX2Set += $(Compare-Object $MBX $Exceptions -PassThru | ? { $_.SideIndicator -eq "<="})
$MBX2Set | ft $TableCols

Last but not least we need to actually set the Retention Policies for the remaining mailboxes.

#Setting RetentionPolicy
Write-Host "`nSetting retention policy" -ForegroundColor Green
if ($MBX2Set) {
    Write-Host "# of mbx to set retention policy for:" $MBX2Set.Count
    $MBX2Set | Set-Mailbox -RetentionPolicy $RetPol
    } else {
    Write-Host "No mailboxes to set!" -ForegroundColor Yellow
}

Screenshots of scripts don’t always offer a lot of added value, especially if they read “nothing to change” but at least one can admire the colors ;-)

Script: check what version of Exchange 2010 you are running

Michael Van Horenbeeck — Tue, 09 Aug 2011 10:37:00 GMT

I've noticed that quite some search phrases in Google were about how to determine what version or build of Exchange (2010) you're running. That is why, a while back, I decided to make a little script which does that for you. I updated the syntax a bit (more compact) and added new Exchange version numbers.

At the moment, the script is limited to Exchange 2010, but you could easily modify it to include support for earlier versions of Exchange as well.

Note that I'm not a scripting-guru and that the script's function is limited to Exchange 2010 only. For more information, you can always contact me directly. Feedback is always welcome!

To run the script, you just have to run "Get-ExchangeVersion" once you've loaded into your profile. To do so, you can dot-script this script by typing ". .\scriptname.ps1" from EMS.

Here's the code:

<#
Michael Van Horenbeeck
Version-checker for Exchange 2010
v1.0 28/02/2011

Updates
v1.1 17/07/2011 - Added new builds to the $versionArray
v1.2 09/09/2011 - Added UR4 v2 to the $versionArray

Additional Information
This script is designed to only work with Exchange Server 2010.
If you want to add support for earlier versions of exchange there are some things that need to be done:
   - add version info to $versionArray
   - lookup version info from exsetup.exe in different location (based on what version you're running)

The script needs to be run with enough rights in order to use administrative shares and lookup file version info
Additionally, the exchange server should be reachable from the computer you are using to run the script.
#>

function Get-ExchangeVersion{
    #define variables
    $var = @()
    $info = @()
    $obj=@()
    $servers = Get-ExchangeServer
    $i=0
    #additional settings
    Set-ADServerSettings -ViewEntireForest $true
    #List of Version numbers
    #format:("Name","buildnr")
    $versionArray = ("Exchange Server 2010 RTM","14.00.0639.021"),
                    ("Exchange Server 2010 Update Rollup 1","14.00.0682.001"),
                    ("Exchange Server 2010 Update Rollup 2","14.00.0689.000"),
                    ("Exchange Server 2010 Update Rollup 3","14.00.0694.000"),
                    ("Exchange Server 2010 Update Rollup 4","14.00.0702.001"),
                    ("Exchange Server 2010 Update Rollup 5","14.00.0726.000"),
                    ("Exchange Server 2010 SP1 RTM","14.01.0218.015"),
                    ("Exchange Server 2010 SP1 Update Rollup 1","14.01.0255.002"),
                    ("Exchange Server 2010 SP1 Update Rollup 2","14.01.0270.001"),
                    ("Exchange Server 2010 SP1 Update Rollup 3","14.01.0289.003"),
                    ("Exchange Server 2010 SP1 Update Rollup 3 v3","14.01.0289.007"),
                    ("Exchange Server 2010 SP1 Update Rollup 4","14.01.0323.001"),
                    ("Exchange Server 2010 SP1 Update Rollup 4 v2","14.01.0323.006")


    #Welcome message
    Write-Host ""
    Write-Host ""
    Write-Host "Exchange 2010 Version Checker v1.2"
    Write-Host "----------------------------------"
    Write-Host "The script is determining what versions of Exchange 2010 you are running. Please wait..."
    Write-Host ""

    #run trhough the array of exchange servers to determine build
    foreach ($server in $servers){

        $var+= Get-ExchangeServer $server
        $role = $var[$i].ServerRole

        #The script uses the default installation directory + administrative share. If one (or both) has changed (e.g. no administrative share available or you installed in another directory)
        #please, update the variable $fileinfo with the correct information
        $fileinfo = Get-Command "\\$server\c$\program files\microsoft\exchange server\v14\bin\exsetup.exe" | %{$_.fileversioninfo}

        $version = $fileinfo.FileVersion
        $major = $fileinfo.FileMajorPart

        for($n=0;$n -lt $versionArray.count; $n++){
            if($version -eq $versionArray[$n][1]){
               $obj = New-Object PSObject
               $obj | Add-Member -type NoteProperty -name Name -value $server
               $obj | Add-Member -type NoteProperty -name Roles -value $role
               $obj | Add-Member -type NoteProperty -name VersionName -value $versionArray[$n][0]
               $info += $obj
            }
        }

        $i++
        $n=0
    }

    Write-Output $info | ft -autosize

    Write-Host ""
    Write-Host ""
}

If you are interested in a more complete (and complex) script, which gives you a nice overview of your entire Exchange organization, please take a look at:

http://www.stevieg.org/2011/07/exchange-environment-report-1-5-2-released/

If you want to get to know more about powershell, visit:

http://technet.microsoft.com/en-us/scriptcenter/dd742419

Generating Exchange 2010 Certificates (Exchange Management Shell)

Johan Delimon — Fri, 23 Oct 2009 17:15:11 GMT

As you probably know, Exchange 2007 certificate management was done in powershell. Luckily we have some tools available to help us with the creation of these Powershell Commandlets to generate certificates.

Exchange 2010 not only allows you to manage certificates via Powershell but also via the GUI
See the following article for Certificates via the GUI
http://www.pro-exchange.be/blogs/exchange2010/archive/2009/05/04/finally-managing-exchange-certificates-using-the-gui.aspx

This article discusses the differences in Powershell Certificate Creation Exchange 2007 vs Exchange 2010

Digicert has a great tool for generating the powershell script required to generate a Certificate
https://www.digicert.com/easy-csr/exchange2007.htm

Let’s create a certificate in Exchange 2010 Exchange Management Shell

A positional parameter cannot be found that accepts argument '-Path'.
+ CategoryInfo : InvalidArgument: (:) [New-ExchangeCertificate], ParameterBindingException
+ FullyQualifiedErrorId : PositionalParameterNotFound,New-ExchangeCertificate

The Powershell command fails! What is happening?

Well, the parameters for New-ExchangeCertificate have changed. The “-Path” parameter has been removed from the parameter list.
Check the Technet page : New-ExchangeCertificate (Exchange 2010 Help)
http://technet.microsoft.com/en-us/library/aa998327(EXCHG.140).aspx

Now Digicert has a new Exchange 2010 CSR Command Wizard
https://www.digicert.com/easy-csr/exchange2010.htm

Let’s run this new Command in the Exchange 2010 Command Shell

That works fine but we have no file that is created. Now we could copy & paste the certificate information from the prompt into a text file and hope that formatting is OK.
The Exchange 2010 New-Certificate help on Technet explains that we have to do this in two steps. First a certificate must be created (like the screenshot) and then this information must be saved into a file.

So Let’s do this:

First we need to create the Certificate and save the information into a variable ($Data in this case)
$Data = New-ExchangeCertificate -GenerateRequest -KeySize 2048 -SubjectName "c=BE, s=Brussels, l=Brussels, o=Johan Delimon, ou=Pro-Exchange, cn=www.pro-exchange.be" -DomainName www.pro-exchange.be, mail.pro-exchange.be, autodiscover.pro-exchange.be -PrivateKeyExportable $True

Then we must save this content to a file:
Set-Content -path "c:\www_pro-exchange_be.req" -Value $Data

The same result can be accomplished from a single command like this:
Set-Content -path "c:\www_pro-exchange_be.req" -Value (New-ExchangeCertificate -GenerateRequest -KeySize 2048 -SubjectName "c=BE, s=Brussels, l=Brussels, o=Johan Delimon, ou=Pro-Exchange, cn=www.pro-exchange.be" -DomainName www.pro-exchange.be, mail.pro-exchange.be, autodiscover.pro-exchange.be -PrivateKeyExportable $True)

Importing Certificates is quite similar and has also a two step approach

Check the Technet page : Import-ExchangeCertificate (Exchange 2010 Help)
http://technet.microsoft.com/en-us/library/bb124424(EXCHG.140).aspx

Import-ExchangeCertificate -FileData ([Byte[]]$(Get-Content -Path c:\www_pro-exchange_be.cer -Encoding byte -ReadCount 0))