Export (0) Print
Expand All

How to Modify Transport Rule Conditions and Exceptions in the Exchange Management Shell

 

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

Topic Last Modified: 2007-03-20

This topic explains how to use the Exchange Management Shell to modify the conditions and exceptions on an existing transport rule that is configured on a computer that has the Microsoft Exchange Server 2007 Hub Transport server role or the Edge Transport server role installed.

For more information about the Transport Rules agents, see Overview of Transport Rules.

Before you perform the following procedures, see How to Modify a Transport Rule, which provides important information that is required to modify transport rule conditions and exceptions.

To perform these procedures, the account you use must be delegated the following:

  • Exchange Organization Administrator role

To perform the following procedures on a computer that has the Edge Transport server role installed, you must log on by using an account that is a member of the local Administrators group on that computer.

For more information about permissions, delegating roles, and the rights that are required to administer Exchange Server 2007, see Permission Considerations.

To perform these procedures, you must be familiar with the following concepts:

For more information about the Exchange Management Shell, see Using the Exchange Management Shell.

The procedures used to modify conditions and exceptions on transport rules are very similar because conditions and exceptions use the same underlying transport rule predicates. The procedures that are described in this topic use transport rule conditions as an example, but you can also apply these procedures to transport rule exceptions. To use the following rules to modify transport rule exceptions, change Conditions to Exceptions. Consider the following example:

  • To access the conditions on a transport rule, use the following command:

    $ConditionArray = (Get-TransportRule "Test Rule").Conditions
    
  • To access the exceptions on a transport rule, use the following command:

    $ExceptionArray = (Get-TransportRule "Test Rule").Exceptions
    

First, you must preserve the existing conditions. Assign each existing condition in the condition array to its own variable. Use the following command syntax to assign the condition array to a variable:

$ConditionArray = (Get-TransportRule "<rule name>").Conditions

  1. Run the following command to assign the condition array to a variable:

    $ConditionArray = (Get-TransportRule "Test Rule").Conditions
    
  2. Run the following command to view the number of conditions in the array:

    $ConditionArray.Length
    

Then assign each condition in the array to its own variable. The conditions are in array elements, which are numbered 0 through $Condition.Length - 1. Use the following syntax to assign each condition array element to its own variable:

$ExistingCondition<Array Element Number> = $ConditionArray[<Array Element Number>]

  • Run the following commands:

    $ExistingCondition0 = $ConditionArray[0]
    $ExistingCondition1 = $ConditionArray[1]
    

Then create the new condition or conditions. You can't use conditions that are already applied to the existing transport rule. Use the following syntax to assign a new condition to a variable:

$NewCondition = Get-TransportRulePredicate <Predicate Name>

For a list of transport rule predicates, see Transport Rule Predicates.

  • Run the following command:

    $NewCondition = Get-TransportRulePredicate SubjectContains
    

After you assign the new condition to a new variable, assign values to the condition. Use the following command to assign values to the new condition:

$NewCondition.<PredicateProperty> = <Single Value or Array of Values>

For a list of transport rule predicate properties and the expected formatting of their values, see Transport Rule Predicates.

  • Run the following command:

    $NewCondition.Words = @("Test Subject 1", "Test Subject 2")
    

After you create all the new conditions, apply all the conditions to the existing transport rule. Use the following command syntax to modify the transport rule:

Set-TransportRule <Transport Rule Name> -Condition @(<Conditions>)
noteNote:
You must order the existing and new conditions according to their Rank when you specify them in the Set-TransportRule command. Use the Get-TransportRulePredicate command to view the rank of each condition or exception.

  • Run the following command:

    Set-TransportRule "Test Rule" -Condition @($ExistingCondition0, $ExistingCondition1, $NewCondition)
    

To remove a condition from a transport rule, follow these steps from the section earlier in this topic:

  1. Assign the conditions of a transport rule to a variable and view how many conditions are in the array.

  2. Assign each condition array element to its own variable, except the condition that you want to remove.

  3. Modify the existing transport rule.

  1. Run the following command to assign the condition array to a variable:

    $ConditionArray = (Get-TransportRule "Test Rule").Conditions
    
  2. Run the following command to view the number of conditions in the array:

    $ConditionArray.Length
    
  3. Run the following command to view the conditions in the $ConditionArray variable and note the array element number of the condition that you want to remove:

    $ConditionArray
    
  4. Run the following command to assign the conditions that you want to keep to variables, omitting the array elements of the conditions that you don't want to keep:

    $ExistingCondition1 = $Condition[1]
    ...
    
  5. Run the following command to modify the transport rule, assigning only the variables that are associated with the conditions that you want to keep:

    Set-TransportRule "Test Rule" -Condition @($ExistingCondition1)
    

