Share via

Upgrading Custom LDAP Filters to OPATH Filters

  • Article

Microsoft Exchange Server 2007 will reach end of support on April 11, 2017. To stay supported, you will need to upgrade. For more information, see Resources to help you upgrade your Office 2007 servers and clients.

 

Applies to: Exchange Server 2007 SP1, Exchange Server 2007 SP2, Exchange Server 2007 SP3

In Microsoft Exchange Server 2003 and earlier versions, Lightweight Directory Access Protocol (LDAP) filtering syntax is used to create custom address lists, global address lists (GALs), e-mail address policies, and distribution groups. In Exchange Server 2007, the new 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 2007 and will exist only on objects that have been migrated from Exchange 2003 or earlier. If you want to edit the LDAP filter from an Exchange 2007 server, you must upgrade these LDAP filters to the OPATH syntax. For example, if you have Exchange 2003 and Exchange 2007 servers in your organization, you can manage the LDAP syntax filter from an Exchange 2003 server. However, you cannot manage or create LDAP syntax filters in Exchange 2007.

For information about how you can use a script to convert your LDAP filters to the OPATH syntax, see the Microsoft Exchange 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 are subject to the terms specified in the Microsoft Terms of Use.

Important

In Exchange 2000 Server and Exchange 2003, you can create custom Active Directory extension attributes. However, in Exchange 2007, you cannot 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 2007 for each recipient. However, if the custom attributes do not meet the needs of your organization, we recommend that you do not upgrade objects that use custom extension attributes.

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

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 that are created when Exchange is installed.

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

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 has not yet been upgraded to OPATH, the following error is displayed.

E-mail Address Policy Filter Upgrade Error

This error signifies that the filtering syntax of the e-mail address policy was created in Exchange 2003 or earlier 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.

For example, to determine which e-mail address polices require upgrading, run the following command:

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

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

Information returned from the EMS

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 2007 or has already been upgraded.

If you can answer "Yes" to any of the following questions, the object has not 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)"?

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 2007, or if you need to administer the object in Exchange 2007:

  • 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 how to upgrade default objects, see the following topics:

Note

The -ForceUpgrade parameter does not 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.

Upgrading Custom Objects

Upgrading custom objects is more difficult as 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 Microsoft Exchange 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 are 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 Exchange 2007 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.

    The following is an example of 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 (as illustrated in the following figure).

    Notepad with filter

  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

In Exchange 2007, the names for many properties have changed. For example, the LDAP property "mailNickname" is called "Alias" in Exchange 2007. To view a complete list of the property names, see the following topics:

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.

  1. (ServerLegacyDN -like "/o=ORG/ou=SITE/cn=Configuration/cn=Servers/cn=*")

  2. ((RecipientType -eq "<group recipient type>" -or RecipientType -eq "DynamicDistributionGroup") -and (DisplayName -like "IT"))

  • Finally, 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 "DynamicDistributionGroup") -and (DisplayName -like "IT"))}

Note

Many of the properties for the -RecipientFilter parameter accept wildcard characters. If you use a wildcard character, do not 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.

For More Information

To learn more about the OPATH filtering syntax, see Creating Filters in Recipient Commands.