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 Begin

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.

Modifying Conditions or Exceptions on a Transport Rule

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:

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

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

Adding Conditions to a Transport Rule

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:

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

To assign the conditions of a transport rule to a variable and view how many conditions are in the array

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

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

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

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

To assign each condition array element to its own variable

  • Run the following commands:

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

Copy Code
$NewCondition = Get-TransportRulePredicate <Predicate Name>

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

To assign a new condition to a new variable

  • Run the following command:

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

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

To assign values to a new condition

  • Run the following command:

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

Copy Code
Set-TransportRule <Transport Rule Name> -Condition @(<Conditions>)
Note:
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.

To modify the existing transport rule

  • Run the following command:

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

Removing Conditions from a Transport Rule

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.

To remove a condition from a transport rule

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

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

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

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

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

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

Modifying the Values of an Existing Condition on a Transport Rule

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.

Modifying an Existing Single-Value Condition

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

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

To assign the conditions of a transport rule to a variable and view how many conditions are in the array

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

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

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

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

To assign a value to the WithImportance condition at array element number 2

  • Run the following command:

    Copy Code
    $ConditionArray[2].Importance = "High"
    

To modify the existing transport rule

  • Run the following command:

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

Adding Values to an Existing Multiple-Value Condition

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

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

To assign the conditions of a transport rule to a variable and view how many conditions are in the array

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

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

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

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

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

To add values to an existing condition at array element 1 of the example

  • Run the following command:

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

To modify the existing transport rule

  • Run the following command:

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

Removing Values from an Existing Multiple-Value Condition

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.

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

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

To assign the conditions of a transport rule to a variable and view how many conditions are in the array

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

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

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

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

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

To remove values from an existing condition at array element 1 of the earlier example

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

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

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

To modify the existing transport rule

  • Run the following command:

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

For More Information