Creating Filters in Recipient Commands

 

Applies to: Exchange Server 2010 SP3, Exchange Server 2010 SP2

You can use several Exchange Management Shell commands to filter a set of recipients. You can create the following types of filters in an Exchange command:

• Precanned filters

• Custom filters using the RecipientFilter parameter

• Custom filters using the Filter parameter

• Custom filters using the ContentFilter parameter

In Microsoft Exchange Server 2003 and earlier versions, 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 and Exchange Server 2010, the OPATH filtering syntax replaces the LDAP filtering syntax. Exchange supports existing LDAP filters, but you can't edit them. Before you can change an LDAP filter, you must upgrade it to an OPATH filter. For more information, see Upgrade Custom LDAP Filters to OPATH Filters.

Contents

Precanned Filters

Custom Filters Using the RecipientFilter Parameter

Custom Filters Using the Filter Parameter

Custom Filters Using the ContentFilter Parameter

Additional OPATH Syntax Information

Precanned Filters

A precanned filter is a commonly used Exchange filter that you can use to meet a variety of recipient-filtering criteria for creating dynamic distribution groups, e-mail address policies, address lists, or GALs. With precanned filters, you can either use Exchange Management Shell or a wizard in the Exchange Management Console (EMC). Using precanned filters, you can do the following:

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

The following parameters are considered precanned filters:

• IncludedRecipients

• ConditionalCompany

• ConditionalDepartment

• ConditionalStateOrProvince

• ConditionalCustomAttribute1–15.

Precanned filters are available for the following cmdlets:

• New-DynamicDistributionGroup

• Set-DynamicDistributionGroup

• New-EmailAddressPolicy

• Set-EmailAddressPolicy

• New-AddressList

• Set-AddressList

• New-GlobalAddressList

• Set-GlobalAddressList

Example

This example describes using precanned filters in the Shell to create a dynamic distribution group. The syntax in this example is similar but not identical to the syntax you would use to create an e-mail address policy, address list, or GAL. When creating a precanned filter, you should ask the following questions:

• From which organizational unit (OU) do you want to include recipients? (This question corresponds to the RecipientContainer parameter.)

  Note

  Selecting the OU for this purpose applies only when creating dynamic distribution groups, and not when creating e-mail address policies, address lists, or GALs.

• What type of recipients do you want to include? (This question corresponds to the IncludedRecipients parameter.)

• What additional conditions do you want to include in the filter? (This question corresponds to the ConditionalCompany, ConditionalDepartment, ConditionalStateOrProvince, and ConditionalCustomAttribute parameters.)

This example creates the dynamic distribution group Contoso Finance for user mailboxes in the OU Contoso.com/Users and specifies the condition to include only recipients who have the Department attribute defined as Finance and the Company attribute defined as Contoso.

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

This example displays the properties of this new dynamic distribution group.

Get-DynamicDistributionGroup -Identity "Contoso Finance" | Format-List *Recipient*,Included*

Return to top

Custom Filters Using the RecipientFilter Parameter

If precanned filters don't meet your needs for creating or modifying dynamic distribution groups, e-mail address policies, and address lists, you can create a custom filter by using the RecipientFilter parameter.

The recipient filter parameter is available for the following cmdlets:

• New-DynamicDistributionGroup

• Set-DynamicDistributionGroup

• New-EmailAddressPolicy

• Set-EmailAddressPolicy

• New-AddressList

• Set-AddressList

• New-GlobalAddressList

• Set-GlobalAddressList

For more information about the filterable properties you can use with the RecipientFilter parameter, see Filterable Properties for the -RecipientFilter Parameter.

Example

The following example uses the RecipientFilter parameter to create a dynamic distribution group. The syntax in this example is similar but not identical to the syntax you use to create an e-mail address policy, address list, or GAL.

This example uses custom filters to create a dynamic distribution group for user mailboxes that have the Company attribute defined as Contoso and the Office attribute defined as North Building.

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

Return to top

Custom Filters Using the Filter Parameter

You can use the Filter parameter to filter the results of a command to specify which objects to retrieve. For example, instead of retrieving all users or groups, you can specify a set of users or groups by 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.

Using the Filter parameter to modify command results is known as 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 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.

To find the filterable properties for cmdlets that have the Filter parameter, you can run the Get command against an object and format the output by pipelining the Format-List parameter. Most of the returned values will be available for use in the Filter parameter. The following example returns a detailed list for the mailbox Ayla.

Get-Mailbox -Identity Ayla | Format-List

The Filter parameter is available for the following cmdlets:

• Get-ActiveSyncDevice

• Get-ActiveSyncDeviceClass

• Get-CASMailbox

• Get-Contact

• Get-DistributionGroup

• Get-DynamicDistributionGroup

• Get-Group

• Get-Mailbox

• Get-MailContact

• Get-MailPublicFolder

• Get-MailUser

• Get-Message

• Get-Queue

• Get-Recipient

• Get-RemoteMailbox

• Get-RoleGroup

• Get-SecurityPrincipal

• Get-StoreUsageStatistics

• Get-ThrottlingPolicyAssociation

• Get-UMMailbox

• Get-User

• Remove-Message

• Resume-Message

• Resume-Queue

• Retry-Queue

• Suspend-Message

• Suspend-Queue

For more information about the filterable properties you can use with the Filter parameter, see Filterable Properties for the -Filter Parameter.

Example

This example uses the Filter parameter to return information about users whose title contains the word "manager".

Get-User -Filter {Title -like '*Manager*'}

Return to top

Custom Filters Using the ContentFilter Parameter

You can use the ContentFilter parameter to select specific message content to export when using the New-MailboxExportRequest cmdlet. If the command finds a message that contains the match to the content filter, it exports the message to a .pst file.

Example

This example creates an export request that searches Ayla's mailbox for messages where the body contains the phrase "company prospectus". If that phrase is found, the command exports all messages with that phrase to a .pst file.

New-MailboxExportRequest -Mailbox Ayla -ContentFilter {Body -like "*company prospectus*"}

For more information about the filterable properties you can use with the ContentFilter parameter, see Filterable Properties for the -ContentFilter Parameter.

Return to top

Additional OPATH Syntax Information

When creating your own custom filters, be aware of the following:

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

• Include the hyphen before all operators. The most common operators include:

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

• Run the following commands to get information about operators 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 you can use with a specific cmdlet, see the cmdlet reference topics in Exchange Management Shell.

Return to top

 © 2010 Microsoft Corporation. All rights reserved.