Export (0) Print
Expand All

Creating Filters in Recipient Commands

 

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

Topic Last Modified: 2007-11-15

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.

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:

noteNote:
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.

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:

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.

noteNote:
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.

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?

    noteNote:
    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

Filter Settings page

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

Select Organizational Unit page

Figure 3   Conditions page of the New Dynamic Distribution Group wizard

Conditions page

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.

noteNote:
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.

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')) }

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

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 Management Shell.

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

 
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft