Address List and EAP filter upgrades with Exchange Server 2007


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 there 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*" ) )

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 UpgradeDefaultFilters.txt attached below!

Evan Dodds

Comments (24)
  1. Joesph Worrall says:

    The command:

    Set-AddressList "All PublicFolders" –RecipientFilter { RecipientType –eq ‘PublicFolder’ }

    Results in the error:

    Set-AddressList : Cannot bind parameter ‘RecipientFilter’ to the target. Except

    ion setting "RecipientFilter": """ is not a valid operator. For a list of suppo

    rted operators see the command help.

    "( RecipientType -eq ‘publicfolder’ )" at position 17."

    At line:1 char:50

    + Set-AddressList "Public Folders" -RecipientFilter  <<<< {( RecipientType -eq

    ‘publicfolder’ )}

  2. Exchange says:

    Joseph, two ideas on what might be wrong (we are unable to reproduce it):

    1) Are you running RTM?

    2) Did you run the script or cut/paste the string (and maybe smart quotes?) from the post?

  3. pesos says:

    Could you guys do a writeup regarding the tcp ports used for Outlook 2007 to Exchange 2007 communication?  Something like the KB article at http://support.microsoft.com/?id=270836 but updated for 2007.  We have a hardware firewall inbetween our citrix servers (outlook 2007) and our exchange server — wondering what ports we’ll need to open and/or if ex2007 will need registry modification to hard-code ports.  We plan to use ISA 2006 to broker OWA, activesync, and Outlook Anywhere connections – should it also be used for direct, internal outlook 2007 use?

    thanks!

    Wes

  4. Jeroen says:

    when i execute: Set-EmailAddressPolicy "Default Policy" –IncludedRecipients AllRecipients

    i get this error:

    Set-EmailAddressPolicy : The recipient policy "Default Policy" with mailbox man

    ager settings cannot be managed by the current version of Exchange Management C

    onsole. Please use a management console with the same version as the object.

    At line:1 char:23

    + Set-EmailAddressPolicy  <<<< "Default Policy" -IncludedRecipients AllRecipien

    ts

    is there an other way to update the Default Policy?

    runnning on 2003 x64 with exchange 2007 RTM

  5. onovotny says:

    I get the same error as Jeroen when I try to update the Default Policy.

  6. Evan says:

    Jeroen and onovotny – this error message indicates that it’s not just a recipient policy but that you also have mailbox manager policy settings on this object. Since Mailbox Manager policies no longer exist in Exchange 2007, you need to remove the mailbox manager policy settings from this recipient policy object using Exchange 2003 before you can upgrade the policy to Exchange 2007 version (you can create another mailbox manager policy that has no email address policy settings in Exchange 2003 if you want to keep the mailbox manager settings).

  7. Rhoderick says:

    Thanks Evan, but what about the error that Joseph posted?  That one is on the PF address list.

  8. Mitchell-MTI says:

    The documentation regarding the -Forceupgrade parameter for set-emailaddresspolicy doesn’t seem to match with what is said in this post:

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

    It seems to imply that the -forceupgrade parameter is updating the version attribute, not just suppressing the warning dialog.  Also, it would be a lot clearer in the documentation for this command if it indicated that it needs to be run with the parameters to create a new recipient filter.

  9. Anonymous says:

    If you are not familiar with what OPATH is, then you must read these two blogs when you are done reading

  10. Evan says:

    Rhoderick and Mitchell – sorry for the delay, I’ve been out of this office this week on vacation.

    The error that Joseph posted I can’t seem to reproduce. The syntax in the script and in the blog post works fine when I run it. My thoughts: Is this an RTM build of the server? (some of the filterable properties changed from Beta2 -> RTM). Did you cut/paste rather than running the script or retyping it? (sometimes the cut/paste approach leads to high-ascii or unicode characters like "smartquotes" that the shell won’t like in the parser).

    Mitchell – the description of ForceUpgrade in this post is the correct one. There’s been a great deal of confusion about what this parameter does, so I’ve passed along the link you posted and we’ll get it fixed up. Please let us know if you run across other confusing descriptions of ForceUpgrade or other parameters.

    Thanks!

    Evan

  11. Anonymous says:

    I have previously listed the progress we’ve been making in posting ITPro focused Systems Management blog

  12. Richard says:

    Had the same problem as Joseph (Joesph?) did.

    I had to change "All PublicFolders" to "Public Folders", probably because I had an Exchange2000 environment.

    After that it still did not work, because of the minus characters (ASCII problem indeed!).

    Retyping it myself in PowerShell did the trick for me.

  13. Johnny says:

    I’m getting this error when trying to run Set-EmailAddressPolicy "Default Policy" –IncludedRecipients AllRecipients

    Unable to validate the filter: ‘An Exchange 2007 server on which an address list service is active cannot be found.’

    At line:1 char:1

    + S <<<< et-EmailAddressPolicy ‘Default Policy’ -IncludedRecipients AllRecipients

  14. Carl Johnson says:

    Ok .. custom address list with A/D contacts that have the mail attribute populated? When I try to create an address list with a specific recipient policy it does not work and I get an error as such:

    WARNING: The recipient "([DN])" is invalid and could not be updated.

    I would think this is possible since the contact has a email address, etc?

  15. Ronald Top says:

    Hi there,

    I try to change the GAL with set-globaladdresslist , but it returns always cannot be performed on object def. gal. Any ideas how i can change the gal filter ??

    BR,

    Ronald

  16. Evan says:

    Ronald – the GAL filter syntax provided in the post is correct for updating the GAL filter. Can you make sure you’re typing it correctly and/or use the attachment script file to do the upgrade? What’s the exact error it’s returning?

    Evan

  17. Ronald Top says:

    Hi Evan,

    Sorry for my late reply, here’s what exactly happens :

    Set-GlobalAddressList : The operation can not be done on the default global address list object, "Default Global Address List".

    At line:1 char:22

    Any ideas ? This is my last road blocker before moving to ex 2007.

    Thanks and best regards,

    Ronald Top

  18. Evan says:

    Ronald – generally this error message means it’s already been upgraded (once it’s upgraded to use the static E2k7 filter, the filter is fixed and cannot be customized). Can you do "Get-GlobalAddressList | fl" and look to see both what is the configured RecipientFilter and also what is the ExchangeVersion? No need to post them here – please go ahead and shoot me some email (evandATmicrosoft) if you’re still having trouble with it after that point.

    Thanks!

    Evan

  19. Nick Smith says:

    We’re in teh process of installing 1st Ex2007 server in our 2003 domain. Preliminary bits went fine, but then failed to install Mailbox role with: "

    Error:

    The Exchange server address list service failed to respond. This could be because of an address list or email address policy configuration error.

    Warning:

    An unexpected error has occurred and a Watson dump is being generated: The Exchange server address list service failed to respond. This could be because of an address list or email address policy configuration error. It was running command ‘$error.Clear(); $count=0; $ExchangeServers = Get-ExchangeServer -DomainController $RoleDomainController; foreach($server in $ExchangeServers) { if(($server.AdminDisplayVersion.Build -gt 641) -and ($server.IsMailboxServer -eq $true)) { $count++; } } if( $count -eq 1) { Set-OrganizationConfig -DomainController $RoleDomainController; }’.

    *************

    Only help we can find on the web is someone who said he’d deleted all his recipient policies. We’re *very* loth to do this especially as any attempt to create new policy/GAl from the Ex2007 mangement console bascially results in same error. So we *could* delete all our policies and GALs but woudl then have to recreate manually in Ex2003 which would bring us full circle.

    Any ideas?

  20. Exchange says:

    Nick,

    Well, seeing that the blog does not work very well for troubleshooting, I’d ask you to either go to our newsgroups with this or open a support case on it. It is hard to tell why this is happening in your environment.

  21. Anonymous says:

    After installing Exchange 2007 into your existing Exchange organization, the address lists and recipient…

  22. Anonymous says:

    I’ve upgraded our internal Exchange organisation over the last week and I’ve got to say Exchange 2007

  23. Anonymous says:

    Since I’ve posted a number of times about OPATH filters for Exchange 2007 and RecipientFilter parameter

Comments are closed.