For space reasons, this text was cut out of my Exchange 2013 Inside Out: Mailbox and High Availability book. I only found it again recently, so here it is…

Many properties can be set to control exactly how a mailbox functions, but some are more important than others. All mailbox properties can be manipulated with EMS and the most critical are exposed through EAC. However, it’s easy to forget to update or set a property. Automation comes to the rescue in the form of Exchange’s cmdlet extension agents, a feature that first appeared in Exchange 2010. One of the standard agents is called the scripting agent and its purpose is to support the automation of common tasks such as mailbox creation. The most common use of the scripting agent is to update the properties of new mailboxes after they are created.

For example, if we create a new mailbox using EMS or EAC, its language and regional settings are not updated and the user will be prompted to provide these settings the first time that they access the mailbox with Outlook Web App. The scripting agent gives us an easy way to ensure that default language and regional settings are applied to new mailboxes and so avoid the need for the user to become involved in the process. If the default settings are not correct, the user can select new values through Outlook Web App options.

The scripting agent is disabled by default. The agent uses an XML configuration file stored in the <install directory>\V15\Bin\CmdletExtensionAgents folder to understand what processing it must perform and when it is invoked. Exchange provides a sample configuration file called ScriptingAgentConfig.xml.sample that you can edit to add your instructions. The sample file contains a number of interesting examples with which you can experiment, but our purposes require only a very simple file that can be created with any text editor and named ScriptingAgentConfig.xml.

The example ScriptingAgentConfig.xml shown below tells the scripting agent:

• It should be invoked whenever the New-Mailbox or Enable-Mailbox cmdlets are run by any process. These cmdlets are used to create a new mailbox or enable a mailbox for an existing Active Directory account.
• The specified code is invoked when the cmdlets have completed processing (the “OnComplete” event)
• The “Name” parameter is to be retrieved from the provisioning handler (the framework that surrounds the scripting agent). The name is the identifier for the object being processed, in this case, a mailbox.
• Three cmdlets are to be run. Set-Mailbox is used to set a default language value of “en-US”; Set-MailboxRegionalConfiguration sets the appropriate date and time formats; and Set-MailboxCalendarConfiguration sets the start of the working day.

<?xml version="1.0" encoding="utf-8" ?>
<Configuration version="1.0">
<Feature Name="Mailboxes" Cmdlets="New-Mailbox, Enable-Mailbox">
<ApiCall Name="OnComplete">
if($succeeded) {
$Name= $ProvisioningHandler.UserSpecifiedParameters["Name"]
Set-Mailbox $Name -Languages "en-US"
Set-MailboxRegionalConfiguration $Name -DateFormat "dd-MMM-yy" -TimeZone "Pacific                        Standard Time"
Set-MailboxCalendarConfiguration $Name -WorkingHoursStartTime "08:30:00"
}
</ApiCall>
</Feature>
</Configuration>

To enable the scripting agent so that it will process the code in its configuration file, we run the Enable-CmdletExtensionAgent cmdlet:

Enable-CmdletExtensionAgent “Scripting Agent”

This is an organization-wide setting, so it is obviously important to have the same configuration file in place on every mailbox server so that the same behavior happens throughout the organization. You do not have to put the file on CAS servers because Exchange 2013 only runs EMS cmdlets to execute operations such as mailbox creation on mailbox servers. After the configuration files are deployed and the scripting agent is enabled, Exchange will faithfully execute the specified commands to automate the finalization of mailbox settings. It’s also important that you test that everything continues to work as you deploy new cumulative updates for Exchange 2013.

Because the scripting agent executes code without administrator intervention (and probably without any knowledge on the part of some administrators), it’s obviously important to make sure that the code works as intended before deployment. After all, it would be embarrassing to see the error illustrated below each time one of your co-workers attempted to create a new mailbox. Errors in the scripting agent configuration file might prevent EAC or EMS from being able to complete an operation. Code should be developed and thoroughly debugged on a test system before being deployed into production and then become part of the “must check list” when a new version or update for Exchange appears as there’s no guarantee that the syntax of a cmdlet will not change in the future.

When you’re developing the configuration file, you’ll probably make some mistakes or want to test different versions of code. To force Exchange to pick up a new version of the configuration file, disable and then enable the scripting agent.

Disable-CmdletExtensionAgent “Scripting Agent” | Enable-CmdletExtensionAgent “Scripting Agent”

All of this goes to prove that there is a mass of interesting things to be discovered if you poke around under the surface of Exchange. And in this case, the interesting thing might just save you some time…

The cmdlet extension agent is not available in Exchange Online. This is logical because the last thing you probably want in a massive multi-tenant environment is to have administrators playing around (in the most professional sense) with code attached to standard cmdlets. Perhaps Microsoft will provide an alternate method in the future to accomplish the same functionality for Office 365, but it’s not there now.

Follow Tony @12Knocksinna