If you have been reading about and testing the new features from System Center 2012 R2, you’ve probably heard about Service Management Automation , a new automation engine based on PowerShell Workflows and shipping as part of System Center 2012 R2 Orchestrator, along with the existing Orchestrator engine.
If you haven’t yet looked closely at SMA, fear not: My colleagues Charles Joy and Jim Britt have also blogged extensively about this feature in this blog post series . And we also highlighted this post from the Orchestrator & SMA team. <- (Thanks Bruno Saille)
In this blog post we are going to discuss some of the fundamentals for Runbook management inside System Center 2012 R2 Orchestrator – Service Management Automation or SMA. We are going to walk through the steps to enable you to quickly create a Runbook, enable logging, and setup a schedule for starting Runbook jobs.
Creating a new Runbook with Quick Create
From the Automation resource in the Windows Azure Pack Service Management Portal, select New\Runbook\Quick Create\Create a new Runbook. Here you can provide a Name for the Runbook, a Description, and relevant Tags that will allow you to categorize the Runbook based on your business requirements. Keep in mind that the name of the Runbook cannot be changed, but you will be able to change the description and tags later from the Configuration tab. It’s generally a good practice to follow the PowerShell verb-noun naming convention. In our example, we’ll use “Configure-Runbook”.
When ready, click Create and the new Runbook will be created and displayed in the Runbooks list. Consider this “Runbooks” view your own private library of Runbooks you can use to automate various resources. You can perform basic operations on your Runbooks from this view including starting, importing, exporting or deleting. We will cover some of these later in the post.
The Runbook is now created in the Runbooks view and is listed as New. At this point you are now able to select the Runbook and select Author to begin authoring the Runbook.
Next, the UI will tell you, “There is no published version of this runbook. Click DRAFT to author and publish this runbook.” Click DRAFT and note SMA inserts the following for you:
You are now able to start authoring your Runbook using standard PowerShell Workflow constructs. Note that PowerShell Workflows are different from standard PowerShell scripts. You can read more about PowerShell Workflows here .
Importing a Runbook
If you already have a (.PS1) PowerShell Workflow, or Runbook – that you wrote or discovered earlier, importing it into your Runbooks Library is easy. You can either use the “Import” function on the command bar or use the Microsoft.SystemCenter.ServiceManagementAutomation PowerShell Module included on your System Center 2012 R2 – Orchestrator install media.
Here is how it works:
Parameter Set: Default
Import-SmaRunbook -Path <String> -WebServiceEndpoint <String> [-AuthenticationType <String> ] [-Credential <PSCredential> ] [-Port <Int32> ] [-Tags <String> ] [-Confirm] [-WhatIf] [ <CommonParameters>]
For example: PS C:\> Import-SmaRunbook -Path "./Runbook01.ps1" -WebServiceEndpoint "https://contoso.com/app01"
Want to know more? Follow the link to the Cmdlet Reference on TechNet. Otherwise just use the Import button the command bar and navigate to your .PS1 file.
Sorting and Filtering Runbooks and Jobs
The Runbooks view shows us specific details about the jobs that have been started. Users have the ability to sort by Name, Last Job Start, Last Job Status, Jobs, Authoring or Tags – let’s talk about some of these in more detail.
· Name – Allows users to sort by Runbook name, for example A-Z or Z-A.
· Last Job Start – Allows users to sort by the last Job that was started by the Runbook in the following format (MM/DD/YYYY HH:MM:SS AM|PM). Note the last job start could also be “None” indicating the Runbook has never started a job.
· Last Job Status – Allows users to view the status of the last job. For example, my job can be in one of several finite states including Suspended, Completed, Failed, Queued, Running or Starting.
· Jobs – Allows user to view the number of jobs the Runbook started.
· Authoring – Allows user to view the current status of the Runbook definition. For example, Runbook in the “In edit” can be executed in “Test” mode while a Runbook in the “Published” state can be started in “Production” mode.
o Draft – A non-production version exists that is actively being edited
o Published – A production version exists that can start jobs and is not actively being edited
o In Edit – A production version exists as well as a Draft version that is currently being edited
· Tags – Allows users to set metadata about a particular Runbook. For example maybe a user wants to categorize her runbooks by production or test then by workload, technology. Her tag may look like: PROD: Windows Azure, IaaS or TEST: VMM, Library. These tags are free-formed allowing the user to provide whatever makes sense.
· Filter - Selecting the magnifying glass icon on the top-right, also allows users to filter on either the Name or Tags column in the Runbooks view.
· Range - Lastly, users are also able to use the top level filtering mechanism for viewing Job Status from X point in time to Y point in time relevant to the Job Status (above).
Authoring a New Runbook
Are you ready to start authoring Runbooks?
Select the Runbook from the Runbooks view to begin authoring your Runbook. From here you can see SMA has automatically added “workflow name { }”. Insert the Runbook definition as seen below. Once you are satisfied with the definition you can insert an Activity , another Runbook or a Setting like a Variable or Connection . These are Assets you can manage from the Assets tab, globally for your Automation service. When ready, you are able to Test or Publish the Runbook.
1: workflow configure-runbook {
2:
3: Write-Verbose -Message "Searching the Application Event Log..."
4: Write-Progress -Activity "Runbook in progress..."
5: Write-Debug -Message "Cannot open file, access denied"
6:
7: }
Configuring a Runbook
Once you are satisfied with the Runbook, you can easily configure it using the Configure tab of the Runbook.
From the Configure tab you are able to modify settings specific to the Runbook you created. For example you can change the Description or Tags .
Want to know more? Read the TechNet article covering Runbook Concepts . This article covers in details concepts specific to Runbook Execution, Permissions, Windows PowerShell Workflows, Activities, Integration Modules, Parallel Execution, Checkpoints, Suspending a Runbook, Inline Script and Starting a Runbook from another Runbook.
In our example we are going to illustrate several configurable logging options, specifically Log Debug Records , Log Verbose Records and Log Progress Records . Set these options to “True” to turn on all logging levels for your Runbook.
Let’s use a real example to see how this can help us fix a workflow that may not be running as expected. In this example we are going to use the Set-AzureVMSize cmdlet to update the instance size of an existing virtual machine. The code would look something like this:
1: workflow OaaS-UpdateVMSize-Azure
2:
3: {
4: <#
5: .SYNOPSIS
6: This workflow will dynamically update the size of your IaaS virtual machine
7: using the Set-AzureVMSize cmdlet.
8: .DESCRIPTION
9: Use this workflow to connect to your default Windows Azure Subscription and
10: update an IaaS virtual machine to a support virtual machine size, for example
11: Extra Small, Small, Medium, Large, ExtraLarge, A5, A6 or A7.
12: .PARAMETER VirtualMachineName
13: This mandatory parameter allows the user to specify a virtual machine name.
14: .PARAMETER ServiceName
15: This mandatory parameter allows the user to specify a cloud service name
16: the virtual machine will belong to.
17: .PARAMETER InstanceSize
18: This mandatory parameter allows the user to specify an instance size
19: for the virtual machine.
20: Valid values are outlined in the [ValidateSet] section of the parameter.
21: .NOTES
22: Author: @justininc
23: Date Published: 12/09/2013
24: Version: 1.0
25: #>
26:
27: param (
28: [parameter(Mandatory=$true)]
29: [ValidateSet("ExtraSmall","Small","Medium","Large","ExtraLarge","A5","A6","A7")]
30: [String]$InstanceSize,
31:
32: [parameter(Mandatory=$true)]
33: [String]$VirtualMachineName,
34: [parameter(Mandatory=$true)]
35:
36: [String]$ServiceName
37: )
38:
39: inlinescript {
40: Import-Module "C:\Program Files (x86)\Microsoft SDKs\Windows Azure\PowerShell
41: \Azure\Azure.psd1"
42: }
43:
44: inlinescript {
45: Select-AzureSubscription -SubscriptionName 'Visual Studio Ultimate with MSDN'
46: -Default
47: }
48:
49: inlinescript {
50: Get-AzureVM -ServiceName $Using:ServiceName -Name $Using:VirtualMachineName |
51: Set-AzureVMSize $Using:InstanceSize | Update-AzureVM
52: }
53:
54: Write-Debug -Message "You entered Instance Size $InstanceSize, which is an invalid size.
55: Valid sizes are ExtraSmall, Small, Medium, Large, ExtraLarge, A5, A6, or A7"
56:
57: }
*Note you don't have to put all these into separate InlineScript blocks <-Thanks Aleksandar Nikolic for the feedback!
Note the [ValidateSet] type for the InstanceSize parameter. Windows Azure will only accept these values for virtual machine sizes. For example, what if we accidentally typed “Xsmall” instead of the valid “ExtraSmall” string value as shown below?
If we start a job from the runbook we get a Debug event with the following description in the job details, History view:
357924a4-942a-4f0a-90f7-79c1533180b3:[localhost]:You entered Instance Size XSmall, which is an invalid size. Valid sizes are ExtraSmall, Small, Medium, Large, ExtraLarge, A5, A6, or A7
Great, because we have Log Debug Records enabled and a little error handling in the Runbook, we are able to easily determine what the issue is and re-submit the job with the proper size.
Starting a Runbook
Starting a Runbook can be accomplished using the SMA user interface or programmatically using the Start-SmaRunbook cmdlet. To start a Runbook from the user interface, navigate to the Runbooks view, select a Runbook and click Start from the command bar. In our example we are using parameters that are presented to the user when the job is started. To learn more about starting the Runbook using the Start-SmaRunbook cmdlet, see the documentation below.
Parameter Set: ByRunbookName
Start-SmaRunbook -WebServiceEndpoint <String> [-AuthenticationType <String> ] [-Credential <PSCredential> ] [-Name <String> ] [-Parameters <IDictionary> ] [-Port <Int32> ] [-ScheduleName <String> ] [-Confirm] [-WhatIf] [ <CommonParameters>]
Parameter Set: ByRunbookId
Start-SmaRunbook -WebServiceEndpoint <String> [-AuthenticationType <String> ] [-Credential <PSCredential> ] [-Id <String> ] [-Parameters <IDictionary> ] [-Port <Int32> ] [-ScheduleName <String> ] [-Confirm] [-WhatIf] [ <CommonParameters>]
For example:
PS C:\> Start-SmaRunbook -WebServiceEndpoint https://localhost -Name "Runbk01" -Parameters @{"StringParam"="Value"; "IntParam"=2}
After providing the correct parameters for the Runbook, the job finishes successfully and you are able to review the summary, input parameters and output from the job Dashboard view. View the History tab as discussed earlier to get more details about the job execution.
After you start a Runbook, an instance of a Runbook is created, called a job. Click on the jobs page of the Runbook to see all jobs of a Runbook that have run. If you click on a job and select the History tab, you can view specifics about the logging you enabled earlier. For example, because we enabled all three log levels, we can see Progress, Verbose and Debug output about our job.
You can further select one of the Job Records (an item in a Progress, Verbose, Debug, or Output logging stream) to view the details and full text of that record.
Scheduling a Runbook
In SMA you are also able to compose a schedule. From the Runbook we created earlier select “Add a new schedule”
Provide a name and description.
And lastly, select your schedule preferences for example Type, Start Time, Schedule Expires On and Recurrence.
You can then easily view the schedule and use it for another Runbook if needed by selecting “Use and existing schedule” from the previous screen.
Want to use the SMA Cmdlets to create a Schedule? Use the Set-SmaSchedule cmdlet.
For Example:
PS C:\> $StartDate = Get-Date
PS C:\> $EndDate = Get-Date -Day 12 -Month 6 -Year 2023
PS C:\> Set-SmaSchedule -StartTime $StartDate -ExpiryTime $EndDate -Name "Schedule01" -ScheduleType "DailySchedule" -WebServiceEndpoint
https://contoso.com/app01
More Information
Automation–Service Management Automation–SMA Runbook Toolkit Spotlight–SMART for Runbook Import...