Upgrade Custom LDAP Filters to OPATH Filters

  • Article

 

Applies to: Exchange Server 2010 SP3, Exchange Server 2010 SP2

In Microsoft Exchange Server 2003 and earlier versions, LDAP filtering syntax is used to create custom address lists, global address lists (GALs), e-mail address policies, and distribution groups. In Exchange Server 2010 and Exchange Server 2007, the OPATH filtering syntax replaces the LDAP filtering syntax. Using the OPATH filtering syntax allows you to create filters directly in Exchange Management Shell commands by using the -RecipientFilter parameter.

Note

LDAP syntax filters are supported in Exchange 2010 and will exist only on objects that have been migrated from Exchange 2003 or earlier versions. If you want to edit the LDAP filter from an Exchange 2010 server, you must upgrade these LDAP filters to the OPATH syntax. For example, if you have Exchange 2003 servers in your organization, you can manage the LDAP syntax filter from an Exchange 2003 server. However, you can't manage or create LDAP syntax filters in Exchange 2010.

For information about how you can use a script to convert your LDAP filters to the OPATH syntax, see the Exchange Server Team blog article Need help converting your LDAP filters to OPATH?

Note

The content of each blog and its URL are subject to change without notice. The content within each blog is provided "AS IS" with no warranties, and confers no rights. Use of included script samples or code is subject to the terms specified in the Microsoft Terms of Use.

Important

In Exchange 2003, you can create custom Active Directory extension attributes. However, in Exchange 2010, you can't use custom extension attributes as a filterable property. If your organization has custom extension attributes, we recommend that you use the 15 custom attributes provided by Exchange 2010 for each recipient. However, if the custom attributes don't meet the needs of your organization, we recommend that you don't upgrade objects that use custom extension attributes.

For more information about creating filters in recipient commands, see Creating Filters in Recipient Commands.

Contents

Determining Which Objects Require Upgrading

Upgrading Default Objects

Upgrading Custom Objects

Determining Which Objects Require Upgrading

Before you upgrade the Exchange objects, you must first determine which objects require upgrading. There are two types of filters that you may need to upgrade:

  • Default objects   Default objects are the default e-mail address policies and address lists created when Exchange is installed.

  • Custom objects   Custom objects are custom LDAP filters created by an Exchange administrator in Exchange 2003 or an earlier version.

To determine which objects require upgrading, you can use the Exchange Management Console or the Exchange Management Shell.

Using the Exchange Management Console

To use the Exchange Management Console to determine which objects require upgrading, you must edit the object by using the Edit wizard for that object.

For example, if you want to determine whether an e-mail address policy has been upgraded, you select the e-mail address policy from the result pane, and then in the action pane, click Edit to open the Edit E-Mail Address Policy wizard.

If the e-mail address policy was created in Exchange 2003 and the filtering syntax hasn't yet been upgraded to OPATH, an error is displayed. This error signifies that the filtering syntax of the e-mail address policy was created in Exchange 2003 or an earlier version and may require upgrading. For information about how to upgrade the filtering syntax, see "Upgrading Default Objects" and "Upgrading Custom Objects" later in this topic.

Using the Exchange Management Shell

To use the Exchange Management Shell to determine which objects require upgrading, you can use the associated Get- cmdlet and format the list to view the recipient filters and the version of Exchange.

This example determines which e-mail address policies require upgrading.

Get-EmailAddressPolicy | Format-List Name, *RecipientFilter*, ExchangeVersion

After you run this command, the following information is displayed in the Exchange Management Shell.

In this example, two e-mail address policies were returned by the Get-EmailAddressPolicy cmdlet. Default Policy, which is highlighted in blue, is an Exchange 2003 object that requires upgrading. Resource Mailboxes, which is highlighted in red, was either created in Exchange 2010 or has already been upgraded.

If you can answer "Yes" to any of the following questions, the object hasn't been upgraded:

  • Is the RecipientFilter attribute empty?

  • Does the value of the RecipientFilterType attribute equal "Legacy"?

  • Does the value of the ExchangeVersion attribute equal "0.0 (6.5.6200.0)"?

