Automation with scripting agents

Cmdlet extension agents are introduced in Exchange Server 2010, and they are called when the Exchange 2010/2013/2016 cmdlets are executed. These agents are used to modify and extend the capabilities of cmdlets by performing additional tasks that the cmdlet alone cannot perform.

For example, in Exchange 2007, if you are using the New-Mailbox cmdlet without a -Database parameter, the command fails. However, if you use the same cmdlet in Exchange 2010/2013/2016 without the -Database parameter, a built-in cmdlet extension agent called Mailbox Resources Management is invoked. The agent will then automatically check for a mailbox database to create the mailbox and pass it on the -Database parameter.

One thing to note here is that the cmdlet extension agents can be invoked by the Exchange 2010/2013/2016 cmdlets only. Exchange 2007 or any third-party products cannot invoke these agents. Also these agents cannot be invoked through scripts. But if the scripts contain Exchange 2010/2013/2016 cmdlets, these agents will be called when executing those cmdlets.

In Exchange 2013/2016, there are these eight agents that can be invoked while executing a cmdlet. You will notice that all of these agents except the scripting agent are enabled by default. Agents cannot be added or removed from this list. However, you can use the Scripting agent to run PowerShell scripts to extend the functionality of cmdlets. These agents can be disabled and the priority can be changed except the ones that are listed as System agents. An agent's priority determines the order in which the agent is invoked. So, agents with lower priority number will be invoked first. Here is a list of default agents with their priority:

Before you make any changes to the scripting agents and their priority, understand the impact it will have on the use of cmdlets on the Exchange servers in your organization.

When you have configured and enabled the scripting-agent extension agent, the cmdlets specified in the configuration XML file will check for some additional information and will set parameters or values specified in the configuration file in the following order:

• Provision Default Properties: As the name suggests, this API call is used to either set or override predefined values on object properties during creation of the objects. This will not impact the values of objects created or modified using higher priority agents.
• Update Affected I Configurable: If you need to set property values after all processing before invoking a valid API, you will use this API call. Again the values modified or set by higher priority agents is respected by this API.
• Validate: Just before the data gets written into the store, this API call is used to validate the property values on objects. Data gets written to the store if it succeeds and an error is returned, which is defined in this API if it fails.
• OnComplete: If you would like cmdlets to perform tasks after all the processing is complete, you will use this API call. For example, we will see how to provision an archive mailbox for users later in Scenario 1 and 2 using the OnComplete API.

Now, let's review the attributes of Scripting agent configuration file from the following table:

https://technet.microsoft.com/en-us/library/dd335054(v=exchg.150).aspx

The following two steps are required to enable the Scripting agent:

1. ScriptingAgentConfig.xml.sample in the <Exchange Installation Path>\V15\Bin\CmdletExtensionAgents file needs to be renamed to ScriptingAgentConfig.xml on every Exchange 2013/2016 server in your organization. You can make changes to this file on one server and copy it on all the Exchange 2013/2016 servers. The file has to be the same on all the servers; otherwise, inconsistent results will be returned based on the cmdlet execution and the server on which it was run.
2. Enable-CmdletExtensionAgent "Scripting Agent" will enable the scripting agent cmdlet extension agent.

Once the scripting agent is enabled, modify the file for the two scenarios.

Scenario 1

When any user mailbox is created, we disable ActiveSync, IMAP, and POP. By default, when you create a new mailbox, it enables ActiveSync, IMAP, and POP protocols.

You can check this by creating a new user through Exchange Admin Center or Exchange management Shell and use the following cmdlet:

Here is the content of the ScriptingAgentConfig.xml file. In this file, we will use the Mailbox provisioning feature and update the cmdlets that will be used to create (New-Mailbox) mailboxes:

<?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-CASMailbox $mailbox -ActiveSyncEnabled $False -ImapEnabled $False -POPEnabled $False
 }
 </ApiCall>
 </Feature>
</Configuration>

The $provisioningHandler.UserSpecified parameter contains user provided parameters passed to the cmdlet. $provisioningHandler.UserSpecifiedParameters["Name"] returns the value of the Name parameter in the New-Mailbox cmdlet.

Now, once the configuration file is set and you have enabled the cmdlet extension agent, it's time to test whether it works or not.

We will create a new mailbox for Peter and check the values of ActiveSync, POP, and IMAP, which should be disabled if the cmdlet extension agent is working. We will use the following cmdlet to create a new mailbox:

New-Mailbox -Alias peterh -Name "Peter Houston" -FirstName Peter -LastName Houston -DisplayName "Peter Houston" -UserPrincipalName peterh@contoso.com -Password (ConvertTo-SecureString -String 'pa$$word1' -AsPlainText -Force)

Here is the result:

Scenario 2

Create an archive mailbox for all user mailboxes that are created. By default, you need to pass additional parameters to the New-Mailbox cmdlet to enable archive for a mailbox.

This is how your ScriptingAgentConfig.xml file will look for this scenario:

<?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"]
 
 If ((Get-Mailbox $mailbox).ArchiveDatabase -eq $null) 
 {
 Enable-Mailbox $mailbox -Archive 
 }
 }
 </ApiCall>
 </Feature>
</Configuration>

Now, it's time to test the cmdlet extension agent by creating a new mailbox. Remember, by default, New-Mailbox cmdlet will not create an archive mailbox. We will use the following command to create a new mailbox for Yan Li.

New-Mailbox -Alias yanl -Name "Yan Li" -FirstName Yan -LastName Li -DisplayName "Yan Li" -UserPrincipalName yanl@contoso.com -Password (ConvertTo-SecureString -String 'pa$$word1' -AsPlainText -Force)

The output of Get-Mailbox is listed here, which shows that an archive mailbox has been provisioned for Yan by the cmdlet Extension agent: