Automating tasks with the scripting agent

The scripting agents were introduced in Exchange 2010 and still remain in Exchange 2013. Exchange 2010 introduced the concept of cmdlet extension agents is to extend the functionality of the Exchange Management Tools. The scripting extension agent can be used to trigger custom commands, as changes are made by administrators from the management console or the shell. In this recipe, we'll take a look at how to use the scripting agent to automate a task in the Exchange Management Shell.

Getting ready

To complete the steps in this recipe, you'll need to create an XML file. You can simply use Notepad or any XML editor of your choice.

How to do it...

To automate a task in the Exchange Management Shell using the scripting agent, perform the following steps:

1. Let's say that you need to enable a single item recovery for every mailbox that gets created in your organization. By default, a single item recovery is disabled when you create a mailbox. To automatically enable a single item recovery for each mailbox as it is created, add the following code to a new file:

   <?xml version="1.0" encoding="utf-8" ?>
   <Configuration version="1.0">
   <Feature Name="MailboxProvisioning" Cmdlets="New-Mailbox">
   <ApiCall Name="OnComplete">
     if($succeeded) {
       $mailbox = $provisioningHandler.UserSpecifiedParameters["Name"]
       Set-Mailbox $mailbox -SingleItemRecoveryEnabled $true
     }
   </ApiCall>
   </Feature>
   </Configuration>

2. Next, make sure to save the file as ScriptingAgentConfig.xml on all Exchange servers in the <install path>\V15\Bin\CmdletExtensionAgents directory.
3. Finally, you need to enable the scripting agent using the following command:

   Enable-CmdletExtensionAgent "Scripting Agent"
   

If you have multiple Exchange servers in your environment, make sure that you copy the ScriptingAgentConfig.xml file to each server in the CmdletExtentionAgents directory, as described previously.

How it works...

When the scripting agent is enabled, it is called every time a cmdlet is run in your Exchange environment. This includes cmdlets that run from within the shell or any of the graphical management tools.

You can see from the code that, in this example, we're using the OnComplete API, which runs immediately after the cmdlet has been completed. Using the Feature tag, we specified that this block of code should only be executed on completion of the New-Mailbox cmdlet.

After the New-Mailbox cmdlet has completed, we check the built-in $succeeded variable to ensure that the command was successful. If so, we retrieve the value that was used with the -Name parameter and store the result in the $mailbox variable. This value is then used to specify the identity when running the Set-Mailbox cmdlet to enable a single item recovery.

There's more...

You can add multiple scripts to the XML file if needed by defining multiple Feature tags under the configuration tag. Each block of code within the Feature tag should have an ApiCall tag, as shown in the previous example.

The state of the scripting agent is an organization-wide setting. If you enable the scripting agent, it is important that ScriptingAgentConfig.xml is copied to every Exchange server in your organization.

Using multiple cmdlets with the OnComplete API

Let's take a look at another example. Imagine that, in addition to enabling a single item recovery for all newly-created mailboxes, we also want to disable the ActiveSync protocol for each mailbox. This means that, in addition to calling the Set-Mailbox cmdlet to enable a single item recovery, we'll also need to call the Set-CASMailbox cmdlet to disable ActiveSync. Also, mailboxes can be created using both the New-Mailbox and Enable-Mailbox cmdlets. Since we'd like our custom settings to be applied regardless of how the mailbox is created, we can use the following code in our XML file:

<?xml version="1.0" encoding="utf-8" ?>
<Configuration version="1.0">
<Feature Name="Mailboxes" Cmdlets="new-mailbox,enable-mailbox">
<ApiCall Name="OnComplete">
  if($succeeded) {
    $id = $provisioningHandler.UserSpecifiedParameters["Alias"]
    Set-Mailbox $id -SingleItemRecoveryEnabled $true
    Set-CASMailbox $id -ActiveSyncEnabled $false
  }
</ApiCall>
</Feature>
</Configuration>

This code is similar to our previous example, except in this version, we specified that our custom code will be called when both the New-Mailbox and Enable-Mailbox cmdlets are used. The code in the ApiCall tag captures Alias of the mailbox, and then uses Set-Mailbox and Set-CASMailbox to modify the settings as required.

There are multiple scripting agent APIs that can be used to extend the Exchange Management Shell functionality even further. For examples on how to use these APIs, refer to the ScriptingAgentConfig.xml sample file in the <installpath>\V15\Bin\CmdletExtensionAgents folder.

See also

• Adding, modifying, and removing mailboxes in Chapter 3, Managing Recipients
• Managing ActiveSync, OWA, POP3, and IMAP4 mailbox settings in Chapter 7, Managing Client Access