Creating Filters in Recipient Commands

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, Exchange Server 2007 SP1, Exchange Server 2007 SP2, Exchange Server 2007 SP3

Several Exchange Management Shell commands allow you to filter a set of recipients. There are two types of filtering with Exchange commands: filtering results and filtering attributes within a command.

To filter results, you must use a custom filter. To filter attributes within a command, you can use either a precanned filter or a custom filter.

A precanned filter is a commonly-used Exchange 2007 filter that you can use to meet a variety of recipient-filtering criteria. For example, you can use precanned filters to:

• Determine the scope of recipients.

• Add conditional filtering based on properties such as company, department, and state or region.

• Add custom attributes for recipients.

When your filtering requirements exceed these parameters, you can define a custom filter by using OPATH filtering syntax to reference the full set of properties in the Exchange Management Shell.

Filtering Results

The first type of filtering allows you to filter the results of a command. For example, the Get-User, Get-Recipient, Get-Mailbox, Get-MailUser, Get-Contact, Get-MailContact, Get-Group, Get-DistributionGroup, and Get-DynamicDistributionGroup cmdlets all have a Filter parameter with which you can specify which users or groups to retrieve with the command. Instead of retrieving all users or groups, you can specify a set of users or groups to retrieve using a filter string. This type of filter does not modify any configuration or attributes of objects. It only modifies the set of objects that the command returns.

For more information about the filterable properties that you can use with the -Filter parameter, see the following topics:

• Filterable Properties for the -Filter Parameter in Exchange 2007 SP1 and SP2

• Filterable Properties for the -Filter Parameter in Exchange 2007 RTM

Note

Using the Filter parameter to modify the results of commands is server-side filtering. Server-side filtering submits the command and the filter to the server for processing. The Exchange Management Shell also supports client-side filtering, in which the command retrieves all the objects from the server, and then applies the filter in the local console window. To perform client-side filtering, use the Where-Object cmdlet. For more information about server-side and client-side filtering, see "How to Filter Data" in Working with Command Output.

Filtering Attributes Within a Command

The second type of filtering allows you to specify which attributes the command should use. You can use a precanned filter or you can create your own custom filter. For example, the New-DynamicDistributionGroup, Set-DynamicDistributionGroup, New-EmailAddressPolicy, Set-EmailAddressPolicy, New-AddressList, Set-AddressList, New-GlobalAddressList, and Set-GlobalAddressList cmdlets all have the IncludedRecipients, ConditionalCompany, ConditionalDepartment, and ConditionalStateOrProvince parameters, which allow you to use precanned filters to determine the set of users to which the command applies. These cmdlets also have the RecipientFilter parameter, which allows you to create your own custom filter. With either a precanned or a custom filter, you can specify the recipients to include in a dynamic distribution group, an e-mail address policy, an address list, or a global address list (GAL).

For more information about the filterable properties that you can use with the -RecipientFilter parameter, see the following topics:

• Filterable Properties for the -RecipientFilter Parameter in Exchange 2007 SP1 and SP2

• Filterable Properties for the -RecipientFilter Parameter in Exchange 2007 RTM

Creating Custom Filters

To create a custom filter for the results of a command using the Filter parameter, or to create a custom filter for the attributes within a command using the RecipientFilter parameter, you must specify a string for the filter. The Exchange Management Shell uses OPath for the filtering syntax. OPath is a querying language designed to query object data sources. With the Exchange Management Shell, you no longer need to use the complicated syntax of Lightweight Directory Access Protocol (LDAP) that you used in Microsoft Exchange Server 2003 to create filters. Instead, you can create filters using the simpler OPath syntax.

Note

To create a dynamic distribution group, an e-mail address policy, an address list, or a GAL with precanned filters, you can either use a wizard in the Exchange Management Console or use the Exchange Management Shell. To create a dynamic distribution group, e-mail address policy, address list, or GAL with a custom filter, you must use the appropriate cmdlet in the Exchange Management Shell with the RecipientFilter parameter.

Predefined Filter Example

This example describes using precanned filters to create a dynamic distribution group. The syntax in the example commands is similar but not identical to the syntax you would use to create a new e-mail address policy, address list, or GAL.

When you create a dynamic distribution group with the New Dynamic Distribution Group wizard, you must choose the following filtering information:

