Hey Readers! This post will introduce you to a couple of useful SMA Runbooks to add to your “SMA Utility Belt”. First things first – go here to read about SMA if you are unfamiliar with the solution: http://aka.ms/IntroToSMA.


Use Case

This post discusses how to leverage three Runbooks to improve the Tenant experience as they request resources in the WAP portal. The process I’ll be covering breaks down in the steps outlined below.

  1. WAP / SPF event invoked Runbook is triggered on a plan creation event (Tenant subscribes to something and a Runbook fires)
  2. Notification [SMTP email] sent to the recipient [admin in this case] to be patient (gathers up some information useful for the targeted recipient and emails them an in progress notification)
  3. VM Host is refreshed
  4. Notify recipient on job competition that the job is complete. (success or failure notification that contains useful data for the targeted recipient on how to proceed)

A Visual Aid to Drive Home What I’m Talking About

image

Note   Red box denotes what I’ll be covering in this blog post. Obviously overkill to have a VM Host refreshed during a plan subscription.  Get fancy and use this example to build from Hot smile.

Two Very Important Notes

  1. This blog post is showing how to tie automation into a plan subscription leveraging SPF tagging with an SMA Runbook.  It is doubtful you’ll ever kick off a VM host refresh during a plan subscription and this example is provided only to show you some simple automation to illustrate our next important point.
  2. This blog post is primarily about how you can leverage email notification and SC Job monitoring to improve the overall experience during some form of automation leveraging SMA in a scenario requiring it.

Runbooks for Use Case

  • Invoke-SubscriptionCreateRunbook: Kicks off an SCJob and returns a job ID
  • Send-SmtpNotification: Sends an email on start and completion
  • Monitor-SCJobStatus: Monitors the SCJob till complete or max time met

Published here

BC-DLButtonDark

Note     XML and PS1 files are both provided in the download.  Use SMART for Runbook Import and Export to leverage the provided XML files in the above download for an enhanced experience in importing the example solution into your SMA environment.


Invoke-SubscriptionCreateRunbook

We start with the Invoke-SubscriptionCreateRunbook, this would essentially be the Runbook that you will tag with “SPF” to be executed on a create event for a plan.  Shown as the Dispatcher Runbook in the graphic above, this dispatcher Runbook makes the decision on what to do depending upon what the tenant selected to do.  Since any Runbook that is associated with the Create event will fire when that event is triggered, a dispatcher Runbook is leveraged above as the single authority on actions.  You build your knowledge here on how to react to requests.

001
002
003
004
005
006
007
008
009
010
011
012
013
014
015
016
017
018
019
020
021
022
023
024
025
026

workflow Invoke-SubscriptionCreateRunbook
{
    $VMMServer = Get-AutomationVariable -Name 'VMM Server'
    $VMHost = Get-AutomationVariable -Name 'VMHost' 
    $SMTPEmailServer = Get-AutomationVariable -Name 'SMTPEmailServer'
    $SMTPEmailFrom = Get-AutomationVariable -Name 'SMTPEmailFrom'
    $SMTPEmailCC = Get-AutomationVariable -Name 'SMTPEmailCC'
    $SMTPEmailTo = Get-AutomationVariable -Name 'SMTPEmailTo'
  
    Send-SMTPNotification -SendNotificationType "Initial-Notification" -SMTPEmailFrom $SMTPEmailFrom -SMTPEmailTo $SMTPEmailTo -SMTPEmailServer $SMTPEmailServer -SMTPEmailCC $SMTPEmailCC -VMHost $VMHost
    "Initial notification sent"
       
    "Refreshing VM Host"
    $NewSCJobID = InlineScript{
        Get-SCVMMServer -Computername $Using:VMMServer | Out-Null 
        Read-SCVMHost -VMHost $Using:VMHost -JobVariable "NewRefreshJob" -RunAsynchronously | Out-Null
        $NewRefreshJob.ID.Guid
    }
    "Job ID = $NewSCJobID"
   
    $RefreshState = Monitor-SCJobStatus -SleepDuration 20 -SCJobID $NewSCJobID -MaxRunTime 3600
    Send-SMTPNotification -JobState $RefreshState -SendNotificationType "Complete-Notification" -SMTPEmailFrom $SMTPEmailFrom -SMTPEmailTo $SMTPEmailTo -SMTPEmailServer $SMTPEmailServer -SMTPEmailCC $SMTPEmailCC -VMHost $VMHost
    "Completion notification sent"
}


PARENT RUNBOOK SECTIONS

There are essentially four main sections that this Runbook is executing

  1. Send initial notification email stating that things are in progress
     image
  2. Refresh the VM Host (and generate a SCjobID to use for our next step)
     image
  3. We fire off the Monitor Runbook using that job ID as a parameter to monitor
     image
  4. Then finally we send an email upon completion or timeout
    image

INVOKE-SUBSCRIPTIONCREATERUNBOOK WORKFLOW VARIABLES

The Invoke-SubscriptionCreateRunbook leverages the following variables shown below.

image

Note Regarding Variables    The above variables should be reviewed and potentially modified in the XML or PS1 file before importing to ensure they do not conflict with existing assets already within your SMA environment.  I’m not going to go into great detail on the above variables since they should all be fairly self explanatory.  If you import these Runbooks with the SMART for Runbook Import and Export, it will create the variables (as defined by me) that will need to be updated with your environment settings.  Alternatively, you can update this Runbook (once imported) to leverage static values in place of the SMA variables for testing.

Best Practice Note    As you can see, I’m specifying the variables in what I would call the parent or process Runbook (at the top level).  You can then leverage these throughout your nested Runbooks and only require a change at the top most Runbook when required. Each nested Runbook would then receive these defined variables as parameters provided by the parent.

Associate the Runbook into your subscription operations as shown below.

image
Note    Runbooks are associated to events in WAP under the VM CLOUDS custom resource tab and then under AUTOMATION

Additional Note     Tagging SPF on the Runbook occurs on the CONFIGURE tab of the Runbook shown above before it will show up as an option in the Runbook dropdown.  Only one Runbook for this type of event can be selected (so make it a good one Smile).

image


Send-SmtpNotification

Next, we need a way to send emails to whomever you need to in order to communicate a job starting, completing, failing, etc.  This Runbook is called a couple of times in my example to notify the defined SMTP recipients (once on initial notification and once on completion).  The idea is that this Runbook can be configured in such a way that it can be used as your general notifying Runbook.  Even the subject and body of your email can be parameterized to make this even more flexible of course but will require some rework to make it functional for that scenario.  This at least gets you started with a good working model to build from!

001
002
003
004
005
006
007
008
009
010
011
012
013
014
015
016
017
018
019
020
021
022
023
024
025
026
027
028
029
030
031
032
033
034

