Objects Available to the Scripting Agent

The Scripting Agent uses $ProvisioningHandler and $readOnlyIConfigurable to represent objects available during an action. I could not find any documentation on these objects and did some experimentation. The following is my results:

• The variable $ProvisioningHandler contains information about the cmdlet being executed. This includes  the name of the cmdlet, parameters for the cmdlet, and the user that ran the cmdlet.
• The name of the cmdlet is stored in $provisioningHandler.TaskName
• The user running the cmdlet is stored in $provisioningHandler.UserScope.UserID
• The parameters passed to the cmdlet are stored in $provisioningHandler.UserSpecifiedParameters[“PName”] where PName is the name of the parameter that was passed. For example, Identity and Alias are common parameter names that would be used in place of PName.
• The variable $readOnlyIConfigurable contains the properties of the object being acted upon. For example, when using the Set-Mailbox cmdlet, $readOnlyIConfigurable contains the object for the mailbox being modified. The values listed are those about to be applied, not the current values of the object.
• The content of these variables can change depending on the ApiCall being used. For example, when using the Validate ApiCall the $readOnlyIConfigurable variable is populated but when using the OnComplete ApiCall the $readOnlyIConfigurable variable is empty. I’ve not tested all of the possible permutations.

The following example of ScriptingAgentConfig.xml shows how you can check the data available to you for various cmdlets:

As far as I can tell, it is not possible to have actions of the Scripting Agent displayed on the screen. However, you can have it dump to text file as shown in the example. I also attempted to get more information about the objects by using Get-Member, but no information was returned. You can modify this example to see what information is available for each of ApiCall options and different cmdlets. Each time you run it, any previous text files are overwritten.

ScriptingAgentConfig.xml Syntax

The Scripting Agent for Exchange 2010 SP1 uses ScriptingAgentConfig.xml to define additional content used when running specified cmdlets. This file needs to be located in in C:\Program Files\Microsoft\Exchange\v14\Bin\CmdletExtensionAgents. This file uses the following generic format:

Line 1 <?xml version “1.0” encoding=”utf-8”?>

Line 2 <Configuration version=”1.0”>

Line 3 <Feature Name=”YouPickName” Cmdlets=”CsvList”>

Line 4 <ApiCall Name=”NameOfAPI”>

Line 5 The script goes here

Line 6 </ApiCall>

Line 7 </Feature>

Line 8 </Configuration>

Description of example:

• Line 1 defines the version of XML . This line is always here and always the same.
• Line 2 opens the configuration tag. The configuration tag exists once in the file.
• Line 3 opens the feature tag. There can be multiple feature tags in the file. Each feature tag has a name that you define. The name needs to be unique, but can be anything that makes sense to you. Each feature tag also has a list of cmdlets that it applies to. If the feature applies to multiple cmdlets the they are separated by commas.
• Line 4 opens the ApiCall tag. This defines how/when the following script is used. The name defines the ApiCall that is used. Valid values are: ProvisionDefaultProperties, UpdateAffectedIConfigurable, Validate, and OnComplete. Multiple ApiCall tags can be used in each feature tag.
• Line 5 the script within the ApiCall tag is run when defined by the ApiCall name used. This is a PowerShell script that is typically short, but can be complex. It can include ligic structures such as if statements. It can also use data in the ProvisioningHandler and IConfigurable objects. These objects contain information about the request.
• Lines 6-8 close the open tags started in Lines 2-4. Notice that these tags are nested and the last tag to be opened is the first tag to be closed.

You can also use the <Common> </Common> tag to define functions that are used by scripts within multiple feature tags. The common tag is placed inside the configuration tag at the same level as the feature tag, but not inside the feature tag.

I suggest liberally using comments within your xml file to document what each section is doing. For a single line the # symbol designates a comment. Block quotes are done by placing content within <!--   -->.

I will be posting some specific examples with explanations. You can also view the example file that comes with Exchange 2010 sp1 at C:\Program Files\Microsoft\Exchange Server\V14\Bin\CmdletExtensionAgents\ScriptingAgentConfig.xml.sample.

Customize Exchange Cmdlets

There have been many times in class when students have asked me if there is a way to change default settings in Exchange 2010 when perform task such as creating users. If you had asked me two weeks ago, my answer would have been: “Nope. You’ll need to modify those users after you create them.” Turns out I was wrong.

Exchange 2010 SP1 includes a component called the Scripting Agent. The Scripting Agent lets you define scripts that run when specific cmdlets, such as New-Mailbox, are used. Since the Exchange Management Console (EMC) runs cmdlets in the background, this will apply there too.

First you need to enable the Scripting Agent:

Enable-CmdletExtensionAgent “Scripting Agent”

Next, you need to create an XML file that defines the scripts to be run and for which cmdlets. The file must be named ScriptingAgentConfig.xml and located in C:\Program Files\Microsoft\Exchange\v14\Bin\CmdletExtensionAgents.  I’ll post some examples later. In this post I will limit myself to describing generally what it can do.

Each time a cmdlet is used, the ScriptingAgentConfig.xml file is checked to see whether there is a script defined for the cmdlet. If there is a script defined for the cmdlet, it is executed. There are four ways a script can be run. The documentation refers to these ways as APIs.

• ProvisionDefaultProperties. This is exactly what you think it is. It lets you define default values for cmdlets parameters. For example, you could specify a default OU when creating new users. If a user running the cmdlet provides values, they override the defaults that you provide with this API.
• UpdateAffectedIConfigurable. Instead of providing defaults, this will overwrite values provided by the user running the cmdlet.
• Validate. This API is called just before the cmdlet writes data. The intent of this is to validate data that is being written before it is actually written. Your script provides the validation. If the script runs without errors, then the cmdlet proceeds to write data. Otherwise, your script needs to generate the error if the conditions you specify are not met. For example, you could verify that a valid database has been specified for a new mailbox to prevent it from being randomly assigned to a database.
• OnComplete. This API is called after the cmdlet is complete. This provides you with an opportunity to modify setting related to the original cmdlet, but not part of the original cmdlet. For example, after creating a new mailbox, you could set calendar settings that are not possible with the New-Mailbox cmdlet.

After you create ScriptingAgentConfig.xml, you need to copy it to all of your Exchange 2010 SP1 servers.

Microsoft provides some very limited documentation here: http://technet.microsoft.com/en-us/library/dd297951.aspx