SMA Capabilities in Depth: The SMA PowerShell Module

SMA Capabilities in Depth: The SMA PowerShell Module

  • Comments 3
  • Likes

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:

clip_image002

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:

clip_image004

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:

clip_image006

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”:

clip_image008

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:

clip_image009

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:

clip_image011

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:

clip_image013

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!

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • How about using $PSDefaultParameterValues to specify the default parameters for the cmldets shipping with SMA Module, something like below
    $PSDefaultParameterValues =@{"*-SMA*:WebServiceEndPoint"="https://localhost";"*-SMA*:Port"="8080"}

    Regards

  • Hi Dexter,

    Yes that will work as well. The reason I prefer splatting over $PSDefaultParameterValues is because with splatting you can clearly see where the extra parameters are coming from. With $PSDefaultParameterValues, it happens behind the scenes, and someone looking at a cmdlet that is using some PS default parameter values that were set at an earlier time cannot see by looking just at the cmdlet call that it is taking in those parameters from $PSDefaultParameterValues. To that user it may look like the cmdlet doesn't require those parameters at all, when in fact it does. Then if they try to call that cmdlet without those parameters, it will not work for them even though the example they were going off of did work without those parameters.

  • Yeah it abstracts what it does, but makes up with ease it brings to the table.
    I completely agree that someone else looking at the program at first might not get the idea what is being passed behind the scenes.