Return to top

Upgrading Default Objects

When you install Exchange 2003, a default e-mail address policy and multiple default address lists are created. The following list includes the default objects that will need to be upgraded if the filter must be changed in Exchange 2010, or if you need to administer the object in Exchange 2010:

  • E-mail Address Policies: Default Policy

  • Address Lists: All Contacts, All Groups, All Rooms, All Users, Default Global Address List, Public Folders

Because default objects have known filters, you can easily upgrade these default objects. For detailed instructions about how to upgrade default objects, see the following topics:

Note

The -ForceUpgrade parameter doesn't construct the replacement recipient filter for the object, nor does it upgrade the object. The -ForceUpgrade parameter suppresses the confirmation question so that you can upgrade by using an unattended script.

Return to top

Upgrading Custom Objects

Upgrading custom objects is more difficult because it requires you to determine what the custom LDAP filter is filtering for, and then translate the filter into OPATH syntax. Custom LDAP filters can be created for the following Exchange objects:

  • Address lists

  • E-mail address policies

  • Dynamic distribution groups

There are two methods you can use to upgrade custom objects:

  • Use a script provided by the Microsoft Exchange Team. For information about this script, see the Exchange Server Team blog article Need help converting your LDAP filters to OPATH?

    Note

    The content of each blog and its URL are subject to change without notice. The content within each blog is provided "AS IS" with no warranties, and confers no rights. Use of included script samples or code is subject to the terms specified in the Microsoft Terms of Use.

  • Manually upgrade the LDAP filter to OPATH as described in the following sections.

Step 1: Determine What the Custom LDAP Filter Does

To upgrade an Exchange 2003 LDAP filter to the OPATH syntax, you must first determine what the LDAP filter is filtering. Perform the following steps:

  1. Copy an existing filter into a text editing application, such as Notepad.

    Important

    Before you begin, document your existing LDAP filter.

    This example is an LDAP filter for an e-mail address policy.

    (&(&(|(&(&(objectCategory=user)(msExchangeHomeServerName=/o=ORG/ou=SITE/cn=Configuration/cn=Servers/cn*)))(&(|(objectCategory=group)(objectCategory=msExchangeDynamicDistributionList))(displayName=IT*)))))

  2. In Notepad, indent the lines of the filter to see the logical flow.

  3. Write a statement that explains what the filter does. In this example, the e-mail address policy's filter includes the following objects:

    • All user category objects that have a home server in a particular administrative group

    • All groups or dynamic distribution lists that begin with a specific display name

Step 2: Translate the LDAP Filter into OPATH Syntax

After you determine the function of the LDAP filter, you must translate the LDAP filter into the OPATH syntax.

Note

The names for many properties have changed. For example, the LDAP property mailNickname is called Alias in Exchange 2010. To view a complete list of the property names, see Filterable Properties for the -RecipientFilter Parameter.

  1. Create the recipient filter based on the statements you recorded in Step 3 of the section "Determine What the Custom LDAP Filter Does" earlier in this topic.

    (ServerLegacyDN -like "/o=ORG/ou=SITE/cn=Configuration/cn=Servers/cn=*")
 ((RecipientType -eq "<group recipient type>" -or RecipientType -eq "DynamicDL") -and (DisplayName -like "IT"))

  2. Construct the command by using the appropriate Set cmdlet, and then run the command in the Exchange Management Shell.

    Set-EmailAddressPolicy eap1 -RecipientFilter {(ServerLegacyDN -like "/o=ORG/ou=SITE/cn=Configuration/cn=Servers/cn=*") -and ((RecipientType -eq "<group recipient type>" -or RecipientType -eq "DynamicDL") -and (DisplayName -like "IT"))}

Note

Many of the properties for the -RecipientFilter parameter accept wildcard characters. If you use a wildcard character, don't use the -eq operator. Instead, use the -like operator. The -like operator is used to find pattern matches in strings, whereas the -eq operator is used to find an exact match.

Return to top

 © 2010 Microsoft Corporation. All rights reserved.