By now you’ve probably had a chance to experiment with all the great features of Service Management Automation through the Windows Azure Pack Admin Portal – authoring runbooks and creating assets, starting jobs manually and on schedules, importing integration modules and viewing job output. Now what if I told you, you could do all these things and more easily and programmatically from the command line? Whether you want to run SMA completely headless, or you’re just looking to script a few key actions like bulk runbook import, the SMA PowerShell module is for you.
Getting Started With the SMA PowerShell Module
SMA provides a PowerShell module that is installed with the SMA web service, or that you can install independently on any host to remotely manage your SMA installation:
The SMA PowerShell module provides 40 cmdlets that allow scripting of most of the actions you can perform from the Automation portal in WAP. How dependable are the cmdlets, you ask? Well, the reason the cmdlets are installed as part of the SMA web service is because the SMA web service installer actually uses the SMA cmdlets to perform a number of post-deployment tasks against the web service, such as importing our out of box runbooks and integration modules into SMA, so they are available with no additional effort the first time the user uses SMA.
To check out all the great cmdlet functionality the SMA PowerShell module provides, open up the PowerShell console on a host with the SMA module installed and type:
PS C:\> Get-Command -Module Microsoft.SystemCenter.ServiceManagementAutomation
This will return data on all SMA cmdlets:
To get details on how to use a specific SMA cmdlet, type:
PS C:\> Get-Help Some-Command
But replace “Some-Command” with the SMA cmdlet you’d like more information about. You can optionally add “–Detailed” or “–Full” to get larger sets of information about the cmdlet:
You can also look at the SMA PowerShell Module Cmdlet Reference if you’d rather learn about the cmdlets in a web browser than in a PowerShell console.
How the SMA Cmdlets Work
Running Get-Help on the SMA cmdlets, or looking at the SMA cmdlet reference linked above, you probably noticed that all the cmdlets seem to take a handful of the same parameters –WebServiceEndpoint, Port, AuthenticationType, and Credential. That’s because all of our cmdlets (with one exception, which we’ll talk about later) accomplish their tasks by talking to the SMA web service. The WebServiceEndpoint parameter takes the protocol (HTTP/HTTPS) and IP address or hostname of the web service, the Port parameter takes the port of the web service (defaults to 9090), AuthenticationType dictates whether the cmdlet should use Windows or Basic auth to authenticate to the web service, and the Credential parameter lets you run the cmdlet as another user. If you chose Basic for AuthenticationType, you must provide the Credential parameter as well, since the cmdlets do not know the password of the current user to be able to transfer it using Basic auth. Using all these parameters together looks like this:
PS C:\> Get-SmaRunbook -WebServiceEndpoint https://localhost -Port 9090 -AuthenticationType Windows -Credential $cred
Of course, as long as your SMA web service uses the default port, and the current user you are running the cmdlets as has access to the web service, all you need to provide is the endpoint of the SMA web service for the cmdlet to connect to:
PS C:\> Get-SmaRunbook -WebServiceEndpoint https://localhost
By default, the SMA web service is set up with a self-signed SSL certificate for HTTPS, so your WebServiceEndpoint parameter should use “https://” rather than “http://”. If you want to connect to the SMA web service over HTTP instead, you need to add a new site binding for SMA in IIS. The SMA cmdlets are by default enabled to allow connecting to SMA web services that use self-signed certificates, but if you would like to configure the SMA cmdlets to instead fail if they connect to an SMA instance that is not using a cert signed by a certificate authority, go to C:\Windows\System32\WindowsPowerShell\v1.0\Modules\Microsoft.SystemCenter.ServiceManagementAutomation\Authentication.config and change “AcceptSelfSignedCertificate” to “False”:
Note If you are using a load balancer to enable high-availability across multiple SMA web services, and you want to point the cmdlets at the load balancer endpoint rather than directly at an SMA web service, be aware that you may need to use basic authentication (-AuthenticationType Basic) with the cmdlets so that the user credentials are able to propagate through the load balancer to the SMA web service.
Running the Cmdlets
Here’s an example of running an SMA cmdlet, and the type of output the cmdlets provide:
One thing you’ll notice using the cmdlets is that it can be cumbersome to continually pass the web service connection parameters (WebServiceEndpoint, Port, AuthenticationType, Credential) into each cmdlet. You may be wondering why we don’t provide a single cmdlet to set the connection to the web service, and have all other cmdlets inherently use that connection when they are called so you don’t have to pass these parameters in every time, similar to the Get-SCVMMServer cmdlet of the Virtual Machine Manager PowerShell module, or the Select-AzureSubscription cmdlet of the Windows Azure PowerShell module. We wanted to make sure the SMA cmdlets were incredibly simple to use from within SMA runbooks (more on that later), and doing this meant we needed each cmdlet to be able to function completely independently of other cmdlets. PowerShell Workflow can run cmdlets written in the same workflow in separate PowerShell sessions, which means any cmdlet depending on some state being previously written to the session it is running in may fail. The way around this is to run these types of cmdlets within an InlineScript activity, but for the SMA cmdlets we decided we wanted full compatibility with PowerShell Workflow, since we provide an engine that runs PowerShell Workflows. If we don’t provide a PowerShell module that works perfectly in PowerShell Workflow, who will!
Luckily, there is an easy way to pass these parameters into each SMA cmdlet without having to write them out every time – splatting. Splatting allows you to define a set of parameters as a hashtable, and pass that set of parameters to any cmdlet. From the below, you can see this makes it super easy to add any SMA web service connection parameters to your SMA cmdlets:
Additional Functionality
While most of the SMA PowerShell cmdlets serve to provide feature parity with the SMA portal via a scripting interface, the module also provides cmdlets for various administrative actions that can’t be done from the portal today:
Admin Configuration
The SMA PowerShell module ships with two cmdlets, Set-SmaAdminConfiguration and Get-SmaAdminConfiguration , which let you get and set administrative configuration settings of SMA, such as drain time (for graceful shutdown), Customer Experience Improvement Program (CEIP) opt in, and the max age of runbook jobs before they will be purged from the SMA database.
Runbook Worker Deployment
The PowerShell module also provides cmdlets for managing the set of runbook workers configured to run runbooks. The deployment can be managed through the Get-SmaRunbookWorkerDeployment and New-SmaRunbookWorkerDeployment cmdlets. For more information on runbook worker deployments, check out the PowerShell help topic on SMA runbook worker deployments .
SMA Product License
You can also view and change license information for SMA through the cmdlets. Get-SmaLicense returns the expiration date of your SMA installation, useful if you installed SMA as an evaluation version, while Set-SmaLicense lets you enter a System Center product key to move your SMA installation from an evaluation version to the full product version.
Portable Module Generation
The only SMA cmdlet that does not go through the web service is New-SmaPortableModule . This cmdlet lets you generate integration modules, for modules which cannot be imported into SMA otherwise. You can read up more on portable modules and using this cmdlet in this blog post .
Using the SMA Cmdlets in SMA
Another interesting tidbit about the SMA PowerShell module is that it is included as an out of box integration module in SMA, which means you can use SMA cmdlets directly in your runbooks with no extra work. For example, here’s an SMA runbook that starts another SMA runbook asynchronously as a new job, and prints out info on that job:
Summary
Hopefully by now you have a better understanding of all the wonderful things you can accomplish using the Service Management Automation PowerShell cmdlets, and how the cmdlets themselves function. Not only can you use SMA to automate your IT and business processes, you can even automate SMA itself by using these cmdlets! The SMA team is super excited to see the kinds of runbooks and scripts you write to take advantage of the functionality SMA and the SMA PowerShell module provide.
Until next time, happy automating!