workflow Send-SmtpNotification
{
    [CmdletBinding()]
    param
    (
        [string]$VMHost,
        [string]$JobState,
        [string]$SendNotificationType,
        [string]$SMTPEmailFrom,
        [string]$SMTPEmailTo,
        [string]$SMTPEmailCC,
        [string]$SMTPEmailServer
    )

    # Initial Notification
    if($SendNotificationType -eq "Initial-Notification")
    {
        $SMTPSubject = "Your VM Server (" + $VMHost + ") is currently being refreshed"
        $SMTPBody = 
'<h1 style="font-family: arial">Your VM Server is currently being refreshed.</h1>
        <p style="font-size: 12pt; font-family: arial"><b>Status: </b><font color="#0000ff">In Progress</font></p>
        <p style="font-size: 12pt; font-family: arial"><font color="#000000">
        Your VM Server ('
 + $VMHost + ') is currently being refreshed.<br>Please be patient. </font></p>'
    }
   
    # Completion Notification
    if($SendNotificationType -eq "Complete-Notification")
    {
        $SMTPSubject = "Your VM Server refresh for (" + $VMHost + ") " + $JobState
        $SMTPBody = '<h1 style="font-family: arial">Your VM Server refresh ' + $JobSTate + 
'.</h1>
        <p style="font-size: 12pt; font-family: arial"><b>Status: </b><font color="#0000ff">('
 + $VMHost + 
')</font></p>
        <p style="font-size: 12pt; font-family: arial"><font color="#000000">The refresh on your VM Server ('
 + $VMHost + ') ' + $JobState +  '.<br></font></p>'
    }
    send-mailmessage -to $SMTPEmailTo -Cc $SMTPEmailCC -from $SMTPEmailFrom -SmtpServer $SMTPEmailServer -subject $SMTPSubject -body $SMTPBody -BodyAsHTML
}

SEND-SMTPNOTIFICATION WORKFLOW PARAMETERS

The Send-SmtpNotification workflow takes in parameters shown below.

image

  • $VMHost: Somewhat obvious Smile - the server you are working with.  This is a flexible piece where you could change this up and make it whatever you want to pull into your communication but for the example I’m showing here, this is the VM Host server name.
  • $Jobstate: This is actually used in a second email notification to provide success / failure status coming back from the SCJOB
  • $SendNotificationType: This would be a type that is leveraged to indicate which section of the script to fire (logic below).  Add more sections to this to provide more types of notifications.
     image
  • $SMTPEmailFrom: This would be the “from” email address. 
    Note          Remember, this ordinarily needs to be an email that is authenticated and allowed to send email through your SMTP server (unless of course you have an open relay – rare and insecure Smile)
  • $SMTPEmailTo and $SMTPEmailCC: These two are addresses that populate the to and cc lines.  Provided as an example and can be removed and customized to support your need within your organization.
  • $SMTPEmailServer: This would be your SMTP server within your organization such as your Exchange Server that will serve as your email server to send the messages through.

SEND-SMTPNOTIFICATION WORKFLOW OUTPUT (NOTIFICATION RESULTS)

Below you can see an example of the three possible types of notifications you may see.  These are shown with some HTML content to pretty it up but you could certainly reduce these to plain text emails. Details were covered briefly in the $SendNotificationType parameter above. 

Initial email sent indicating things are in process

image

Completion email sent indicating things completed successfully. 

image

Job timeout email indicating that a job exceeded the maximum allowed run time.

image


Monitor-SCJobStatus

This Runbook is used to monitor for the completion of a SC JOB using the ID and taking in a parameter in seconds to determine the looping intervals.  You can easily modify this to adapt to your needs.  Consider this an example that you can add your own logic and return values from.

001
002
003
004
005
006
007
008
009
010
011
012
013
014
015
016
017
018
019
020
021
022
023
024
025
026
027

workflow Monitor-SCJobStatus
{
    param
    (
        [int]$SleepDuration,
        [string]$SCJobID,
        [int]$MaxRunTime           
    )
    if($SCJobID -ne $null)
    {
        $JobEndTime = $null
        Do
        {
            $scjob = Get-SCJob -ID $SCJobID
            $JobEndTime = $scjob.EndTime
            $SleepDurationTotal += $SleepDuration
            $returnStatus = $scjob.Status
            if($SleepDurationTotal -ge $MaxRunTime)
            {
                $JobEndTime = "error"
                $returnStatus = "timed out for the job monitor"
            }
            Start-Sleep $SleepDuration
        } While ($JobEndTime -eq $null)
        $returnStatus
    }
}


MONITOR-SCJOBSTATUS WORKFLOW PARAMETERS

The Monitor-SCJobStatus takes in parameters as shown below

image

  • $SleepDuration: This parameter determines the number of seconds to sleep in between checks. (Example: 5 = 5 Seconds).  Make sure you set this to something that is realistic for your job you are executing.  If you want the instant gratification for a job that takes ~30 seconds, set the sleep to 30 for example.  If it takes ~10 mins, set it to 600 seconds.  You get the idea Winking smile
  • $SCJobID: This is the actual SC Job ID that gets generated in the calling Runbook.  This ID will be what you monitor for completion using $scjob.EndTime to determine when the job is complete.
  • $MaxRunTime: This variable indicates the maximum amount of seconds you want this process to run before it times out and returns (so things don’t run indefinitely).

MONITOR-SCJOBSTATUS WORKFLOW OUTPUT

This workflow should output the completion status of the job that was being monitored.  This would be specific to the job.  (Example: a successful completion of the example job we are monitoring = Complete).


Summary

So in summary of all we’ve talked about

  • Three Runbooks Outlined in this Solution

Invoke-SubscriptionCreateRunbook: Kicks off an SCJob

Send-SmtpNotification: Sends an email

Monitor-SCJobStatus: Monitors the SCJob till complete or max time met

  • Can be customized to plug into other events within WAP
  • Example shows refresh of a VM host.  Use the example to create your own dispatcher Runbook (as explained) to respond to actions within your WAP environment using SMA.
  • BONUS: Download SMART for Runbook Import and Export to make it easier for managing your Runbook imports and exports as well as importing this solution!

Until next time – Happy Automating! Open-mouthed smile


And for more information, tips/tricks, and example solutions for SMA, be sure to watch for future blog posts in the Automation Track on http://aka.ms/BuildingClouds!