Automation in a corporate environment using Microsoft technologies, Part 3

Introducing SMA

SMA, which is the abbreviation for the Microsoft System Center Service Management Automation, is an IT orchestration engine powered by the PowerShell scripting language. This product is available for installation in the on-premises environment as a part of Windows Azure Pack. Technically SMA consists of several components and there are three major steps in its deployment:

· Setting up SMA web service and runbook workers using SMA distributive from the System Center Orchestrator installation media.

· Installing Windows Azure Pack which will serve as the web front end for SMA.

· Registering SMA endpoint on the Windows Azure Pack web portal.

While Windows Azure Pack is a freely downloadable distribution and does not requires separate licensing, you’ll need to cover all your managed servers with the System Center server management licenses for SMA. Please review the references in the end of this post for more information on licensing issues.

Please note that at Kcell we are still using System Center 2012 R2 version of SMA and Microsoft has since released System Center 2016 SMA. But all recipes in this post will work just fine on both versions, as there were very few changes introduced in SMA 2016. The only important distinction is that SMA now supports PowerShell Script runbooks which differ from the PowerShell Workflow runbooks in that the former are hosted in a pure PowerShell interpreter environment while the latter are technically instances of workflows running inside the .NET Windows Workflow Foundation engine. I’ll cover this in more details below, but you are also advised to look through the references, especially excellent topics by Don Jones in the TechNet Magazine, for deeper understanding of PowerShell workflows and how they relate to the regular PowerShell execution context.

PowerShell as a scripting language

PowerShell (PS for brevity) is a high level object-oriented interpreted language based on .NET platform with a strong focus on common system administration scenarios. There is a lot of information on this language in the Internet and I’ll not repeat it all here. Instead, I’ll just outline the key takeaways of this programming language which make it a tool of choice for implementing automation scenarios leveraging Microsoft products and platforms:

· It’s built into Windows and most other Microsoft server products.

· It’s a modern language with many features and ideas stolen from Unix bash, Perl and C#.

· It supports vital technologies and protocols, which are essential for the implementation of a complex corporate automation solution:

o Full .NET support –any piece of C# code can be literally translated into PS syntax

o Remote execution of scripts


· Microsoft invests a lot of resources into the development of this language and it’s definitely worth the time and efforts to learn it. PowerShell will remain the primary scripting language for both Microsoft cloud and on-premises platforms in the foreseeable future. Your PowerShell programming skills will stay relevant if your organization decides to embrace the cloud and buy into Microsoft Azure, as this platform includes Azure Automation feature. This cloud based automation tool is very like SMA and builds upon PowerShell workflows as well.

Anatomy of SMA runbook

The best way to see how SMA works is to examine some practical example, such as the Internet access provisioning scenario described in the previous post. In that post I discussed how SharePoint workflow handles the approval process and then prepares to hand over the processing to SMA. The SharePoint workflow prepares arguments to be passed to the SMA runbook (the trickiest part), sets some HTTP headers and then fires up an HTTP POST request to the SMA web service to start the runbook. Now let’s see how this SMA runbook is designed.

Figure 1 — SMA runbook in browser

As you can see, I work with the SMA runbooks in a browser via a nice-looking web portal, which is a part of the Windows Azure Pack package. However, in the newest version of SMA 2016 there is an alternate way of authoring runbooks — via PowerShell ISE (standard PS code authoring tool) with a special add-on.

Let’s examine the example runbook “Sharepoint-InternetAccessForm-GrantAccess” more closely:

1. It starts with a PowerShell workflow declaration statement, specifying the name of this runbook. There is an ambiguity between the two terms “workflow” and “runbook”, but you may remember that “SMA runbooks” are essentially “PowerShell workflows” on steroids with additional features made available by the SMA hosting, so in many contexts these two terms are interchangeable. I prefer to call this thing a “runbook” when working in SMA, because it’s the term from the SMA glossary.

2. The top level runbook code block starts with a curly bracket. Which goes into this code block looks like a proper PS code. However, all these statements and expressions in this code block are not executed directly by the PowerShell interpreter but are instead compiled into an XAML markup which defines a workflow hosted in the Windows Workflow Foundation engine. Later in this post I’ll call this kind of “pseudo PowerShell” code block a “WF context”. Please note that in workflow context you can only use a subset of the standard PowerShell cmdlets and expressions and there are also some specific cmdlets and additional options for common cmdlets only available in this context (see reference #8 for more details).

The first few lines in the workflow code block starting with “Param” statement declare the input parameters for this runbook. How the values for these parameters will be supplied depends on the way in which the runbook is started. There are several ways to start an SMA runbook, each with its own mechanism for passing arguments to the runbook parameters:

3. Write-Output statements in the WF context look just like the regular PowerShell cmdlets. But they are actually just facades for Windows Workflow Foundation activities which sometimes behave quite different from their PowerShell counterparts. Where standard Write-Output statement in PowerShell interpreter writes to the output stream (which is console or command prompt in many cases), the same command in the WF context saves all output in the SMA database and it is possible to view it afterwards in the browser window.

4. In the WF context it is possible to use the Assets feature of SMA for secure retrieval of the credentials (usually username/password pairs) which were previously entered via the SMA web interface and stored in its database in an encrypted form. This is not just a convenience, but also a very important security feature, because it offers an easy way to get rid of all those plain text passwords found in many scripts. The Assets feature can also be used to define variables centrally at the SMA service level via its web GUI and then reference these variables from one or many runbooks.

5. As we’ve seen before, all these PowerShell-looking commands from the beginning of the runbook and up to this point are not a real PS code and they are quite limited in what they can do. So, when some actual work must be done at last, a real PowerShell session must be launched and then the whole power of this scripting platform will come into play. The InlineScript WF context statement does just that — launches a PowerShell session and executes the specified code block with regular PowerShell cmdlets and statements in this session.

6. Very often we will need to access some data from the WF context from inside the PowerShell session that we’ve started by invoking the InlineScript statement. As the WF code and the code in the PowerShell session are executed in separate contexts, we need to use a special syntax with the “Using” keyword for referencing WF scope variables from the InlineScript block.

7. The regular PowerShell code is used to do the actual work. If you just copy the contents of the InlineScript code block and try to paste and execute it in a normal PowerShell window, it will probably just work, complaining only about those WF scope variables referenced via the “Using:” constructs.

The rest of this PowerShell runbook contains all technical steps necessary to add the user specified by the “userName” runbook parameter to the groups specified by the “requestedAccesses” parameter. The actual cmdlets used for this task are well known to any experienced Active Directory admin and the whole groups modification script is quite trivial, but there is one very important aspect specific to SMA. The PowerShell session defined by the InlineScript is hosted on a SMA runbook server and has direct access only to the local resources (files, processes, .NET objects etc.) on this server. But to make changes in Active Directory, Exchange, SharePoint and other IT systems, we will need to connect from the PowerShell session running on the SMA runbook server to other servers in the network and carry out some actions remotely. There are different ways to accomplish this and such remote scenarios often involve complex configuration, so I think this topic’s more than worth a separate post. Then look in the next part for the description and comparison of DCOM/RPC, WMI and WinRM protocols, recipes for remote PowerShell invocation and some practical advice on the configuration of SMA-enabled server environments using AD Group Policy.


1. Windows Azure Pack and it’s licensing

2. How to buy System Center 2016

3. How to deploy Service Management Automation

4. PowerShell Script Runbook Support in System Center Service Management Automation 2016 (SMA) — Part 1

5. Windows PowerShell: What is Windows PowerShell Workflow

6. Windows PowerShell: Windows PowerShell: PowerShell scripts versus PowerShell workflow

7. Introducing Service Management Automation ISE add-on

8. Syntactic Differences Between Script Workflows and Scripts

9. SMA Capabilities in Depth: Runbook Input, Output, and Nested Runbooks

10. Invoking SMA Runbooks via REST