• From which organizational unit do you want to include recipients?

  Note

  Choosing the organizational unit from which you want to include recipients only applies to creating dynamic distribution groups, not to creating e-mail address policies, address lists, or GALs.

• What type of recipients do you want to include?

• What additional conditions do you want to include in the filter?

The following figures show the pages of the New Dynamic Distribution Group wizard on which you choose the filter information.

Figure 1   Filter Settings page of the New Dynamic Distribution Group wizard

Figure 2   To select the organizational unit, click Browse on the Filter Settings page of the New Dynamic Distribution Group wizard

Figure 3   Conditions page of the New Dynamic Distribution Group wizard

Each of these filtering options corresponds to one of the precanned filter parameters in the New-DynamicDistributionGroup or Set-DynamicDistributionGroup commands.

The first filtering option for the organizational unit corresponds to the RecipientContainer parameter in the command. The second filtering option for type of recipients corresponds to the IncludedRecipients parameter. The third filtering option for additional conditions corresponds to the ConditionalCompany, ConditionalDepartment, ConditionalStateOrProvince, and ConditionalCustomAttribute parameters.

Note

The OrganizationalUnit parameter specifies the location for the new dynamic distribution group after it is created. The RecipientContainer parameter is a filter parameter that specifies the organizational unit where recipients that will be added to the dynamic distribution group reside.

For example, in the Dynamic Distribution Group wizard, you could select recipients from the Contoso.com/Users organizational unit, select UserMailbox objects, and select the condition to include only recipients who have Department defined as Finance and Company defined as Contoso.

To create the same dynamic distribution group using the Exchange Management Shell, run the following command:

New-DynamicDistributionGroup -Name ContosoFinance -OrganizationalUnit Contoso.com/Users -RecipientContainer Contoso.com/Users -IncludedRecipients MailboxUsers -ConditionalDepartment "Finance" -ConditionalCompany "Contoso"

To view the properties of this new distribution group, run the following command:

Get-DynamicDistributionGroup -Identity ContosoFinance | format-list *Recipient*,Included*

The RecipientFilter property displays the OPath filter syntax that was used to create this group. The RecipientFilterType property is Precanned, which means the filter for this group was created using the precanned filters. The LdapRecipientFilter property is a read-only property that displays what LDAP filter you would have used in previous versions of Exchange to create this group.

Custom Filter Example

This example describes using custom filters to create a dynamic distribution group. The syntax in the example commands is similar but not identical to the syntax you would use to create a new e-mail address policy, address list, or GAL.

To create a custom filter for a dynamic distribution group, you must use the RecipientFilter parameter with the New-DynamicDistributionGroup or Set-DynamicDistributionGroup cmdlet.

For example, if you want to create a dynamic distribution group of mailbox recipients whose Company attribute is defined as Contoso and whose Office is North Building, you must use a custom filter. To create this dynamic distribution group, run the following command:

New-DynamicDistributionGroup -Name AllContosoNorth -OrganizationalUnit contoso.com/Users -RecipientFilter { ((RecipientType -eq 'UserMailbox') -and (Company -eq 'Contoso') -and (Office -eq 'North Building')) }

Note

The OrganizationalUnit parameter specifies the location for the new dynamic distribution group after it is created.

Additional OPath Syntax Information

To create your own custom filters, be aware of the following:

• Use curly braces { } around the entire OPath syntax string with the Filter or RecipientFilter parameter.

• Include the hyphen before all operators.

• The most common operations are the following:

  • -and

  • -or

  • -not

  • -eq (equals)

  • -ne (does not equal)

  • -lt (less than)

  • -gt (greater than)

  • -like (string comparison)

  • -notlike (string comparison)

• Many of the properties for the -RecipientFilter and -Filter parameters accept wildcard characters. If you use a wildcard character, use the -like operator instead of the -eq operator. The -like operator is used to find pattern matches in rich types, such as strings, whereas the -eq operator is used to find an exact match.

• Use the following commands to get information about operators that you can use:

  • Help about_logical_operator

  • Help about_comparison_operator

• You can use most properties of recipient types to create filter strings. For information about filterable properties that you can use with a specific cmdlet, see the cmdlet reference topics in Exchange 2007 Cmdlets.

For More Information

For more information about pipelining output in the Exchange Management Shell, see Pipelining.