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, email address policies, address lists, or GALs. With precanned filters, you can use either the Exchange Management Shell or the Exchange Administration Center (EAC). 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 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 email 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 email 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.

	Copy Code
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.

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

Return to top

If precanned filters don't meet your needs for creating or modifying dynamic distribution groups, email 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 email 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.

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

Return to top

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.

	Copy Code
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-MailboxStatistics
  
  
• Get-MailContact
  
  
• Get-MailPublicFolder
  
  
• Get-MailUser
  
  
• Get-Message
  
  
• Get-MobileDevice
  
  
• Get-Queue
  
  
• Get-QueueDigest
  
  
• Get-Recipient
  
  
• Get-RemoteMailbox
  
  
• Get-RoleGroup
  
  
• Get-SecurityPrincipal
  
  
• Get-StoreUsageStatistics
  
  
• Get-ThrottlingPolicyAssociation
  
  
• Get-UMMailbox
  
  
• Get-User
  
  
• Get-UserPhoto
  
  
• 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".

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

Return to top

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.

	Copy Code
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

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.
  
  

The following table contains links to topics that will help you learn more about the filterable properties that you can use with Exchange recipient commands.

Return to top