Cmdlet Extension Agents Part 2: Postconfiguring Mailboxes

Cmdlet Extension Agents Part 1: Automatic archive creation

Almost a year ago, I posted an article in which I tried to show the power of Cmdlet Extension Agents in Exchange 2010, or more specifically, the Scripting Agent. Unfortunately, the Cmdlet Extension Agents are often overlooked or ignored, despite customers having requirements to customize things immediately after creating a mailbox. Therefor, I decided to write another article on this topic, hoping people take up using Scripting Agents.

Now while you can also put all sorts of post-configuration tasks in provisioning scripts, using the Scripting Agent when possible has a big bonus, because those additional actions not only run when you run the cmdlet directly from the Exchange Management Shell but also when you run them indirectly by using the Exchange Management Console.

So, as this follow up of the previous article, in which I explained what the CmdLet Extension Agents are and how to utilize the Scripting Agent to automate tasks, I’ll show you another example of a Scripting Agent and quickly walk you through it, so you can experiment with it (first in a lab of course) and tune it to your own requirements.

In this example, we’ll disable ActiveSync and configure SingleItemRecovery when creating a new user with a mailbox or mailbox-enabling an existing user. Therefor, the cmdlets we’re going to customize are New-Mailbox and Enable-Mailbox.

Open up Notepad and create a file \bin\CmdletExtensionAgents\ScriptingAgentConfig.xml located in Env:ExchangeInstallPath, e.g. C:\Program Files\Microsoft\Exchange Server\V14\Bin\CmdletExtensionAgents, using the following contents:

Note: If you’ve already got a ScriptingAgentConfig.xml file, you need to integrate the following content.

<?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 -SingleItemRecoveryEnabled $true
     Set-CASMailbox $Name -ActiveSyncEnabled $false
   }
 </ApiCall>
 </Feature>
 </Configuration>

As you can see, you’re not limited to 1 action or related cmdlets (*-Mailbox). A small explanation:

  • The Cmdlets specified in this feature extension dictates which cmdlets will be extended, in this case New-Mailbox and Enable-Mailbox;
  • OnComplete dictates that our script will fire when the cmdlet has finished;
  • We check for OnComplete parameter $succeeded, only configuring the mailbox when the preceding events were successful;
  • $provisioningHandler.UserSpecifiedParameters contains user provided parameters passed to the cmdlet. So, $provisioningHandler.UserSpecifiedParameters[“Name”] will return the value of –Name;
  • We set SingleItemRecovery to $true for the mailbox specified by $Name;
  • We disable ActiveSync client access for this mailbox as well.

As mentioned in part 1, distribute this XML file to all your Exchange servers in the local CmdletExtensionAgents folder. When you haven’t already enabled the Scripting Agent, do so by running the following cmdlet:

Enable-CmdletExtensionAgent “Scripting Agent”

Now, when we create a new mailbox or mailbox-enable an existing user:

image

.. you’ll see the SingleItemRecovery has been enabled and ActiveSync has been disabled for this mailbox by the scripting agent:

image

I recommend you start checking out the Scripting Agent if you haven’t already done so. You can use these examples as a starting point and work from there. More information on the Scripting Agent, alternative APIs etc. can be found here.

Cmdlet Extension Agents Part 1: Automatic archive creation

Cmdlet Extension Agents Part 2: Postconfiguring Mailboxes

An Exchange fellow inquired about the possibility to automatically enable personal archives when creating mailboxes with the added requirement to create those personal archives in a specific mailbox database, depending on the location of the mailbox. Dedicated mailbox databases were used for personal archives. Simply said, the idea was that mailboxes located in database MDB1 should get a personal archive in mailbox database ADB1, MDB2 in ADB2, etc.

Your first thought could be creating a script to automatically provision those personal archives in the proper database depending on the mailbox database. But alas, when using Exchange 2010’s automatic mailbox provisioning system you never know upfront what mailbox database will be appointed.

That leads us to Exchange 2010’s Cmdlet Extension Agents, more specific the Scripting Agent. I won’t go into much detail now on those Agents, but look at them as a way to extend cmdlets by adding pre- and post-jobs, additional constraints, reporting or override parameters.

Now, when you haven’t already done so, first exclude the mailbox databases containing personal archives from automatic provisioning. If you have a dedicated server for hosting personal archives, use the IsExcludedFromProvisioning with the Set-MailboxServer cmdlet; to exclude a mailbox database use IsExcludedFromProvisioning with the Set-MailboxDatabase, e.g.

Set-MailboxDatabase <Archive Database ID> –IsExcludedFromProvisioning $true

image

I’ll first show you how the scripted version could work. We’ll start by creating some mailboxes. We don’t require anything fancy, so this will do:

$pwd= ConvertTo-SecureString -AsPlainText “Welcome1 -Force
1..10 | ForEach { New-Mailbox “User$_ -Password $pwd -UserPrincipalName user$_@<domain> }

A quick overview of the result shows the mailboxes are created in a round robin fashion:

image

What you could do now is enabling the archive on ADB1 for MDB1 and ADB2 for MDB2 mailboxes, e.g.

Get-Mailbox –Database MDB1 | Enable-Mailbox –Archive -ArchiveDatabase ADB1
Get-Mailbox –Database MDB2 | Enable-Mailbox –Archive -ArchiveDatabase ADB2

image

This is what we wanted. As you probably understand, the main disadvantage now is that this only works for the current mailbox population. Administrators should appoint the proper mailbox database for personal archives when creating new mailboxes. Can the Scripting Agent overcome this problem?

