OPATH recipient filtering for Exchange Server 2007

OPATH is basis for the filtering syntax used by PowerShell, and is therefore the filtering syntax used by Exchange 2007. It replaces the complicated syntax of LDAP used in Exchange 2003, and will allow for filters which are easier to create and interpret. For native PowerShell filters, all work is done client-side in the Powershell host. In Exchange 2007, however, various cmdlets provide "server-side" filters using the same syntax as their client-side counterparts. These server-side filters provide higher performance and added scenarios that are specific to Exchange Server.

This blog post will address some techniques to make use of these "added scenarios" that relate specifically to Exchange Server. For instance, we'll talk about the RecipientFilter "server-side" filter definitions used by Dynamic Distribution Groups, Email Address Policies, Address Lists, and Global Address Lists.

Note that dynamic distribution groups, email address policies, address lists, and global address lists all share approximately the same filtering behavior. They all share the same concept of "precanned" vs "custom" filters, the same filtering properties ("RecipientFilter", "IncludedRecipients", etc), and the same RecipientFilter syntax. Therefore, the examples and techniques below are equally useful for any of these other types, not just for dynamic distribution groups.

When creating dynamic distribution groups (DDGs) with Exchange 2007 Exchange Management Console GUI, you will be presented with three basic decisions used for filtering:

1. From what OrganizationalUnit scope do I want to include recipients
2. What sort of recipients do I want to include
3. Are there any additional things I want to filter on

Where:

#1 corresponds to the "RecipientContainer" property in the Exchange shell.

#2 corresponds to the "IncludedRecipients" property.

#3 corresponds to the "ConditionalCompany", "ConditionalStateOrProvince", "ConditionalDepartment", or "ConditionalCustomAttribute" properties.

After you've created a DDG through the GUI, you can also notice that the RecipientFilterType is set to "Precanned". These are the most simple sort of RecipientFilter that can be created, and are the only sort that can be created through the GUI. They take the values you've provided to IncludedRecipients, ConditionalCompany, ConditionalStateOrProvince, ConditionalDepartment, or ConditionalCustomAttribute# and automatically turn them into a RecipientFilter for you. We believe the filters available as Precanned cover the most common RecipientFilter cases used in Exchange 2003.

So, for instance in the GUI you could select to filter starting at the "Domain.com/Users" Organizational Unit, starting with all MailboxUser objects, and then filtering to include only those who have Company defined as "Microsoft". This is a very common sort of DDG and very easy to do in the GUI.

It's also very easy to do in the Exchange shell (syntax is roughly the same for New or Set):

   Set-DynamicDistributionGroup AllMicrosoft –RecipientContainer "Domain.com/Users" –IncludedRecipients MailboxUsers –ConditionalCompany "Microsoft" –OrganizationalUnit "Domain.com/Users"

Note for clarification: Although they may both look the same in this example, RecipientContainer and OrganizationalUnit are very different. RecipientContainer defines the root of the OU tree from which recipients will be included in the dynamic distribution group. OrganizationalUnit parameter defines where the new dynamic distribution group will be created in the AD. Note also that the RecipientContainer parameter is available only for dynamic distribution group, and not Email Address Policy nor Address List Recipient Filters.

After this command completes, you can inspect the results of the properties we care about with "Get-DynamicDistributionGroup AllMicrosoft | fl Recipient*,Included*":

RecipientContainer      : Users,28b69b51-a381-4f50-bf34-a5c976b64d9e
RecipientFilter   : (((RecipientType –eq 'UserMailbox') –and (Company –eq 'Microsoft')) –and –not(Name –like 'SystemMailbox{*') –and –not(Name –like 'CAS{*'))
RecipientFilterType     : Precanned
IncludedRecipients      : MailboxUsers

Note that you can also see what is the equivalent LDAP filter by inspecting the LdapRecipientFilter property. This is a read-only representation of the LDAP filter. Filters cannot be entered directly with LDAP syntax for Exchange 2007.

Now, what if you want to do something more complicated? Something that is not exposed as a filterable property in the GUI? Well, you can build a custom (ie – not precanned) RecipientFilter!

For example, let's say you want to use that exact same query we just constructed above, EXCEPT that you want it to be also based on the UMEnabled status of the mailbox. In that case, you would need a custom filter and that means you need to use the RecipientFilter property directly:

   Set-DynamicDistributionGroup AllMicrosoft –RecipientFilter { (((RecipientType –eq 'UserMailbox') –and (Company –eq 'Microsoft')) –and –not(Name –like 'SystemMailbox{*') –and –not(Name –like 'CAS{*') –and (UMEnabled –eq $true))}

In this example, you've just taken the exact syntax used by the Precanned filter, and then added one extra clause onto the end for the UMEnabled boolean. Simple!

A few more quick examples:

All mailboxes that are on the Server1 server and user in the Dallas office:

   Set-DynamicDistributionGroup AllServer1Dallas –RecipientFilter { ServerName –eq 'Server1' –and Office –eq 'Dallas' }

All recipients that are in the state of Texas and have OtherTelephone starting with 469:

   Set-DynamicDistributionGroup AllTx469 –RecipientFilter { StateOrProvince –eq 'TX' –and OtherTelephone –like '469*' }

All mailboxes that are in the state of Texas and have OtherTelephone starting with 469:

   Set-DynamicDistributionGroup AllTx469 –RecipientFilter { RecipientType –eq 'UserMailbox' –and StateOrProvince –eq 'TX' –and OtherTelephone –like '469*' }

So, what are some of the syntax basics to be aware of?

• For Precanned filters, use IncludedRecipients parameter along with the various "Conditional<whatever>" parameters to define the filter
  • IncludedRecipients parameter takes the various recipients types that can be used for precanned filters: None, MailboxUsers, Resources, MailContacts, MailGroups, MailUsers, or AllRecipients.
• For Custom filters, use "-RecipientFilter {  <some filter> }"   (yes, curly braces around the filter)
• Powershell uses "-and", "-or", and "-not" (yes, with leading hyphen)
• Some other useful comparison operators: "-eq" (equals), "-ne" (not equal), "-lt" (less than), "-gt" (greater than), "-like" and "-notlike" (wildcard string compare).
• Almost all of the properties exposed on the various recipient types are available to these custom RecipientFilters. Please let us know if you run across one that you need but cannot access!

Other references: Now that Powershell has released, there are several books available that are fairly useful as a reference. Also, the PowerShell team has a blog: http://blogs.msdn.com/powershell/.

- Evan Dodds