Automation–SMA Runbook Toolkit (SMART) for Runbook Import / Export–Updated!

Hey readers, well I have just updated the SMART for Runbook Import and Export and this post is all about discussing some of those updates.


What is SMART for Runbook Import and Export You Ask?

First things first – if you don’t know what SMART is – go here Automation–Service Management Automation–SMA Runbook Toolkit Spotlight–SMART for Runbook Import and Export  and get an idea of what you’ve been missing.  Seriously, this solution is ideal if you want to port  Runbooks between environments or just export in complete sets and check into TFS as discussed in this post Automation-Exporting SMA Runbooks to TFS on a Schedule in Windows Azure Pack with SMART!

If you already know what it is and just want to go download it right now without reading the rest click the download button below.

UPDATE

9/23/2014: The SMART Import / Export solution has been combined with the other SMART solutions. Please see the updates as well as the new download link below.

Updated SMA Runbook Toolkit (SMART) download, with new Visualization and Dependency Mapping Tool

BC-DLButtonDark

Note    If you have a previously installed version of this solution, this update (when installed) will overwrite what you have in your existing environment unless you change the options in the Install-SMARTForRunbookImportAndExport.ps1.

image


What’s New and Exciting in this Version?

So there are a handful of useful updates in this version that I think will be worthwhile to download the update.

  • Ability to capture encrypted values from variables and credentials and store them within the XML export file (if run from inside SMA)
  • Ability to create your original credentials with this captured data in the target SMA environment you import them into
  • Minor bug updates

Export Secrets Option (Credentials)

So in the previous version we would export a credential or an encrypted variable but we didn’t export the secret within (encrypted junk).  With this update we have the option now to export encrypted contents and save those in the XML file for import later into another environment or just to have for recovery in case of an issue, etc.  This allows you to quickly get back up and running with your Runbooks / credentials / variables as they were when exported.  The TFS for SMA link above gives you an idea of what you can do there – take that idea and expand.

What’s the secret to the “-ExportSecrets” option? 

Just add a switch (-ExportSecrets $True) in your SMA Runbook for SMART that does your exporting (Invoke-SMARunbookExport is provided as an example)

image

The result looks something like this.  Now you’ll have what you need on the import process to create your credentials properly.

image

Note    Access to the secrets can only happen during the execution of an SMA Runbook (not outside of SMA from PowerShell, not within an InlineScript within an SMA Runbook either btw). Why is this? Because the cmdlets that are leveraged to get access to the secrets are only available in SMA (they just don’t exist in PowerShell outside). This also means that the pure PowerShell scripts that are provided with this solution do not have the option to use ExportSecrets.


Export Secrets Option (Variables)

Just like above, the –ExportSecrets option (when specified) will allow you to also export the encrypted data for variables that are leveraged within the Runbook you are exporting. Even better, you can export string, Int32, DateTime, and Bool.

image

Note     Integers get exported differently depending upon if they are encrypted or not. Encrypted Integers get exported with type Int32 and non-encrypted integers have a type of int. Don’t ask me, I’m just leveraging the data as it is given to me. Just wanted to point this out in case you see the difference in your XML file. Also, if you are wanting to create these values manually in the XML for import – INT and INT32 both work in both scenarios so don’t worry.


Updating Tags when Updating Existing Runbooks

See below (It Takes a Village) but was able to work out some logic to update tags after Runbooks have already been imported into SMA through the web service.  This is pretty slick actually and not too difficult to implement.  Got my web service skills polished up a bit as well so bonus Open-mouthed smile. I’m providing an example (similar to what I used in my script) to help those that are interested in interacting with the web service for SMA.

001002003004005006007008009010011012013014015016017018019020021022023024025026027028029030031032033034035036 $RBName = "Get-ConsoleVersion"$RB = Get-SmaRunbook -Name $RBName -WebServiceEndpoint "https://localhost"$RBID = $RB.RunbookID$RunbookURI = "https://localhost:9090/00000000-0000-0000-0000-000000000000/Runbooks(guid'${RBID}')"$XmlResult = Invoke-RestMethod -Uri $RunbookUri -UseDefaultCredentials$TagResult = "Tag data from SMART XML"[xml]$baseXML = @' <?xml version="1.0" encoding="utf-8"?> <entry xmlns="https://www.w3.org/2005/Atom" xmlns:d="https://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata"> <id></id> <category term="Orchestrator.ResourceModel.Runbook" scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" /> <title /> <updated></updated> <author> <name /> </author> <content type="application/xml"> <m:properties> <d:Tags></d:Tags> </m:properties> </content> </entry> '@$baseXML.entry.content.properties.Tags = [string]$TagResultInvoke-RestMethod -Method Merge -Uri $RunbookURI -Body $baseXML ` -UseDefaultCredentials -ContentType 'application/atom+xml'

 

MORE INFORMATION

Note    This works in SMA as well as outside of SMA with the PowerShell script provided.


Added Logic for Determining if the PowerShell is Running in SMA

See in the (It Takes a Village) reference below but in a “nutshell” this update was required to ensure that the cmdlets that were being called were running from within SMA.  In the end, I wasn’t able to directly leverage this logic since compilation errors occur when the PowerShell cmdlets cannot be found that only exist in SMA.  But! This may be useful for others in the future so I’m posting it below here.

001002003004005006007008009010 #Let's figure out if we are running from an SMA Runbook or in PowerShell nativelyif ($PSPrivateMetadata.JobId){ $RunningInSMA = $True}else{ $RunningInSMA = $False}

Added Support for Importing Credential (secrets) in the Import Process

The previous iteration of this script allowed for the creation of credentials but only with a default user account and password.  The updates provide the ability to formulate your own XML for a Runbook and populate the required fields to allow you to create the credentials on import as expected.  This ensures that you can get up and running immediately with a Runbook with its dependencies (without manual modifications in your SMA environment). So, essentially just provide the required details in your Runbook XML according to the schema below and you’ll be done!

image


BUG Fixes

What? Bugs? Yeah Rolling on the floor laughing

  • Credentials that didn’t exist but were referenced in a Runbook weren’t exported properly
  • DateTime and Int32 types for variables were not properly set on import causing variables to be created as string types (including encrypted ones)

It Takes a Village Smile

So I wanted to call out the great collaboration during this update.  Though the updates seem small, they were thought provoking Winking smile and definitely needed to be done in a way that would support forwards and backwards compatiblity with the cmdlets as much as possible both inside and outside of SMA.

  • Charles Joy (WSSC CAT) – Thank you for being my sounding board and validating where my brain was going here and there!
  • Eamon O’Reilly (Orchestrator PG) – Thank you for the ideas and links to research the web service update added for the tags.
  • Joe Levy (Orchestrator PG) – Thank you Joe for your assistance in plowing through a bit of the magic around getting creds / values out of SMA that are considered “secret”.
  • Anatoli Beliaev (Orchestrator PG) – Anatoli, your idea on using the jobID to determine when I’m running in SMA or in pure PowerShell – genius!
  • Ryan Andorfer (Orchestrator MVP) – Ryan, thanks for the collaboration around the web service updates.  Your example helped me flesh out what I could use for tags.  Without your initial idea, I may not have done it so thank you Smile.

Until next time – Happy Automating! Hot smile


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