Invoking SMA Runbooks via REST | Laurie Rhodes' Info

Service Management Automation Runbooks are PowerShell workflows. Workflows allow parameters to be passed in at the time of execution and are essential to any infrastructure automation.

Service Management Automation runbooks can be initiated through the Azure web portal which creates appropriate input fields for the data types used in the “param” section of the workflow. With the workflow above, two string input fields are displayed that match the “FIRSTNAME” and “LASTNAME” variables.

Invoking this runbook via REST (starting directly via a submitted web POST) requires the runbook GUID, then a POST request can be sent to the Orchestrator web service containing parameter information. The GUID for my runbook can be obtained by making a GET request directly from the hosting Service Management Automation server. With the URL below you can see how a request for runbook details is made, filtered by the name "runbookparametersexample".

https://smaserver.domain.com:9090/00000000-0000-0000-0000-000000000000/Runbooks()?$filter=RunbookName%20eq%20%27runbookparametersexample%27

Remember that spaces and special characters are translated when they are included in a URL so “%20” is a space an “%27” is a single quote mark. Web Browsers will translate these characters automatically so

https://smaserver.domain.com:9090/00000000-0000-0000-0000-000000000000/…()?$filter=RunbookName eq ‘runbookparametersexample’

… is exactly the same!

The webserver will provide an XML based response where the Id node holds the GUID used to create the POST request.

eg.

https://smaserver.domain.com:9090/00000000-0000-0000-0000-000000000000/…

SMA POST Body

The body of the request uses JSON to hold the values of the parameters that are about to be passed. The PowerShell code below shows how the text parameters are presented in JSON.

[[powershell]]
$URI =  “https://smaserver.domain.com:9090/00000000-0000-0000-0000-000000000000/Runbooks(guid'2e32df92-2364-4c1a-bfea-e1ba45baa79f')/Start”

$credentials = New-Object System.Management.Automation.PSCredential ("domain\username",(ConvertTo-SecureString "Password1234" -AsPlainText -Force))

$Headers = @{“Accept” = “application/atom+xml,application/xml”}

$Body = @"

{"parameters":[
{"__metadata":{"type":"Orchestrator.ResourceModel.NameValuePair"},"Name":"FirstName","Value":"Laurie"},
{"__metadata":{"type":"Orchestrator.ResourceModel.NameValuePair"},"Name":"LastName","Value":"Rhodes"}
]}
"@


$Response = Invoke-RestMethod -Uri $URI -Body $Body -Method Post -Headers $Headers -Credential $credentials -ContentType  “application/json;odata=verbose” -Verbose

$Response.Start.'#text'

[[/powershell]]

The submitted Job may be viewed via the SMA / Azure portal… as expected, the passed parameters have been processed as expected.

If we were calling runbooks from a Windows host, we could simply use PowerShell cmdlets to do the same thing. PowerShell will be quietly querying the SMA web service to find the runbook GUID and it will create the JSON body for a request just as above.

[[powershell]]
Start-SmaRunbook -WebServiceEndpoint https://smaserver.domain.com -Port 9090 `
-Name "sample-using-runbookparameters" -Parameters @{"FirstName"="Fred";"LastName"="Rhodes"}
[[/powershell]]

As Service Management is integrating a wide range of technologies, it’s important to know how the requests are formed without using Windows based cmdlets.

Name Value Pairs

The web service (port 9090) is documented by Microsoft to accept “Name Value Pairs” as parameters when invoking runbooks. With the example of passing two text fields, calling a runbook is without issue.

Microsoft provide an example runbook for specifying parameters titled “Sample-Using-RunbookParameters” although the sample uses multiple data types for parameters.

The use of different data types allows the web portal to provide a rich interface based purely on the type of parameter being used. The Microsoft example shows how date controls, buttons and string (and integer) fields can be called for and presented to the person initiating the script.

If we construct a POST request, using JSON and listing “Name Value Pairs” with the Sample-Using-RunbookParameters example, we quickly discover that data types other than strings cause exception errors.

The “Catch 22” is that SMA (on port 9090) only currently supports the initiation of runbooks using Name Value Pairs (Orchestrator.ResourceModel.NameValuePair). For coders, Name Value Pairs are a type of list or a dictionary of string values. All names and values are passed as strings and there is no third field to declare what type of data they are supposed to represent. As a result, by only supporting Name Value Pairs for runbook inputs, runbooks are forced to only use string inputs when processes are to be initiated via REST.