Let’s have a look on how to configure the Scripting Agent. Open up Notepad and create a file \bin\CmdletExtensionAgents\ScriptingAgentConfig.xml located in Env:ExchangeInstallPath, e.g. C:\Program Files\Microsoft\Exchange Server\V14\Bin\CmdletExtensionAgents, using the following contents:

<?xml version="1.0" encoding="utf-8" ?>
  <Configuration version="1.0">
  <Feature Name="MailboxProvisioning" Cmdlets="New-Mailbox">
  <ApiCall Name="OnComplete">
  If($succeeded) {
    $Name= $provisioningHandler.UserSpecifiedParameters["Name"]
    If ((Get-Mailbox $Name).ArchiveDatabase -eq $null) {
      $MailboxDatabase= (Get-Mailbox $Name).Database
      $ArchiveDatabase= "A"+ ( $MailboxDatabase.Name).Substring( 1)
      Enable-Mailbox $Name -Archive -ArchiveDatabase $ArchiveDatabase
    }
  }
  </ApiCall>
  </Feature>
  </Configuration>

A small explanation might be appropriate:

  • The Cmdlets specified in this feature extension dictates which cmdlets will be extended;
  • OnComplete dictates that our script will fire when the cmdlet has finished;
  • We check for OnComplete parameter $succeeded, only enabling archives when the preceding cmdlet was successful;
  • $provisioningHandler.UserSpecifiedParameters contains user provided parameters passed to the cmdlet. So, $provisioningHandler.UserSpecifiedParameters[“Name”] will return the value of -Name;
  • We’ll check if the mailbox already has a personal archive configured; if not, we can proceed;
  • Next, we’ll get the current MailboxDatabase. Then we’ll map that to our personal archive naming scheme by stripping the first character and prefix it with “A”;
  • Finally, we can execute the cmdlet to enable the personal archive of the mailbox on the database specified.

Now, before we test our scripting agent, we need to distribute the XML file on all of our Exchange servers. The reason for this is that you don’t know which Exchange server an administrator will connect to or which server will execute the cmdlet. The location to copy the XML file to is the local CmdletExtensionAgents folder.

Now there’s one more thing we need to do, which is enabling the Scripting Agent. The Scripting Agent is disabled by default. Use the Enable-CmdletExtensionAgent cmdlet to enable it, e.g.:

Enable-CmdletExtensionAgent “Scripting Agent”

Now, when we use the same cmdlet we used before to create those mailboxes, we get the following result:

image

As you can see, archive databases are now nicely aligned with the automatically assigned mailbox databases.

A small note for those wishing to experiment with the Scripting Agent. Alternatively to OnComplete, you can also try defining the personal archive parameters using the ApiCall ProvisionDefaultProperties. This ApiCall can be used to define default attributes when creating a mailbox. However, this leads to a catch 22 situation and has to do with the Mailbox Resources Management Agent.

By default the Mailbox Resources Management Agent has higher priority (2) than the Scripting Agent (6). This means it will override any settings made in our Scripting Agent.

image

The Mailbox Resources Management Agent is responsible for the automatic mailbox distribution when you don’t specify a mailbox database when creating a mailbox. But it is also responsible for assigning a mailbox database for the personal archive when you don’t specify the ArchiveDatabase parameter.

So, unless we want to add all the automatic mailbox distribution logic to our script, we can’t use the ProvisionDefaultProperties ApiCall properly, because if we want to use that, we need to assign the Scripting Agent a higher priority than the Mailbox Resources Management Agent, but at that point we have no database value so we can’t determine the proper archive database.

If you’re interested in playing with this, check out the ScriptingAgentConfig.xml.sample file which is located in the CmdletExtensionAgents as well. If you’re looking for more information on Cmdlet Extension Agents, check here; information on the Scripting Agent can be found here. More information on the automatic mailbox distribution process here.

ForeFront Identity Manager 2010 RTM

By now you’ve probably already heared ForeFront Identity Manager 2010 went RTM on March 2nd. FIM 2010 is the successor to ILM, the Identity Lifecycle Manager. FIM is an solution to manage identities and credentials in heterogeneous environments. It contains functionality for user (de)provisioning, password synchronization, group management, self-service and workflow-like applications. So for instance, FIM can enable organizations to automatically create an Active Directory user with an Exchange mailbox with all the proper settings when a new employee has been entered into the HRM system (or disabled or removed when the employee leaves the organization, depending on requirements).

You can download the trial here. More information on the FIM portal here.

Identity Lifecycle Manager 2007 FP1 SP1 released

Today Microsoft released Service Pack 1 for Service Pack 1 Identity Lifecycle Manager 2007 Feature Pack 1. Besides many hotfixes and features already contained in rollups, ILM 2007 FP1 SP1 also supports the long awaited support to provision Exchange Server 2010. The article states the following in relation to provisioning Exchange 2010:

You can use the GALSync management agent or a customized Active Directory management agent to perform provisioning for Exchange Server 2010. To use this feature, the following conditions must be true:

  • The ILM 2007 Synchronization service account must be a domain account.
  • The ILM 2007 Synchronization server must be joined to a domain. However, the server does not have to be joined to the domain in which the provisioning occurs.

For more information on using GALSync for provisioning Exchange 2010, consult this TechNet website. Click here to see the SP1 knowledgebase article.

Identity Lifecycle Manager is a metadirectory product and is a successor to the MIIS (Microsoft Identity Integration Server) and MMS (Microsoft Metadirectory Services). MMS was acquired by Microsoft from ZoomIt back in 1999. ILM matches the concept of Identity Management in organizations, where identities (e.g. accounts) exist in many places, e.g. directories and applications. ILM provisions (creation, changes and removed) identities in these directories and applications in their “native format” through agent technology. If you’re interested in ILM check out the Microsoft product page here.