The procedures for modifying a condition depend on whether the condition accepts single or multiple values. Follow the procedure that applies to the type of condition that you want to modify.

To determine the type of condition that you want to modify, see Transport Rule Predicates.

First, assign the conditions of the existing transport rule to a variable and view the array. Use the following command syntax:

$ConditionArray = (Get-TransportRule "Test Rule").Conditions

  1. Run the following command to assign the condition array to a variable:

    $ConditionArray = (Get-TransportRule "Test Rule").Conditions
    
  2. Run the following command to view conditions in the array:

    $ConditionArray
    

Determine which condition you want to modify and note its array element number. See "Adding Values to an Existing Multiple-Value Condition" later in this topic to find the correct array element number.

After you determine the array element number, assign the new value to that condition by using the following command syntax:

$ConditionArray[<array element number>].<Predicate Property> = <Single Value>

  • Run the following command:

    $ConditionArray[2].Importance = "High"
    

  • Run the following command:

    Set-TransportRule "Test Rule" -Condition $ConditionArray
    
noteNote:
You don't have to insert the $ConditionArray variable in an array because $ConditionArray variable is already an array.

First, you must assign the conditions of the existing transport rule to a variable and view the array. Use the following command syntax:

$ConditionArray = (Get-TransportRule "Test Rule").Conditions

  1. Run the following command to assign the condition array to a variable:

    $ConditionArray = (Get-TransportRule "Test Rule").Conditions
    
  2. Run the following command to view conditions in the array:

    $ConditionArray
    

Determine which condition you want to modify and note its array element number. The first condition in the array is at array element 0. If the condition that you want to modify is the third condition in the list, its array element number is 2. You must then determine the predicate property or properties of the condition. The condition's predicate properties are always listed immediately before the line starting with LinkedDisplayTextException, as in the following example:

Addresses                  : {Kim Akers}
LinkedDisplayTextException : except if from <a id="Addresses">people</a>
Name                       : From
Rank                       : 0
LinkedDisplayText          : from <a id="Addresses">people</a>

Words                      : {Corporate Communication, Message from VP, Sales Quotas}
LinkedDisplayTextException : except if with <a id="Words">specific words</a> in the subject
Name                       : SubjectContains
Rank                       : 15
LinkedDisplayText          : with <a id="Words">specific words</a> in the subject

In this example, the first condition, at array element 0, has the predicate property Addresses. The second condition, at array element 1, has the predicate property Words.

To add new values to an existing condition, use the following command syntax:

$ConditionArray[<Array Element Number>].<Predicate Property> += <Array of Values>

For a list of transport rule predicate properties and the expected formatting of their values, see Transport Rule Predicates.

  • Run the following command:

    $ConditionArray[1].Words += @("Industry Projections", "Sales Forecast")
    

  • Run the following command:

    Set-TransportRule "Test Rule" -Condition $ConditionArray
    
noteNote:
You don't have to insert the $ConditionArray variable in an array because $ConditionArray variable is already an array.

To remove values from an existing condition, you must note the existing values and then re-enter the existing values into the condition, omitting the values that you no longer want. When you perform the following procedure, the existing values are replaced with the values that you specify.

noteNote:
The following procedure works well for conditions that have only a few values configured. However, for conditions that have dozens, or hundreds, of values configured, this procedure is not feasible. We recommend that you use a foreach loop when it is unreasonable to manually reassign values to a condition.
For more information, see Using the Exchange Management Shell.

First, you must assign the conditions of the existing transport rule to a variable and view the array. Use the following command syntax:

$ConditionArray = (Get-TransportRule "Test Rule").Conditions

  1. Run the following command to assign the condition array to a variable:

    $ConditionArray = (Get-TransportRule "Test Rule").Conditions
    
  2. Run the following command to view conditions in the array:

    $ConditionArray
    

Then view the values of the condition that you want to modify and replace the values of that condition with the values that you want to keep. For more information about how to determine the element number and predicate properties of a condition array, see "Adding Values to an Existing Multiple-Value Condition" earlier in this topic. Use the following command syntax:

$ConditionArray[<Array Element Number>]

Then replace the existing values of the condition that you want to modify with the values that you want to keep. Use the following command syntax:

$ConditionArray[<Array Element Number>].<Predicate Property> = <Array of Values>

For a list of transport rule predicate properties and the expected formatting of their values, see Transport Rule Predicates.

  1. Run the following command to view current values that are configured on the condition:

    $ConditionArray[1]
    
  2. Run the following command to replace the current values with the desired values:

    $ConditionArray[1].Words = @("Corporate Communication", "Sales Quotas")
    

  • Run the following command:

    Set-TransportRule "Test Rule" -Condition $ConditionArray
    
noteNote:
You don't have to insert the $ConditionArray variable in an array because the $ConditionArray variable is already an array.
 
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft