Using Cmdlet Extension Agents to Cause Automatic Events to Occur in Exchange 2010 – Life Just Got Simpler!
In previous posts, I’ve shown how to automate some tasks like automatically sending a ‘welcome’ email to all new user accounts, automatically applying Messaging Records Management policies to new users, and other functions. This helps perform normally routine tasks, as well as providing for a level of interaction with the users that isn’t as readily available manually. It also helps reduce errors and maintain consistency.
The problem with these methods is that they rely on scheduled tasks. So, every four hours, send a message to the new users. That’s all fine and dandy when the account is provisioned for a user starting tomorrow or next week. But if the HR person is standing at your desk saying “the person is starting NOW”, there’s a gap. Additionally, as the environment gets bigger and bigger, the queries to find new users can take more time and more system resources. There must be a better way, and there IS!
A nearly undocumented Exchange 2010 feature called the cmdlet extension agents helps perform tasks automatically based on other commands running. Other Exchange notables have talked about some of the features, including Administrator Audit Logging. There are also cmdlet extension agents for OAB Resource Management, Provisioning Policy, Mailbox Resources Management, RUS, and even a Query Base DN agent. These can be seen by using the Get-CmdletExtensionAgent cmdlet. Today, we’ll focus on the Scripting Agent.
Picture this: a new user mailbox is created from ANY method that calls the new-mailbox cmdlet. This could be Exchange Management Console, Exchange Management Shell, or even some custom provisioning application. As soon as that cmdlet succeeds, the server immediately fires another event – say, sending the ‘welcome’ email. Or disabling POP3 and IMAP on the mailbox; or assigning an Exchange ActiveSync or retention policy. Very cool. But it gets even cooler when you realize that you can also trigger events BEFORE the cmdlet actually does much. Imagine, everytime the remove-mailbox cmdlet is run, an export-mailbox cmdlet is triggered and dumps the mailbox to .pst! It’s possible! Here’s how we can do thngs:
Open Notepad and paste the following:
<?xml version="1.0" encoding="utf-8" ?>
<Configuration version="1.0">
<Feature Name="MailboxProvisioning" Cmdlets="new-mailbox">
<ApiCall Name="OnComplete">
if($succeeded) {
$newmailbox = $provisioningHandler.UserSpecifiedParameters["Name"]
set-casmailbox $newmailbox -ImapEnabled $false
}
</ApiCall>
</Feature>
</Configuration>
Save the file as ScriptingAgentConfig.xml in the \bin\CmdletExtensionAgents folder, which, by default is C:\Program Files\Microsoft\Exchange Server\V14\Bin\CmdletExtensionAgents
Let’s break down how this works. In our code, the highlighted sections are where we need to focus, Notice this line: <Feature Name=”MailboxProvisioning” Cmdlets=”new-mailbox”>. The “cmdlets” parameter dictates what cmdlets will fire our custom event. In this case, whenever new-mailbox is executed. We can define multiple cmdlets here, separating them with a comma.The very next line, <ApiCall Name=”OnComplete”> defines when during the new-mailbox process our custom event will fire. Here, it’s OnComplete, or after the new-mailbox command finishes. We can also use “validate”, to trigger an event after Exchange determines new-mailbox is a valid command and has all of the info it needs. “validate” is where we could export a mailbox during remove-mailbox, as it occurs after validation, but before the mailbox is actually removed.
For the sake of keeping things simple here, we’ll disable IMAP on a new mailbox as an example. In order to disable the IMAP feature, we normally run the set-casmailbox cmdlet (or use EMC, which just calls set-casmailbox), which requires a mailbox name. So, we use $newmailbox = $provisioningHandler.UserSpecifiedParameters[“Name”] to assign the mailbox name used in the new-mailbox cmdlet to a variable, $newmailbox. After that, we simply run set-casmailbox $newmailbox -ImapEnabled $false like we would from EMS or a .ps1 script. That’s it!
Before we try out our new found feature, we need to enable the Cmdlet Extension Agent. Open an Exchange Management Shell window and use the following command:
Enable-CmdletExtensionAgent "Scripting Agent"
Now – using either EMS or EMC, create a new mailbox. Once it’s created, look at the Mailbox Features tab of the mailbox, and you’ll see that IMAP is disabled:
You can certainly perform multiple actions, if you’d like, by simply specifying each command on a new line. If you’d like to take complex actions after new-mailbox (or any cmdlet), you can also call an external script by placing the path and script name in the .xml file.
$newmailbox = $provisioningHandler.UserSpecifiedParameters["Name"] c:\myscript.ps1 -name $newmailbox
Keep in mind that you can’t do things like write-host or dump other outputs to the console screen. If you’d like to look at some other samples, look at the ScriptingAgentConfig.sample file in the \CmdletExtensionAgents folder in Notepad.
As you can see, the possibilities here are endless. We can automate many tasks, and, with the power of PowerShell, perform many actions not available in the Exchange Management Console.
Caveats: If you have more than one server running Exchange 2010, you’ll need to enable the extension agent on each, and create the .xml file.
Follow Me