As discussed in this earlier blog post on OPATH Filters, Exchange 2007 uses a new style of filter syntax to replace the LDAP filters of previous versions. This blog post will talk about the steps you can take to upgrade your legacy LDAP filters to the new syntax, allowing you to upgrade your Address List and Email Address Policy objects to the Exchange 2007 object version.
Note that if you decide not to upgrade the ALs or EAPs, there will be no broken functionality from the Exchange 2007 side. New users will still be provisioned according to those policies. However you will not be able to edit those objects from 2007 Exchange Management Console until they are upgraded.
There are two types of EAPs and ALs you might be looking to upgrade: The built-in, default objects (Default Policy, All Users, etc) and custom objects (MyCompany Sales Org). It's very straight-forward to do filter upgrades for the built-in, default objects since these are well known and have standard filters in place. Upgrades for custom EAP and AL objects requires a bit more work, and we'll cover that later in the blog post.
Upgrading your default Email Address Policy
There's only one default EAP in your organization. This is the EAP which is usually called "Default Policy", and it will be specifically identified by the "Priority" value of "lowest". While it's quite likely you have created other custom EAPs, this EAP is the "fall-through" EAP which will match any recipient not matched to a higher-priority policy.
Therefore, you may notice that the default policy has a very inclusive LDAP recipient filter: "(mailnickname=*)". Thus, it matches any recipient object.
So first let's talk about how to confirm you need to upgrade the filter (and the version) on your EAP. There are a couple of key indicators you can check. The first is that if you try to edit the EAP in Exchange 2007 GUI, you'll get a screen with this error - "Unable to edit the specified E-mail address policy. E-mail address policies created with legacy versions of Exchange must be upgraded using the 'Set-EmailAddressPolicy' task, with the Exchange 2007 Recipient Filter specified.":
Another way to check that doesn't rely on the GUI is to issue this one-liner:
Get-EmailAddressPolicy | Format-List Name,*RecipientFilter*,ExchangeVersion
This cmdlet will return all of your EAPs, and will include any properties containing RecipientFilter and the ExchangeVersion property. Look for these clues:
- LdapRecipientFilter is populated but RecipientFilter is empty - Exchange 2003 doesn't populate RecipientFilter; that's what we're about to do!
- RecipientFilterType is "Legacy"
- ExchangeVersion is "0.0 (6.5.6500.0)"
Matching these characteristics, you've now got a sense of which EAPs need to have their filters upgraded. Another shortcut now that we've talked about the details is that you might just run a one-liner like this to get the consolidated list:
Get-EmailAddressPolicy | where { $_.RecipientFilterType -eq "Legacy" }
Next step, how to do the upgrade on the default EAP (we'll talk about custom EAPs later in the post).
Since the "Default Policy" EAP has a well-known filter, we can simply provide the Exchange 2007 equivalent of this well-known filter to do the upgrade. Here's the one-liner:
Set-EmailAddressPolicy "Default Policy" -IncludedRecipients AllRecipients
When you run this one-liner, you'll be prompted to ask whether you REALLY want to do the upgrade with this text: "To save changes on object "Default Policy", the object must be upgraded to the current Exchange version. After the upgrade, this object cannot be managed by a previous version of Exchange System Manager. Do you want to continue to upgrade and save the object?"
Once you've committed to a "Y" answer on this confirmation, the "Default Policy" EAP will be upgraded to Exchange 2007 version with the new Exchange 2007 filter in place. You can confirm this by looking at the same properties as before. Now you'll notice that there is a RecipientFilter property populated, that the RecipientFilterType is "Precanned", and that the Exchange version has bumped to 0.1 (8.0.535.0). Further, you may notice that you can no longer make changes to the recipient policy through Exchange 2003 ESM, although the Exchange 2003 Recipient Update Service (RUS) will continue to process these recipient policies just fine.
ForceUpgrade parameter
Many have noticed that there's a "-ForceUpgrade" parameter on the Set-EmailAddressPolicy and Set-AddressList cmdlets. Note that this parameter does NOT construct the proper replacement RecipientFilter for your object or do the upgrade. This parameter simply suppresses the confirmation question discussed just above so that you can do these upgrades in a script, if needed.
This means that if you run a one-liner like: Set-EmailAddressPolicy "Default Policy" -ForceUpgrade, nothing will happen. This is because you've told it to suppress the confirmation prompt, but without a new filter provided on the one-liner, there's no upgrade and therefore no upgrade confirmation to suppress!
Upgrading your Default Address Lists
Exchange 2003 creates a number of default address lists for exposure to the client side. These are named to match what objects they contain: "All Users", "All Groups", "All Contacts", "Public Folders", and the "Default Global Address List". Exchange 2007 adds one new AL to expose just the resource mailboxes of type room: "All Rooms".
The "All Rooms" AL is already updated to Exchange 2007 filter and version, but the other five default ALs are not. Like with the default EAP example above, you can try to edit these in the GUI or you can run a simple one-liner to confirm that these ALs are in need of an upgrade:
Get-AddressList | Format-List Name,*RecipientFilter*,ExchangeVersion
Get-GlobalAddressList | Format-List Name,*RecipientFilter*,ExchangeVersion
The exact same "clues" criteria apply to legacy AddressLists:
- LdapRecipientFilter is populated but RecipientFilter is empty - Exchange 2003 doesn't populate RecipientFilter; that's what we're about to do!
- RecipientFilterType is "Legacy"
- ExchangeVersion is "0.0 (6.5.6500.0)"
So, now that you've made an inventory of your legacy ALs, let's get those default ones upgraded!
Since these five ALs have well-known filters, we can simply provide the Exchange 2007 equivalent of these well-known filters to do the upgrades. Here are the one-liners:
Set-AddressList "All Users" -IncludedRecipients MailboxUsers
Set-AddressList "All Groups" -IncludedRecipients MailGroups
Set-AddressList "All Contacts" -IncludedRecipients MailContacts
And the last two that are slightly different, since the re are not "precanned" filters for public folder recipient type:
Set-AddressList "Public Folders" -RecipientFilter { RecipientType -eq 'PublicFolder' }
Set-GlobalAddressList "Default Global Address List" -RecipientFilter {(Alias -ne $null -and (ObjectClass -eq 'user' -or ObjectClass -eq 'contact' -or ObjectClass -eq 'msExchSystemMailbox' -or ObjectClass -eq 'msExchDynamicDistributionList' -or ObjectClass -eq 'group' -or ObjectClass -eq 'publicFolder'))}
When you run these one-liners, you'll be prompted to ask whether you REALLY want to do the upgrade with this text: "To save changes on object "<whichever one you're upgrading>", the object must be upgraded to the current Exchange version. After the upgrade, this object cannot be managed by a previous version of Exchange System Manager. Do you want to continue to upgrade and save the object?"
Once you've committed to a "Y" answer on this confirmation, the Address List will be upgraded to Exchange 2007 version with the new Exchange 2007 filter in place. You can confirm this by looking at the same properties as before. Now you'll notice that there is a RecipientFilter property populated, that the RecipientFilterType is "Precanned", and that the Exchange version has bumped to 0.1 (8.0.535.0). Further, you may notice that you can no longer make changes to address list through Exchange 2003 ESM, although the Exchange 2003 Recipient Update Service (RUS) will continue to process these recipient policies just fine.
ForceUpgrade parameter
Many have noticed that there's a "-ForceUpgrade" parameter on the Set-EmailAddressPolicy and Set-AddressList cmdlets. Note that this parameter does NOT construct the proper replacement RecipientFilter for your object or do the upgrade. This parameter simply suppresses the confirmation question discussed just above so that you can do these upgrades in a script, if needed.
This means that if you run a one-liner like: Set-AddressList "All Users" -ForceUpgrade, nothing will happen. This is because you've told it to suppress the confirmation prompt, but without a new filter provided on the one-liner, there's no upgrade and therefore no upgrade confirmation to suppress!
Custom Email Address Policy and Address List filters
But what if you've created some special EAP or AL objects for your organization, over and above the built-in set of EAP and AL objects? How can you convert the "not-so-well-known" LDAP filter you have created into an equivalent OPATH filter for use by PowerShell?
The process I've covered earlier in my blog (http://blogs.technet.com/evand/archive/2006/09/14/456310.aspx), but I'm going to revisit it here so that it's available together with the default objects above.
The key part of this exercise has two parts: 1) figure out what the filter is actually filtering, followed by 2) reconstruct the filter with PowerShell syntax as OPATH and set it on the object.
So here's a sample "custom filter" you might have built:
(&(&(|(&(&(objectCategory=user)(msExchHomeServerName=/o=ORG/ou=SITE/cn=Configuration/cn=Servers/cn=*)))(&(|(objectCategory=group)(objectCategory=msExchDynamicDistributionList))(displayname=IT*)))))
On to step 1 - figuring out what this actually filters!
There are a couple things you can do at this stage to help yourself out. You can copy and paste this filter into a "search" action in LDP (subtree, starting at the root) and see what it returns. At a high-level, this will at least help you to know what sort of things you're looking for in your OPATH translation (you can tell if you're way off after you've finished).
The more practical way of doing this is to paste it into notepad and break it out into indented lines so you can see the logical flow:
(&
(&
(|
(&
(&
(objectCategory=user)(msExchHomeServerName=/o=ORG/ou=SITE/cn=Configuration/cn=Servers/cn=*)
)
)
(&
(|
(objectCategory=group)(objectCategory=msExchDynamicDistributionList)
)
(displayname=IT*)
)
)
)
)
Alright, that seems fairly easy... give or take.
Translated to English, it looks something like this:
- All user-category objects that have home server in a particular admin group (this would only be mailbox objects in that AG)
- AND
- All (Groups OR Dynamic Distribution Groups) that start with a particular displayname wildcard
Great! So that's a start. Now we at least know what we should expect to find if we do issue the LDAP search in LDP!
Next, on to part two... translating the logical filter we've just determined into OPATH syntax:
First, let's diagram it loosely like above. Then we can go into the actual cmdlet syntax...
- (ServerLegacyDN -like "/o=ORG/ou=SITE/cn=Configuration/cn=Servers/cn=*")
- -and
- ( (RecipientType -eq "<one of several group recipient-types>" -or RecipientType -eq "DynamicDL")
- -and
- ( DisplayName - like "IT*" ) )
- ( (RecipientType -eq "<one of several group recipient-types>" -or RecipientType -eq "DynamicDL")
Not so bad, really. You're just swapping some filtering keywords and the LDAP style of syntax for the OPATH style.
Since you're upgrading your existing EAP (or Address List), now you're ready to use the appropriate Set cmdlet to save this change to your object.
This will be a "custom filter" created from the shell, since it doesn't fall under the "precanned" filter options. This means you will create it using the "RecipientFilter" parameter and you'd end up with a long, but manageable, one-liner something like this:
Set-EmailAddressPolicy eap1 -RecipientFilter { (ServerLegacyDN -like "/o=ORG/ou=SITE/cn=Configuration/cn=Servers/cn=*" ) -or ( ( RecipientType -eq "MailEnabledUniversalDistributionGroup" -or RecipientType -eq "MailEnabledUniversalSecurityGroup" -or RecipientType -eq "MailEnabledNonUniversalGroup" -or RecipientType -eq "DynamicDL") -and ( DisplayName -like "IT*" ) ) }
There are nearly infinite possible "custom" filters you may have created and need to upgrade, so we can't cover all of them in a blog post. I have created a wiki page over at http://www.exchangeninjas.com/ to host any such filters you've converted and wish to share. See the page at: http://www.exchangeninjas.com/EAPAndALFilterUpgrades
Also, this page will be a great place to post your LDAP filters (be sure to strip out anything sensitive from the filters before posting!) and ask if anyone else has already done the work of converting a similar filter and might be able to help.
NOTE: a sample script that you can use to upgrade your default policy as well as your default ALs is attached. Please see the UpgradeDe faultFilters.txt attached below!