Starting and waiting for an SMA runbook from remote computers

If you are going to manually trigger a SMA runbook from a single computer you’ll want to install the Powershell module from the Orchestrator setup splash screen by clicking on PowerShell administration under Service Management.

However in order to deploy this to a team of administrators we’ll want to automate this. According to the technet library we should be able to use the command:

msiexec.exe /i PowershellModuleInstaller.msi /qn

We can get this PowershellModuleInstaller.msi file from the System Center 2012 R2 Orchestrator 2012 R2 iso in the SMA subfolder.

Once the module is installed, we can import it as follows:

import-module Microsoft.SystemCenter.ServiceManagementAutomation

In order to see all of the command-lets exposed with this module, we can run:

Get-Command -Module Microsoft.SystemCenter.ServiceManagementAutomation

This returns:

CommandType     Name                                               ModuleName
-----------     ----                                               ----------
Cmdlet          Edit-SmaRunbook                                    Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaAdminConfiguration                          Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaCertificate                                 Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaConnection                                  Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaConnectionField                             Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaConnectionType                              Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaCredential                                  Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaJob                                         Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaJobOutput                                   Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaLicense                                     Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaModule                                      Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaRunbook                                     Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaRunbookDefinition                           Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaRunbookWorkerDeployment                     Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaSchedule                                    Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Get-SmaVariable                                    Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Import-SmaModule                                   Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Import-SmaRunbook                                  Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          New-SmaConnection                                  Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          New-SmaRunbookWorkerDeployment                     Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Publish-SmaRunbook                                 Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Remove-SmaCertificate                              Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Remove-SmaConnection                               Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Remove-SmaCredential                               Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Remove-SmaModule                                   Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Remove-SmaRunbook                                  Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Remove-SmaSchedule                                 Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Remove-SmaVariable                                 Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Resume-SmaJob                                      Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Set-SmaAdminConfiguration                          Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Set-SmaCertificate                                 Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Set-SmaConnectionFieldValue                        Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Set-SmaCredential                                  Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Set-SmaLicense                                     Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Set-SmaRunbookConfiguration                        Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Set-SmaSchedule                                    Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Set-SmaVariable                                    Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Start-SmaRunbook                                   Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Stop-SmaJob                                        Microsoft.SystemCenter.ServiceManagementAutomation
Cmdlet          Suspend-SmaJob                                     Microsoft.SystemCenter.ServiceManagementAutomation

To start a job, simply use the start-smarunbook cmdlet…this returns a job ID so you can track it down:

$strJobID = start-smarunbook -webserviceendpoint $strWebserviceEndPoint -name "RunbookName" -parameters $hashParams

Notice that each cmdlet requires you to specify your webserviceendpoint. Typically this will be https:// followed by the name of your server running the SMA management service. The -name field is simply the the name of your runbook. The -parameters field is a hash table of all of the parameters required by your runbook. Take note that the type of each key value pair in the parameter must match or be convertible for the matching parameter in your runbook. For example, if the parameter in your runbook is [string]$strComputer, the key pair in the hashtable should be: strComputer = [string]$string. The types should match….however, there are some anomalies for this such as runbooks which take hashtables as parameters. See this blog post concerning this topic.

Once you’ve started the runbook, you may want to wait for the runbook to complete before continuing:

Function Wait-SMAJob{
param ([string]$strJobID,[string]$strWebserviceEndPoint)

	[string]$strRBResult = $null

    #Wait for the job to finish
	Do
	{
		Try
		{
			Start-Sleep 1
			$objJob = (Get-SmaJob -WebServiceEndpoint $strWebserviceEndPoint -Id $strJobID)
			$strJobStatus = $objJob.Jobstatus
		}
		Catch [Exception]{
			$strException = $_.Exception.Message
			$strException = "Failed to get sma runbook status...with error ${strException}"
		}
	}
	While (($strJobStatus -notin @("Failed", "Stopped", "Completed", "Suspended")) -and (!($strException)))
		
	#Get the job output....job is finished
	Try
	{
		$JobOutputErrors = Get-SmaJobOutput -WebServiceEndpoint $strWebserviceEndPoint -Stream "Error" -id $strJobID
		$JobOutputWarnings = Get-SmaJobOutput -WebServiceEndpoint $strWebserviceEndPoint -Stream "Warning" -id $strJobID
		$JobOutput = Get-SmaJobOutput -WebServiceEndpoint $strWebserviceEndPoint -Stream "Output" -id $strJobID
        $hashJobProps = @{
            "JobID"=$strJobID;
            "Status"=$strJobStatus;
            "Errors"=$JobOutputErrors;
            "Warnings"=$JobOutputWarnings;
            "Output"=$JobOutput
        }
	}
	Catch [Exception]{
		If ($objJob.JobException)
		{
			$strException = "Exception: " + $objJob.JobException
		}
		else
		{
			$strException = $_.Exception.Message
			$strException = "Failed to get sma runbook output...with error ${strException}"
		}
        $hashJobProps = @{
            "JobID"=$strJobID;
            "Status"=$strJobStatus;
            "Errors"=$strException;
            "Warnings"="";
            "Output"=""
        }
	}
    
    $objJobStatus = New-Object -TypeName PSObject -Property $hashJobProps
	Return $objJobStatus
}

This function will nicely wait for the job to finish, and then return an object with the jobid, status, output, warning, and errors.

$jobstatus = Wait-SMAJob -strJobID $strJobID -strWebserviceEndPoint $strwebserviceendpoint

Of note, the Output/Errors/Warnings properties are collection properties which hold more information about the associated output stream. In order to get the text from this stream, reference the streamtext sub-property.

$jobStatus.Warnings.StreamText

And example output:

489030c2-114d-4f4a-8ee9-6d12fea72687:[localhost]:The names of some imported commands from the module ‘tmp_4v5ml5cq.1ue’
include unapproved verbs that might make them less discoverable. To find the commands with unapproved verbs, run the
Import-Module command again with the Verbose parameter. For a list of approved verbs, type Get-Verb.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s