Share via


How to Modify Transport Rule Actions in the Exchange Management Shell

Microsoft Exchange Server 2007 will reach end of support on April 11, 2017. To stay supported, you will need to upgrade. For more information, see Resources to help you upgrade your Office 2007 servers and clients.

 

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

This topic explains how to use the Exchange Management Shell to modify the actions 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 actions.

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 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 the Actions on a Transport Rule

Adding Actions to a Transport Rule

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

$ActionArray = (Get-TransportRule "<rule name>").Actions

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

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

    $ActionArray = (Get-TransportRule "Test Rule").Actions
    
  2. Run the following command to view the number of actions in the array:

    $ActionArray.Length
    

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

$ExistingAction<Array Element Number> = $ActionArray[<Array Element Number>]

To assign each action array element to its own variable

  • Run the following commands:

    $ExistingAction0 = $ActionArray[0]
    $ExistingAction1 = $ActionArray[1]
    

Then create the new action or actions. You cannot use the actions that are already applied to the existing transport rule. Use the following syntax to assign a new action to a variable:

$NewAction = Get-TransportRuleAction <Action Name>

For a list of transport rule actions, see Transport Rule Actions.

To assign a new action to a new variable

  • Run the following command:

    $NewAction = Get-TransportRuleAction LogEvent
    

After you assign the new action to a new variable, assign a value to the action. Use the following command to assign a value to the new action:

$NewAction.<ActionProperty> = <Single Value or Array of Values>

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

To assign values to a new action

  • Run the following command:

    $NewAction.LogMessage = "Transport Rule triggered"
    

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

Set-TransportRule <Transport Rule Name> -Action @(<Actions>)

Note

You must order the existing and new actions according to their Rank when you specify the actions in the Set-TransportRule command. Use the Get-TransportRuleAction command to view the rank of each action.

To modify the existing transport rule

  • Run the following command:

    Set-TransportRule "Test Rule" -Action @($ExistingAction0, $ExistingAction1, $NewAction)
    

Removing Actions from a Transport Rule

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

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

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

  3. Modify the existing transport rule.

To remove an action from a transport rule

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

    $ActionArray = (Get-TransportRule "Test Rule").Actions
    
  2. Run the following command to view the number of actions in the array:

    $ActionArray.Length
    
  3. Run the following command to view the actions in the $ActionArray variable and note the array element number of the action you want to remove:

    $ActionArray
    
  4. Run the following commands to assign the actions that you want to keep to variables, omitting the array elements of the actions that you do not want to keep:

    $ExistingAction1 = $Action[1]
    ...
    
  5. Run the following command to modify the transport rule, assigning only the variables associated with the actions that you want to keep:

    Set-TransportRule "Test Rule" -Action @($ExistingAction1)
    

Modifying the Value of an Existing Action on a Transport Rule

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

Note

The following examples use transport rule actions that are available on Hub Transport servers.

To determine the type of action that you want to modify, see Transport Rule Actions.

Modifying an Existing Single-Value Action

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

$ActionArray = (Get-TransportRule "Test Rule").Actions

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

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

    $ActionArray = (Get-TransportRule "Test Rule").Actions
    
  2. Run the following command to view actions in the array:

    $ActionArray
    

Determine which action you want to modify and note its array element number. The first action in the array is at array element 0. If the action that you want to modify is the third action in the list, its array element number is 2. You must then determine the action property or properties. The action properties are always listed immediately before the line starting with Name.

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

$ActionArray[<array element number>].<Action Property> = <Single Value>

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

To assign a value to the SetScl action at array element 2

  • Run the following command:

    $ActionArray[2].SclValue = "7"
    

To modify the existing transport rule

  • Run the following command:

    Set-TransportRule "Test Rule" -Action $ActionArray
    

Note

You don't have to insert the $ActionArray variable in an array because the $ActionArray variable is already an array.

Adding Values to an Existing Multiple-Value Action

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

$ActionArray = (Get-TransportRule "Test Rule").Actions

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

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

    $ActionArray = (Get-TransportRule "Test Rule").Actions
    
  2. Run the following command to view actions in the array:

    $ActionArray
    

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

Addresses         : {Legal Group, Regulatory Compliance}
Name              : RedirectMessage
Rank              : 10
LinkedDisplayText : redirect the message to <a id="Addresses">addresses</a>

RejectReason       : Example Message
EnhancedStatusCode : 5.7.1
Name               : RejectMessage
Rank               : 11
LinkedDisplayText  : send <a id="RejectReason">bounce message</a> to sender with <a id ="EnhancedStatusCode">enhanced status code</a>

In this example, the first action, at array element 0, has the action property Addresses. The second action, at array element 1, has the action properties RejectReason and EnhancedStatusCode.

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

$ActionArray[<Array Element Number>].<Action Property> += <Array of Values>

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

To add values to an existing action at array element 0 of the example

  • Run the following command:

    $ActionArray[0].Addresses += @((Get-DistributionGroup "Example Group 1"), (Get-DistributionGroup "Example Group 2))
    

To modify the existing transport rule

  • Run the following command:

    Set-TransportRule "Test Rule" -Action $ActionArray
    

Note

You don't have to insert the $ActionArray variable in an array because $ActionArray variable is already an array.

Removing Values from an Existing Multiple-Value Action

To remove values from an existing action, you must note the existing values and then re-enter the existing values into the action, 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 actions that have only a few values configured. However, for actions that have dozens, or hundreds, of values configured, this procedure is not feasible. We recommend that you use a ForEach loop when it is impractical to manually reassign values to an action.
For more information, see Using the Exchange Management Shell.

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

$ActionArray = (Get-TransportRule "Test Rule").Actions

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

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

    $ActionArray = (Get-TransportRule "Test Rule").Actions
    
  2. Run the following command to view actions in the array:

    $ActionArray
    

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

$ActionArray[<Array Element Number>]

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

$ActionArray[<Array Element Number>].<Action Property> = <Array of Values>

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

To remove values from an existing action at array element 0 of the earlier example

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

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

    $ActionArray[0].Addresses = @((Get-Mailbox "Kim Akers"),(Get-Mailbox "Frank Lee"))
    

To modify the existing transport rule

  • Run the following command:

    Set-TransportRule "Test Rule" -Action $ActionArray
    

    Note

    You don't have to insert the $ActionArray variable in an array because $ActionArray variable is already an array.

For More Information

For detailed syntax and parameter information about each command, see the following topics:

For more information about transport rules, see the following topics: