Automation–Orchestrator and the Exchange PowerShell Activity

A question came up on an internal distribution list recently about how to create an Exchange Distribution List leveraging Orchestrator.  Well, I did some investigation and in fact collaborated with Charles Joy on this because we were both curious. The setup and configuration is the trickiest part and you’ll have to do some configuration on more than just your Orchestrator infrastructure. The Exchange server will need to be modified to support this. I highly recommend taking this into the lab first so you know all the moving parts!

Let’s Dive In!

Step 1:Go Download the Integration Pack and Do Some Configuration

You’re going to want to make sure that all is followed to the letter on the following URL: I also recommend after all configurations are done, doing a GPUPDATE /FORCE if you can on the Exchange and Orchestrator servers to update Group Policy and ensure all is up to date. This is probably the most important step (preparation) because if this isn’t done exactly right, you will get very frustrated later on Open-mouthed smile.

Step 2: Ensure You Have an ID with the “Juice”

Ensure that the account you have defined in your Exchange Admin Connection (found under Options in the Orchestrator Designer) has enough rights to create a Distribution List for Exchange. See my very basic configuration shown below and I turned all validation off in my lab. I also used port 80 and did not use SSL.  I can’t stress enough to make sure you are working with an account that has appropriate rights to do what you need or you’ll find yourself spending a bit of time wondering why things aren’t working. 

Troubleshooting Note    A way to validate rights for the service account you have created / been given would be to make the same connection to your Exchange server in a PowerShell session as you would be with Orchestrator using the same account you configured above.  Then executing a simple command to validate you have rights.


001 002 003 004 005 006 $conn = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri -Authentication Kerberos -Credential (Get-Credential) Import-PSSession $conn Get-User #Don't forget to remove the session :) Remove-PSSession $conn

You should get something like the below for output.  If you get this, you know you have at least got a good connection – event better, next steps will leverage this last command (Get-User) to validate in connectivity in Orchestrator.


Step 3: Create a Basic Runbook

Create a simple Runbook to get the connection and rights tested out. Grab the “Run Exchange Management Shell CMDLET” activity out of the Exchange Admin list of activities, on the right pane within the Orchestrator Designer, and drop it into a basic Runbook.  See below, I’m putting in the “Get-User” command in the Command Text box to do essentially what we did in step 2 but with Orchestrator this time.  Ensure you change the option for Is Exchange Command to True to ensure you can successfully execute this command against the Exchange cmdlets.


Step 4: Test – Iterate – Test Smile

To get some basic testing going on and a successful Runbook execution put in a really basic script execution to ensure you have rights and can access the Exchange Server with that account you specified in the connection. Run it.  My suggestion is to start simple and make sure you are doing queries instead of creations at least at the beginning so you don’t have to constantly go back in and remove what you’ve created.

Important Note    Testing is not done in the Orchestrator test console for this.  This activity leverages a PowerShell module on the Exchange server so in order to do proper testing, you need to have this checked in and executed from the Runbook Designer or it will fail (unless of course you have the necessary support installed on your system you are testing from).

Step 5: Validate Success as You Go. 

You are looking for a “green” result showing some data coming back. If you get a red, and it shows “access denied”, check the user account. If it shows something on WINRM / PS Remoting, check step 1 above.  You’re looking for Command Output Data within the returned results from the activity.


Step 6: Create your Test Distribution List

Add in a bit of PowerShell into your existing activity to test the creation of a statically named DL and then add a list of users to that successfully created DL. Example below, replace with stuff that exists in your environment.

001 002 003 004 $DLGroup = "Dist4" $Members = @() $Members = "!ex" , "!sp" , "administrator" New-DistributionGroup –Name $DLGroup -Members $Members -OrganizationalUnit ""



Step “N”… : Go Nuts, Get Dynamic

Iterate on this and add logic to check for the existence of the DL and if it does exist add members instead of trying to create and add members, etc. Really depends upon what you are trying to accomplish. The other piece here is of course using dynamic data to populate this information instead of statically assigned data (use the power of Orchestrator and dynamic published data!). This can come in many forms (including directly from multiple AD groups, SQL, CSV, etc.). Trick here is ensuring you are putting in proper logic to make decisions since this automation is doing the work of your brain Smile.  In the below example I added a bit more rudementary checking to illustrate what I’m talking about.  If the DL exists, just update the membership with the new array, otherwise create it and add members. 

001 002 003 004 005 006 007 008 009 010 011 012 013 014 015 $DLGroup = "Dist4" $Members = @() $Members = "!ex" , "!sp" , "administrator" , "Jbritt" $DLExists = "" $DLExists = Get-DistributionGroup $DLGroup If ($DLExists) { Update-DistributionGroupMember –Identity $DLGroup -Members $Members -Confirm:$False } else { New-DistributionGroup -Name $DLGroup -Members $Members -OrganizationalUnit "" }

Keep in mind that if you wanted to Add a member instead of Update membership, you’ll likely want to use a foreach loop similar to below to process the array and potentially adding a try/catch for members that already exist.

001 002 003 004 foreach($member in $members) { Add-DistributionGroupMember -Identity $DLGroup -Member $Member }

That’s it!  I hope that gave some decent guidance on the use of the Orchestrator PowerShell activity for Exchange.  For more information and tips/tricks for Orchestrator, be sure to watch for blog posts in the Automation Track!

Till next time, Happy Automating!