Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

Creating Filters in Recipient Commands

Applies to: Exchange Server 2010

Topic Last Modified: 2009-12-08

You can use several Exchange Management Shell commands 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 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. For more information, see Understanding Custom Attributes.

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

Contents

Filtering Results

Filtering Attributes Within a Command

Creating Custom Filters

Predefined Filter Example

Custom Filter Example

Additional OPATH Syntax Information

You can 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, which you can use to 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 doesn't 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 Filterable Properties for the -Filter Parameter.

Bb124268.note(en-us,EXCHG.140).gifNote:
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 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.

Return to top

You can specify which attributes a 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, so that you can use precanned filters to determine the set of users to which the command applies. These cmdlets also have the RecipientFilter parameter, so that you can 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 Filterable Properties for the -RecipientFilter Parameter.

Return to top

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 Shell uses OPATH for the filtering syntax. OPATH is a querying language designed to query object data sources.

Bb124268.note(en-us,EXCHG.140).gifNote:
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 (EMC) or use the 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 Shell with the RecipientFilter parameter.

Return to top

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 an 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?
    Bb124268.note(en-us,EXCHG.140).gifNote:
    Selecting the organizational unit from which you want to include recipients applies only to creating dynamic distribution groups, and 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?

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.

Bb124268.note(en-us,EXCHG.140).gifNote:
The OrganizationalUnit parameter specifies the location for the new dynamic distribution group after it's 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.

This example creates the same dynamic distribution group using the Shell.

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

This example displays the properties of this new distribution group.

Get-DynamicDistributionGroup -Identity ContosoFinance | Format-List *Recipient*,Included*

The RecipientFilter property displays the OPATH filter syntax 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.

Return to top

This example uses 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 an 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. This example creates this dynamic distribution group.

New-DynamicDistributionGroup -Name AllContosoNorth -OrganizationalUnit contoso.com/Users -RecipientFilter { ((RecipientType -eq 'UserMailbox') -and (Company -eq 'Contoso') -and (Office -eq 'North Building')) }
Bb124268.note(en-us,EXCHG.140).gifNote:
The OrganizationalUnit parameter specifies the location for the new dynamic distribution group after it's created.

Return to top

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 (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.

Return to top

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.